Gatsby Typescript Plugin
An alternative to the official typescript plugin, with ts-loader
& automatic type generation for your graphql queries (using graphql-code-generator
)
Installation
yarn add typescript gatsby-plugin-ts
Add this to your gatsby config like any other plugins:
// gatsby-config.jsmoduleexports = plugins: `gatsby-plugin-ts`
Unlike the official plugin, you'd have to bring your own tsconfig.json
.
# 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:
"compilerOptions": "target": "ESNext" /* 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 for more |
options.alwaysCheck | false |
⚠️deprecated 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 |
codegen options | ||
options.codegen | true |
enable / disable generating definitions for graphql queries |
options.documentPaths | ['./src/**/*.{ts,tsx}', |
The paths to files containing graphql queries. ⚠️ The default paths will be overwritten by the documentPaths you pass in, so please make sure to include all necessary paths ⚠️ |
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 |
An example setup:
// gatsby-config.js resolve: `gatsby-plugin-ts` options: tsLoader: logLevel: 'warn' forkTsCheckerPlugin: eslint: true fileName: `types/graphql-types.ts` codegen: true codegenDelay: 250 alwaysCheck: false
Gatsby files
gatsby-config
has to be a.js
filegatsby-node
is run directly bynode
, 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 withtsc
independently, in a script inpackage.json
or somehow in gatsby's pre-init hook.- Gatsby's global variable like
__PATH_PREFIX__
can be handled by declaring this code somewhere:
// src/global.d.tsdeclare
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:
// src/pages/index.tsx const pageQuery = graphql`- query {+ query BlogIndex { site { siteMetadata { title } } ...
...and import it from the generated type file:
// src/pages/index.tsx interface IBlogIndexProps data: BlogIndexQuery; location: Location; const BlogIndex: React.FC<IBlogIndexProps> = { ...}
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:
resolve: 'gatsby-plugin-ts' options: // Disable type checking in production typeCheck: processenvNODE_ENV !== 'production'