{"id":10928,"library":"gatsby-plugin-typescript","title":"Gatsby TypeScript Plugin","description":"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.","status":"active","version":"5.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatsbyjs/gatsby","tags":["javascript","gatsby","gatsby-plugin","typescript"],"install":[{"cmd":"npm install gatsby-plugin-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-plugin-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-plugin-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Gatsby plugin and requires a compatible Gatsby core version.","package":"gatsby","optional":false}],"imports":[{"note":"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`.","wrong":"import { GatsbyPluginTypescript } from 'gatsby-plugin-typescript'; // Not how Gatsby plugins are configured\nmodule.exports = {\n  plugins: [\n    new GatsbyPluginTypescript(),\n  ]\n};","symbol":"gatsby-plugin-typescript (configuration)","correct":"module.exports = {\n  plugins: [\n    `gatsby-plugin-typescript`,\n    // Or with options:\n    {\n      resolve: `gatsby-plugin-typescript`,\n      options: {\n        isTSX: true,\n        allExtensions: true\n      }\n    }\n  ]\n};"}],"quickstart":{"code":"// gatsby-config.js\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-typescript`,\n      options: {\n        isTSX: true, // Enable TSX support\n        allExtensions: true // Process all extensions including .ts and .tsx\n      }\n    }\n  ]\n};\n\n// src/pages/index.tsx\nimport * as React from 'react';\nimport type { PageProps } from 'gatsby';\n\ninterface IndexPageProps extends PageProps {\n  // Add any custom props if using page queries\n}\n\nconst IndexPage: React.FC<IndexPageProps> = () => {\n  const greeting: string = \"Hello, Gatsby with TypeScript!\";\n\n  return (\n    <main style={{ fontFamily: 'sans-serif', padding: 20 }}>\n      <h1>{greeting}</h1>\n      <p>This page is built with TypeScript and rendered by Gatsby.</p>\n      <button onClick={() => alert('TypeScript in action!')}>\n        Click Me\n      </button>\n    </main>\n  );\n};\n\nexport default IndexPage;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<5.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install necessary type definitions as development dependencies, for example: `npm install --save-dev @types/react @types/react-dom @types/node`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to a version compatible with Gatsby 5. The latest Gatsby releases support Node.js 22 and 24.","cause":"This error, originating from a transitive dependency, indicates that your Node.js version is too old for the Gatsby ecosystem components being used.","error":"error glob@11.0.3: The engine \"node\" is incompatible with this module. Expected version \"20 || >=22\". Got \"18.6.0\""},{"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.","cause":"`gatsby-plugin-typescript` transpiles code regardless of type errors, allowing the Gatsby build to complete even when TypeScript issues exist.","error":"Type 'string' is not assignable to type 'number'. (or similar type-related error during `gatsby build`)"},{"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.","cause":"`gatsby-plugin-typescript` does not directly process the `baseUrl` or `paths` configuration from `tsconfig.json` for module resolution.","error":"Cannot find module 'src/components/MyComponent' or its corresponding type declarations. (when using `paths` or `baseUrl` in `tsconfig.json`)"}],"ecosystem":"npm"}