{"id":13213,"library":"gatsby-plugin-tsconfig-paths","title":"Gatsby TSConfig Paths Plugin","description":"This plugin integrates `tsconfig-paths-webpack-plugin` into Gatsby builds, enabling resolution of module aliases defined in `tsconfig.json`. This simplifies imports, especially in large TypeScript projects, by allowing absolute or aliased paths instead of lengthy relative ones. The current stable version is 1.0.6. It doesn't appear to follow a strict time-based release cadence, with updates typically occurring to ensure compatibility with new major versions of Gatsby. For instance, recent updates added support for Gatsby v5. Its key differentiator is its seamless, zero-config integration for most standard Gatsby setups, abstracting away the manual Webpack configuration typically required for `tsconfig-paths-webpack-plugin`. Users can also pass through any `tsconfig-paths-webpack-plugin` options if more granular control is needed.","status":"active","version":"1.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/Js-Brecht/gatsby-plugin-tsconfig-paths","tags":["javascript","gatsby-plugin","gatsby","typescript","tsconfig paths","webpack","tsconfig-paths-webpack-plugin"],"install":[{"cmd":"npm install gatsby-plugin-tsconfig-paths","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-plugin-tsconfig-paths","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-plugin-tsconfig-paths","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Gatsby framework integration.","package":"gatsby","optional":false}],"imports":[{"note":"Gatsby plugins are configured in `gatsby-config.js` and are not directly imported into application code.","wrong":"import * as tsconfigPlugin from 'gatsby-plugin-tsconfig-paths';","symbol":"Plugin registration","correct":"module.exports = { plugins: [`gatsby-plugin-tsconfig-paths`] }"},{"note":"When passing options, the plugin needs to be wrapped in an object with `resolve` and `options` properties.","wrong":"module.exports = { plugins: [`gatsby-plugin-tsconfig-paths`, { configFile: './tsconfig.json' }] }","symbol":"Plugin with options","correct":"module.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-tsconfig-paths`,\n      options: {\n        configFile: `${__dirname}/tsconfig.json`,\n        silent: true\n      }\n    }\n  ]\n}"}],"quickstart":{"code":"// gatsby-config.js\nconst path = require('path');\n\nmodule.exports = {\n  plugins: [\n    // ... other plugins\n    {\n      resolve: `gatsby-plugin-tsconfig-paths`,\n      options: {\n        // Optionally specify the tsconfig file location if not at root\n        configFile: path.resolve(__dirname, 'tsconfig.json'),\n        // Optionally silence tsconfig-paths-webpack-plugin output\n        silent: true,\n        // Optionally disable colors in tsconfig-paths-webpack-plugin output\n        colors: false,\n        // Optionally customize extensions (defaults: ['.ts', '.tsx', '.js', '.jsx'])\n        extensions: ['.ts', '.tsx', '.js', '.jsx']\n      }\n    }\n  ]\n};","lang":"javascript","description":"Demonstrates how to include and configure the plugin in `gatsby-config.js` with common options."},"warnings":[{"fix":"Explicitly set the `extensions` option for `gatsby-plugin-tsconfig-paths` if you have a custom setup or experience resolution issues, e.g., `options: { extensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs'] }`.","message":"When `allowJs` is set to `true` in your `tsconfig.json`, ensure the plugin's `extensions` option (or the underlying `tsconfig-paths-webpack-plugin`'s `extensions`) includes `.js` and `.jsx` to correctly resolve JavaScript modules using path aliases. The plugin defaults to `['.ts', '.tsx', '.js', '.jsx']`, which generally aligns with typical Webpack configurations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure your `gatsby` package version aligns with the `peerDependencies` specified by `gatsby-plugin-tsconfig-paths`. Upgrade `gatsby-plugin-tsconfig-paths` to `v1.0.6` or newer for full Gatsby v5 compatibility.","message":"The plugin's peer dependency on `gatsby` has been updated to support newer major versions. Older versions of this plugin may not be compatible with recent Gatsby releases, and vice-versa. Specifically, `v1.0.6` introduced compatibility for Gatsby v5.","severity":"breaking","affected_versions":"<1.0.6"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that your `tsconfig.json` `compilerOptions.paths` are correctly defined and that `gatsby-plugin-tsconfig-paths` is properly included in `gatsby-config.js`. If your `tsconfig.json` is not at the project root, ensure you're using the `configFile` option, e.g., `options: { configFile: './path/to/tsconfig.json' }`.","cause":"TypeScript path aliases defined in `tsconfig.json` are not being correctly resolved during the Gatsby build process.","error":"Module not found: Error: Can't resolve 'your/aliased/module'"},{"fix":"Check the `peerDependencies` listed in `node_modules/gatsby-plugin-tsconfig-paths/package.json` and ensure your project's `gatsby` version falls within the allowed range. Upgrading `gatsby-plugin-tsconfig-paths` to its latest version (currently `1.0.6`) often provides broader `gatsby` version support, including `gatsby@5`.","cause":"The installed `gatsby` version in your project conflicts with the `peerDependencies` specified by `gatsby-plugin-tsconfig-paths`.","error":"npm ERR! ERESOLVE unable to resolve dependency tree` or `Yarn failed to install dependencies` (mentioning `gatsby` peer dependency)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}