gatsby-typescript
v2.1.2
Published
Typescript support via ts-loader & fork-ts-checker-webpack-plugin + automate codegen
Downloads
3
Readme
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.js
module.exports = {
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}','./.cache/fragments/*.js', './node_modules/gatsby-*/**/*.js'] | 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.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:
// src/pages/index.tsx
export const pageQuery = graphql`
- query {
+ query BlogIndex {
site {
siteMetadata {
title
}
}
...
...and import it from the generated type file:
// 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:
{
resolve: 'gatsby-plugin-ts',
options: {
// Disable type checking in production
typeCheck: process.env.NODE_ENV !== 'production',
}
}