Registry / devops / gatsby-plugin-tsconfig-paths

gatsby-plugin-tsconfig-paths

library1.0.6jsnpmunverified

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.

devops

npm install gatsby-plugin-tsconfig-paths

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GATSBY-PLUGIN-TSCO

gatsby-plugin-tsconfig-paths

devopsjavascriptv1.0.6

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.

Plugin registration

✓ module.exports = { plugins: [`gatsby-plugin-tsconfig-paths`] }

✗ import * as tsconfigPlugin from 'gatsby-plugin-tsconfig-paths';

Gatsby plugins are configured in `gatsby-config.js` and are not directly imported into application code.

Plugin with options

✓ module.exports = { plugins: [ { resolve: `gatsby-plugin-tsconfig-paths`, options: { configFile: `${__dirname}/tsconfig.json`, silent: true } } ] }

✗ module.exports = { plugins: [`gatsby-plugin-tsconfig-paths`, { configFile: './tsconfig.json' }] }

When passing options, the plugin needs to be wrapped in an object with `resolve` and `options` properties.

Demonstrates how to include and configure the plugin in `gatsby-config.js` with common options.

// gatsby-config.js const path = require('path'); module.exports = { plugins: [ // ... other plugins { resolve: `gatsby-plugin-tsconfig-paths`, options: { // Optionally specify the tsconfig file location if not at root configFile: path.resolve(__dirname, 'tsconfig.json'), // Optionally silence tsconfig-paths-webpack-plugin output silent: true, // Optionally disable colors in tsconfig-paths-webpack-plugin output colors: false, // Optionally customize extensions (defaults: ['.ts', '.tsx', '.js', '.jsx']) extensions: ['.ts', '.tsx', '.js', '.jsx'] } } ] };

Debug

Known issues

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

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'] }`.

affects: >=1.0.0

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

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.

affects: <1.0.6

Errors

Common errors & fixes

Module not found: Error: Can't resolve 'your/aliased/module'

TypeScript path aliases defined in `tsconfig.json` are not being correctly resolved during the Gatsby build process.

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

npm ERR! ERESOLVE unable to resolve dependency tree` or `Yarn failed to install dependencies` (mentioning `gatsby` peer dependency)

The installed `gatsby` version in your project conflicts with the `peerDependencies` specified by `gatsby-plugin-tsconfig-paths`.

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

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

gatsbyrequiredRequired peer dependency for Gatsby framework integration.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Js-Brecht/gatsby-plugin-tsconfig-paths ↗

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

homepagehttps://js-brecht.github.io/gatsby-plugin-tsconfig-paths/ ↗