# gatsby-plugin-ts

> Typescript support via ts-loader & fork-ts-checker-webpack-plugin + automate codegen

Latest version **3.1.1** (published 2022-02-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-plugin-ts
pnpm add gatsby-plugin-ts
yarn add gatsby-plugin-ts
bun add gatsby-plugin-ts
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.1.1 |
| Published | 2022-02-02 |
| First published | 2019-06-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 12.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 120 |
| Author | Derek Nguyen |
| Maintainers | alvis, d4rek |
| Keywords | gatsby, gatsby-plugin, typescript |

## Links

- npm: https://www.npmjs.com/package/gatsby-plugin-ts
- Repository: https://github.com/d4rekanguok/gatsby-typescript
- Homepage: https://github.com/d4rekanguok/gatsby-typescript#readme
- Issues: https://github.com/d4rekanguok/gatsby-typescript/issues
- npm.io page: https://npm.io/package/gatsby-plugin-ts

## Dependencies (4)

- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.0
- [ts-loader](https://npm.io/package/ts-loader.md) ^9.2.2
- [gatsby-plugin-graphql-codegen](https://npm.io/package/gatsby-plugin-graphql-codegen.md) ^3.1.1
- [fork-ts-checker-webpack-plugin](https://npm.io/package/fork-ts-checker-webpack-plugin.md) ^6.2.10

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 3.1.1 (latest) — 2022-02-02
- 3.1.0 — 2021-11-03
- 3.0.0 — 2021-05-30
- 2.7.3 — 2021-05-30
- 2.7.1 — 2020-04-06
- 2.7.0 — 2020-03-30
- 2.6.1 — 2020-03-27
- 2.6.0 — 2020-03-23
- 2.5.0 — 2020-03-13
- 2.4.0 — 2020-03-04
- 2.3.0 — 2020-03-04
- 2.2.4 — 2020-03-03
- 2.2.3 — 2020-02-23
- 2.2.2 — 2020-02-09
- 2.2.1 — 2020-02-04
- … 16 more at https://npm.io/package/gatsby-plugin-ts/versions

## README

# Gatsby Typescript Plugin

An alternative to the official typescript plugin, with [`ts-loader`](https://github.com/TypeStrong/ts-loader) & automatic type generation for your graphql queries (using [`graphql-code-generator`](https://github.com/dotansimha/graphql-code-generator))

---
## Installation

```
yarn add typescript gatsby-plugin-ts
```

Add this to your gatsby config like any other plugins:
```js
// gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-ts`,
  ]
}
```

---

Unlike the official plugin, you'd have to bring your own `tsconfig.json`.

```bash
# generate a tsconfig if you have none
tsc --init
```

In order for this plugin to work right, you'd need to set your compile options like the following:

```js
  "compilerOptions": {
    "target": "ES2018",    /* or at least ES2015 */
    "module": "ESNext",    /* or at least ES2015 */
    "lib": ["dom"],             /* <-- required! */
    "jsx": "preserve",          /* <-- required! */
    "moduleResolution": "node", /* <-- required! */

    /* for mixed ts/js codebase */
    "allowJs": true,
    "outDir": "./build"    /* this won't be used by ts-loader */
    /* other options... */
  }

```

### Options

|key | default | value |
|---|---|---|
|**typecheck options**|||
|options.tsLoader| `{}` | option to be passed into `ts-loader`. `transpileOnly` is always `true`, since typechecking is handled by `fork-ts-checker-webpack-plugin`. [See ts-loader docs](https://github.com/TypeStrong/ts-loader#options) for more | 
|options.alwaysCheck | `false` | <small>⚠️deprecated </small><br/> By default type checking is disabled in production mode (during `gatsby build`). Set this to `true` to enable type checking in production as well |
|options.typeCheck | `true` | Enable / disable type checking with `fork-ts-checker-webpack-plugin`. |
|options.forkTsCheckerPlugin | `{}` | Options that'll be passed to `fork-ts-checker-webpack-plugin`. For all options, please see [their docs](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin#options)
|**codegen options**|||
|options.codegen| `true` | enable / disable generating definitions for graphql queries|
|options.documentPaths| <pre>['./src/&ast;&ast;/&ast;.{ts,tsx}',<br/>'./.cache/fragments/&ast;.js', <br/>'./node_modules/gatsby-&ast;/&ast;&ast;/&ast;.js']</pre> | The paths to files containing graphql queries. <br/><small>⚠️ The default paths will be overwritten by the `documentPaths` you pass in, so please make sure to include *all* necessary paths ⚠️</small>
|options.fileName| `graphql-type.ts` | path to the generated file. By default, it's placed at the project root directory & it should not be placed into `src`, since this will create an infinite loop|
|options.codegenDelay| `200` | amount of delay from file change to codegen|
|options.pluckConfig| <pre>{ globalGqlIdentifierName: "graphql", modules: [ { name: 'gatsby', identifier: 'graphql' } ] }</pre> | options passed to [graphql-tag-pluck](https://github.com/ardatan/graphql-toolkit/tree/master/packages/graphql-tag-pluck) when extracting queries and fragments from documents |
|options.failOnError (2.5.0)| `process.env.NODE_ENV === 'production'` | Throw error if the codegen fails. By default only apply to production builds.
|options.codegenConfig (^2.7.0)| `{}` | Add config directly to `graphql-codegen`. These key-value config will be applied to every `graphql-codegen` plugins. See [graphql-codegen docs on the config field](https://graphql-code-generator.com/docs/getting-started/config-field) |
|options.codegenPlugins (^2.7.0)| `[]` | Add additional plugins to `graphql-codegen`. We use the same format as Gatsby's. See example usage below.
|options.additionalSchemas (^2.6.0)| <pre>[]</pre> | array of additional schemas (other than the schema used by gatsby queries) for which types should be generated for. This is useful when you use client-side queries (e.g. with apollo-client) where you are querying another schema/endpoint |

## Example Setup

### Basic

```js
module.exports = {
  plugins: [
    `gatsby-plugin-ts`,
  ]
}
```

### Custom Output Path

```js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-ts`,
      options: {
        fileName: `gen/graphql-types.ts`,
      }
    }
  ]
}
```

### I need to change everything

```js
// gatsby-config.js
{
  resolve: `gatsby-plugin-ts`,
  options: {
    tsLoader: {
      logLevel: 'warn',
    },
    forkTsCheckerPlugin: {
      eslint: true,
    },
    fileName: `types/graphql-types.ts`,
    codegen: true,
    codegenDelay: 250,
    typeCheck: false,
    pluckConfig: {
      // this is the default config
      globalGqlIdentifierName: 'graphql',
      modules: [
        { name: 'gatsby', identifier: 'graphql' },
      ],
    },
    additionalSchemas: [
      {
        key: 'example',
        fileName: 'graphql-types-example.ts',
        schema: 'https://example.com/graphql',
        pluckConfig: {
          // config to ensure only queries using the `gql` tag are used for this schema
          globalGqlIdentifierName: 'gql',
          modules: [
            {
              name: 'graphql-tag',
              identifier: 'gql',
            },
          ],
        },
      }
    ],
  },
}
```

### Gatsby files

- `gatsby-config` has to be a `.js` file
- `gatsby-node` is run directly by `node`, so it has to be a .js file as well. It is a shame, because in a complicated Gatsby app it is where a lot of logic live & will benefit from ts. As a work around, it can be built with `tsc` independently, in a script in `package.json` or somehow in gatsby's pre-init hook.
- Gatsby's global variable like `__PATH_PREFIX__` can be handled by declaring this code somewhere:

```ts
// src/global.d.ts
declare const __PATH_PREFIX__: string
```

## Code generation

By default, this plugin will build typing for your queries automatically to `graphql-types.d.ts` on every edit. Please note that the definition file **should not** be placed inside `src` since this triggers a never ending loop during development.

In order to take advantage of the generated code, user needs to name their query:

```js
// src/pages/index.tsx

  export const pageQuery = graphql`
-   query {
+   query BlogIndex {
      site {
        siteMetadata {
          title
        }
      }
  ...
```

...and import it from the generated type file: 

```js
// src/pages/index.tsx

import { BlogIndexQuery } from '../graphqlTypes'

interface IBlogIndexProps {
  data: BlogIndexQuery;
  location: Location;
}

const BlogIndex: React.FC<IBlogIndexProps> = ({ data, location }) => {
  ...
}
```

## Disable type checking in production

Previously this plugin disable type checking in production by default, which can be changed by setting `alwaysCheck` to `true`. Since 2.0.0 it no longer does this. If you want to preseve the previous behavior, please set the `typeCheck` option like below:

```js
{
  resolve: 'gatsby-plugin-ts',
  options: {
    // Disable type checking in production
    typeCheck: process.env.NODE_ENV !== 'production',
  }
}
```

---
_Source: https://npm.io/package/gatsby-plugin-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._