Gatsby TypeScript Plugin

5.16.0 · active · verified Sun Apr 19

gatsby-plugin-typescript allows Gatsby to process and build TypeScript and TSX files, integrating TypeScript transpilation into the Gatsby build pipeline using `@babel/preset-typescript`. The plugin's current stable version, 5.16.0, is designed for Gatsby v5, and its releases typically align with major and minor Gatsby core updates. A key differentiator is that this plugin focuses solely on transpilation, meaning it transforms TypeScript code into JavaScript without performing type checking itself. Developers are expected to handle type checking separately, often through their IDE or a dedicated `type-check` script. While it supports most common TypeScript features, it has specific limitations due to its Babel-based approach, such as not supporting namespaces, `const` enums, `export =`/`import =` syntax, or direct `baseUrl` configuration. The plugin is automatically included in Gatsby projects, requiring explicit configuration only for custom options.

Common errors

```
error glob@11.0.3: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"
```
cause This error, originating from a transitive dependency, indicates that your Node.js version is too old for the Gatsby ecosystem components being used.

fix Upgrade your Node.js environment to a version compatible with Gatsby 5. The latest Gatsby releases support Node.js 22 and 24.
```
Type 'string' is not assignable to type 'number'. (or similar type-related error during `gatsby build`)
```
cause `gatsby-plugin-typescript` transpiles code regardless of type errors, allowing the Gatsby build to complete even when TypeScript issues exist.

fix This is expected behavior for `gatsby-plugin-typescript`. To catch and enforce type correctness, run `tsc --noEmit` separately as a build step or rely on your IDE's TypeScript integration.
```
Cannot find module 'src/components/MyComponent' or its corresponding type declarations. (when using `paths` or `baseUrl` in `tsconfig.json`)
```
cause `gatsby-plugin-typescript` does not directly process the `baseUrl` or `paths` configuration from `tsconfig.json` for module resolution.

fix Install and configure `gatsby-plugin-root-import` (`npm install gatsby-plugin-root-import`) in your `gatsby-config.js` to enable path aliasing for module resolution during the Gatsby build.

Warnings

breaking Gatsby 5, and by extension gatsby-plugin-typescript, requires Node.js versions >=18.0.0 and <26. Using older Node.js versions (e.g., Node.js 16) will lead to build failures and dependency incompatibilities.
Fix: Upgrade your Node.js environment to a compatible version, preferably Node.js 20 or 22. Gatsby 5.16.0 officially supports Node.js 24.
gotcha `gatsby-plugin-typescript` exclusively handles TypeScript transpilation to JavaScript using Babel; it does NOT perform type checking during the Gatsby build process. Type errors will not halt your build.
Fix: Implement a separate type-checking step in your project. Add a script like `"type-check": "tsc --noEmit"` to your `package.json` and run it alongside or before your Gatsby build. Configure your IDE (e.g., VS Code) for real-time type error surfacing.
gotcha The plugin's Babel-based transpilation has limitations compared to the full TypeScript compiler. It does not support TypeScript-specific features like namespaces, `const` enums (unless their values are available at runtime), `export =`/`import =` syntax, or the direct `baseUrl` option from `tsconfig.json`.
Fix: Adopt ES module syntax (`export default`, `export const`, `import x, {y} from "z"`), avoid `const` enums (or remove the `const` keyword), and use `gatsby-plugin-root-import` to handle path aliases similar to `baseUrl`.
gotcha Many JavaScript packages do not ship with their own TypeScript type definitions. When using these packages, you will need to manually install their corresponding `@types/` packages.
Fix: Install necessary type definitions as development dependencies, for example: `npm install --save-dev @types/react @types/react-dom @types/node`.

Install

npm install gatsby-plugin-typescript npm
yarn add gatsby-plugin-typescript yarn
pnpm add gatsby-plugin-typescript pnpm

Imports

gatsby-plugin-typescript (configuration)

wrong:

import { GatsbyPluginTypescript } from 'gatsby-plugin-typescript'; // Not how Gatsby plugins are configured
module.exports = {
  plugins: [
    new GatsbyPluginTypescript(),
  ]
};

correct:

module.exports = {
  plugins: [
    `gatsby-plugin-typescript`,
    // Or with options:
    {
      resolve: `gatsby-plugin-typescript`,
      options: {
        isTSX: true,
        allExtensions: true
      }
    }
  ]
};

Gatsby plugins are configured via string names or objects within the `plugins` array in `gatsby-config.js`. They do not export symbols for direct programmatic import into application code. Ensure `module.exports` is used for `gatsby-config.js`.

Quickstart

This quickstart shows how to configure `gatsby-plugin-typescript` in `gatsby-config.js` and create a basic Gatsby page component using TypeScript and TSX syntax.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-typescript`,
      options: {
        isTSX: true, // Enable TSX support
        allExtensions: true // Process all extensions including .ts and .tsx
      }
    }
  ]
};

// src/pages/index.tsx
import * as React from 'react';
import type { PageProps } from 'gatsby';

interface IndexPageProps extends PageProps {
  // Add any custom props if using page queries
}

const IndexPage: React.FC<IndexPageProps> = () => {
  const greeting: string = "Hello, Gatsby with TypeScript!";

  return (
    <main style={{ fontFamily: 'sans-serif', padding: 20 }}>
      <h1>{greeting}</h1>
      <p>This page is built with TypeScript and rendered by Gatsby.</p>
      <button onClick={() => alert('TypeScript in action!')}>
        Click Me
      </button>
    </main>
  );
};

export default IndexPage;

view raw JSON →