Registry / web-framework / gatsby-plugin-typescript

gatsby-plugin-typescript

library5.16.0jsnpmunverified

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.

web-framework

npm install gatsby-plugin-typescript

github ↗package ↗

INSTALL

IMPORT

SIG · GATSBY-PLUGIN-TYPE

gatsby-plugin-typescript

web-frameworkjavascriptv5.16.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gatsby-plugin-typescript (configuration)

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

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

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`.

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;

Debug

Known issues

breakingGatsby 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.

affects: <5.0.0

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.

affects: >=1.0.0

gotchaThe 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`.

affects: >=1.0.0

gotchaMany 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`.

affects: >=1.0.0

Errors

Common errors & fixes

error glob@11.0.3: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"

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`)

`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`)

`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.

Upgrade

Version history

5.16.0latest on npm

Audit

Dependencies

gatsbyrequiredThis is a Gatsby plugin and requires a compatible Gatsby core version.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagehttps://www.npmjs.com/package/gatsby-plugin-typescript ↗