Gatsby Typescript

An alternative to the official typescript plugin, with ts-loader & automatic type generation for your graphql queries (using graphql-code-generator)

---

Hi there 👋 Are you just looking for a way to generate graphql types for your graphql queries?

gatsby-plugin-graphql-codegen is what you want. However, other maintainers and I haven't been able to keep this repo up to shape. Please have a look at @cometkim's graphql-plugin-typegen which does almost the same thing & better maintained. Still, ideas & PRs are all welcomed. If you'd like to help maintain this project, please feel free to reach out. Thank you, have a great day!

---

This monorepo houses 2 packages:

npm package	Description	Docs
gatsby-plugin-ts	alternative typescript support with ts-loader & automated graphql codegen via graphql-code-generator	docs
gatsby-plugin-graphql-codegen	automated graphql codegen via graphql-code-generator	docs

---

Quick links: Acknowledgement • General Q&A • Contribute

---

Acknowledgment

Special thanks to the contributors, who have improved this project with code, bug reports & suggestions:

Code

@ricokahler (maintainer),

@kije,

@Js-Brecht,

@Kerumen,

@olee,

@Tielem

Bugs & Suggestions

@frantic1048,

@cometkim,

@FrobtheBuilder,

@aswinckr,

@mshick,

@joewood,

@Jdruwe

Do you want to send a PR? see this section

Powered By

This project is built upon these awesome projects:

• TypeStrong projects:

  • TS Loader
  • Fork TS Checker Webpack Plugin

• The Guild's projects:

  • Graphql Code Generator
  • Graphql Toolkit

And of course, Gatsbyjs and Typescript

---

General Q&A

Here's a list of common questions I've seen since releasing this project. If you have a question that's not here, please don't hesitate to open an issue!

Why use gatsby-plugin-ts?

Gatsby use babel-preset-typescript which strips type information out of your code without doing typecheck. gatsby-plugin-ts use ts-loader, so you don't have to (1) worry about the caveats of babel-preset-typescript or (2) use an IDE / code editor that can typecheck for you.

It also generate typings for your graphql queries, make it easier to strengthen your code.

If you're already using something like VSCode and/or don't want to do typecheck in production, you can toggle off the typecheck option.

What's the difference between gatsby-plugin-ts and gatsby-plugin-graphql-codegen?

Originally belong to the same plugin, the codegen portion was extracted to gatsby-plugin-graphql-codegen so it can be used with the official typescript plugin. If you are already using gatsby-plugin-ts, you don't need gatsby-plugin-graphql-codegen.

Should I check the generated type definition into git?

It's up to your preference.

What is up with all the Maybe<T>?

It's due to Gatsby internal. There's an effort to make typing more strict here.

You also may find the new optional chaining & nullish coalescing operator in typescript 3.7 helpful to deal with this.

Can I turn off type checking and/or type generating?

Yes! You can also use node env to determine whether to enable these features.

// gatsby-config.js
{
  resolve: `gatsby-plugin-ts`,
  options: {
    codegen: false,
    typeCheck: process.env.NODE_ENV === 'development',
  }
},

My graphql queries returns null

Gatsby extract graphql queries statically and it only understand queries inside template literal. It's possible that tsc is transpiling your template literal to string concat quivalent. Check your tsconfig.json & make sure you have a setting similar to this:

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

What if I have a mixed ts/js codebase?

You'd have to update your tsconfig with the below options:

  "allowJS": true,
  "outDir": "./build"

The outDir option won't be used by ts-loader, but you may need it to satisfy vscode.

Babel doesn't understand the new optional chaining & nullish coalescing syntax even though my IDE shows no errors

If you are using gatsby-plugin-ts, before you go off and install a bunch of babel plugins like a lot of tutorials suggest, check if your compilation target in tsconfig.json is too high (ESNext or ES2019).

With these targets, tsc will leave the new syntax as-is, which babel might not understand. Downgrade them to ES2018 should fix the issue; also make sure your IDE's typescript version is the same as the one listed in your package.json dependency.

Can I write `gatsby-node` in typescript & have its queries typing generated as well?

Yes, but it's not easy at the moment. We're working on it; stay tuned!

Typechecking causes `gatsby develop` to crash.

We're trying to pin down why this happens, please share your experience in #36

Common warning & errors

Gatsby recently moved plugins' fragments from .cache to node_modules. We currently support both paths, but sometimes it may cause conflict warnings & errors:

`warning: Unable to find any GraphQL type definitions for the following pointers ...`

If you are annoyed by this warning, set the documentPaths options as below:

// gatsby-config.js
{
  resolve: 'gatsby-plugin-graphql-codegen',
  options: {
    documentPaths: [
      './src/**/*.{ts,tsx}',
      './node_modules/gatsby-*/**/*.js',
    ],
  }
},

We will remove the .cache/fragments path and bump gatsby peer dependency version in a later release.

Update: Since 2.4.0, we've removed .cache/fragments & bump up gatsby peer dep.

Duplicate identifier error: Duplicate identifier 'GatsbyImageSharpFixedFragment'

If you see this error please run a gatsby clean to remove fragments in .cache, or set the documentPaths options as below:

// gatsby-config.js
{
  resolve: 'gatsby-plugin-graphql-codegen',
  options: {
    documentPaths: [
      './src/**/*.{ts,tsx}',
      './node_modules/gatsby-*/**/*.js',
    ],
  }
},

Missing definition Unknown identifier 'GatsbyImageSharpFixedFragment' in a yarn/lerna monorepo

Are you using a monorepo? It's possible that the missing fragment's plugin is 'hoisted' (moved to workspace root's node_modules). A simple fix is use a nohoist config, supported by both lerna & yarn. Here's an example with yarn workspace, where gatsby-transformer-sharp is always installed in its project's node_modules.

in your root's package.json

"workspaces": {
  "packages": ["packages/*"],
  "nohoist": [
    "**/gatsby-transformer-sharp",
  ]
}

Contribute to this repo

All PRs / issues are welcomed.

Steps to run in development:

# 0
git clone https://github.com/d4rekanguok/gatsby-typescript.git && cd gatsby-typescript

# 1 Install deps
yarn

# 2 Hook up dependencies
yarn bootstrap

# 3 Build binaries
lerna run build

# 4 Run test
yarn test

You can test your code against the starters inside the repo. Don't forget to checkout the changes in those repo before sending a PR. Alternatively, use yalc to test the plugins in your own Gatsby project:

# 1 Install yalc
npm i yalc -G

# 2 cd into, say, gatsby-plugin-ts
cd packages/gatsby-plugin-ts

# 3 Publish to yalc
yalc publish

# 4 cd into your gatsby project
cd ../../my-gatsby-project

# 5 Install yalc & re-install deps
npm uninstall gatsby-plugin-ts && yalc add gatsby-plugin-ts

npm install

# 6 Subsequent update
yalc update

# 7 Done? remove yalc deps
yalc remove --all