gatsby-plugin-ts-loader

Provides plug-n-play support for Typescript and tslint in Gatsby.

Install

npm install gatsby-plugin-ts-loader

Motivation

The only other option for adding typescript to Gatsby at the time of writing is gatsby-plugin-typescript, which does not use the typescript compiler but instead a babel plugin. Therefore it does not do type checking and you are required to install a separate plugin to check types. In addition, you are required to install a third plugin for linting. I would also argue that most react developers prefer ts-loader over the babel plugin, which could just be my perspective, but the plugins listed above were the first time I even came someone using the babel plugin.

Also, it is worth noting that the compiled typescript is fed back through babel, this means that anything you have setup through babel should still work.

I wrote this to reduce the required number of plugins to get up and running with typescript and to also do typescript in a way more react developers are accustomed to, using the same tools most frontend developers already use. I also wanted to make it very easy for new developers to get up and running by simplifying the process and providing better documentation than other options.

How to use

1. Install plugin via your prefered package manager
2. Include the plugin in your gatsby-config.js file, optionally enabling tslint (defaults to: false). It is important to include this plugin AFTER any other plugins that modify the babel config, as this plugin will feed the compiled typescript back through babel.
3. Add a tsconfig.json file to the root of your site (example below)
4. If using tslint, add a tslint.json file to the root of your project (example below)
5. Optionally install DefinitelyTyped definitions for any of your dependencies that require it.
6. You are now free to write Typescript inside any file with a .ts or .tsx file. To use the jsx syntax, your file must have the .tsx extension.
7. If you have an existing project written in javascript you are able to incrementally convert the project to typescript as needed. See the conversion guide for help. Your .js files will continue to work. Note that sometimes gatsby crashes when changing file names, simply restart the dev-server and you will be good to go.
8. tslint will currently only warn you in development mode but will error out when you build the project for release. This is to make it less intrusive during development, while also preventing you from releasing code that does not meet your style guide. If you need an escape hatch for a specific part of your codebase, tslint provides disable comments to have it ignore certain lines. This forces you to be explicit about breaking the rules.

Example gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-ts-loader",
      options: {
        tslint: true // false or exclude to disable tslint
      }
    }
  ]
};

Example tsconfig.json

{
  "compilerOptions": {
    "outDir": "./dist/",
    "sourceMap": true,
    // uncomment the following lines if you are working with a mixed code base (both javascript and typescript. Useful when migrating a project)
    // "noImplicitAny": true,
    // "allowJs": true,
    "module": "commonjs",
    "target": "esnext",
    "jsx": "react",
    "lib": ["dom", "esnext"]
  },
  "include": ["./src/**/*"]
}

Example tslint.json

{
  "extends": "tslint:recommended",
  "rules": {
    "quotemark": [true, "single", "jsx-single", "avoid-escape"]
  }
}

Possible Features

These are some of my ideas for things I would like to add to this in the future. These shouldn’t break any of the existing functionality. I will add a feature when I need it myself or if someone ask (nicely) for it or better yet, opens up a PR for it. If you have any ideas for what you would like to add, please feel free to open an issue.

• Optionally use fork-ts-checker-webpack-plugin to check types in a separate process instead of in the main webpack thread.
• Optionally have tslint only warn on production builds.

Contributing

• If you see something listed under Possible Features, open an issue if one is not already open and assign it to yourself. I will check in periodically to see if you are still working on it if it has been open more than a few days. If it seems abandoned I will close it so someone else can take it on if they wish.
• If you find a bug or would like a new feature, open an issue and I will try to be as responsive as possible.
• If you have a question, please feel free to open up an issue and I will answer at my earliest convenience.