TypeScript Paths to Webpack Aliases Converter

0.9.2 · active · verified Sun Apr 19

The `convert-tsconfig-paths-to-webpack-aliases` package offers a focused utility to bridge the gap between TypeScript's `compilerOptions.paths` and Webpack's `resolve.alias` configuration. It transforms the globstar notation used in `tsconfig.json` into a format compatible with Webpack, thereby establishing a single source of truth for module aliases and preventing discrepancies between TypeScript's type resolution and Webpack's bundling process. This ensures that developers define their module aliases only once in `tsconfig.json`, and this utility automatically synchronizes them with the Webpack build. The current stable version is 0.9.2, indicating it's pre-1.0 but widely functional, and it typically sees stable, moderate release cycles fitting a niche utility.

Common errors

```
Error: Cannot find module './tsconfig.json' or SyntaxError: Unexpected token / in JSON at position X
```
cause Attempting to `require()` a `tsconfig.json` file that contains comments, or the file path is incorrect.

fix Ensure the path to `tsconfig.json` is correct. If comments are present, read the file content as a string, strip comments (e.g., using `strip-json-comments`), and then parse it with `JSON.parse` before passing to the utility.
```
TypeError: convertPathsToAliases is not a function
```
cause Incorrect import syntax for the default export, particularly when mixing CommonJS and ES Modules.

fix For CommonJS, use `const convertPathsToAliases = require('convert-tsconfig-paths-to-webpack-aliases').default;`. For ES Modules, use `import convertPathsToAliases from 'convert-tsconfig-paths-to-webpack-aliases';`.
```
Module not found: Error: Can't resolve '@components/MyComponent' in '...'
```
cause Webpack is unable to resolve an alias generated by the utility, often due to an incorrect `baseUrl`, malformed `paths` in `tsconfig.json`, or an unparsed `tsconfig.json` with comments.

fix Verify that `tsconfig.json` has `compilerOptions.baseUrl` correctly set. Ensure there are no comments in the `tsconfig.json` being passed to the utility. Double-check that `compilerOptions.paths` entries correctly map to existing directories and files.

Warnings

gotcha The utility expects a valid JSON object for `tsconfig.json`. Directly requiring `tsconfig.json` with comments will result in a parsing error.
Fix: Use a utility like `strip-json-comments` to preprocess `tsconfig.json` content before passing it to `convertPathsToAliases`. For example: `JSON.parse(stripJsonComments(fs.readFileSync('./tsconfig.json', 'utf8')))`.
gotcha For TypeScript `paths` to function correctly, `compilerOptions.baseUrl` must be defined in `tsconfig.json`. If `baseUrl` is missing or incorrect, aliases generated by this utility might not resolve as expected in Webpack.
Fix: Ensure `compilerOptions.baseUrl` is correctly configured in your `tsconfig.json`, typically set to `.` for the project root.
breaking As a pre-1.0.0 package, the API might introduce breaking changes in minor versions (e.g., from 0.x.x to 0.y.x). Always review release notes when upgrading to new minor versions.
Fix: Consult the package's GitHub releases or changelog before upgrading to understand any API changes or required adjustments in your `webpack.config.js`.

Install

npm install convert-tsconfig-paths-to-webpack-aliases npm
yarn add convert-tsconfig-paths-to-webpack-aliases yarn
pnpm add convert-tsconfig-paths-to-webpack-aliases pnpm

Imports

convertPathsToAliases

wrong:

import { convertPathsToAliases } from 'convert-tsconfig-paths-to-webpack-aliases';

correct:

import convertPathsToAliases from 'convert-tsconfig-paths-to-webpack-aliases';

The package exports a default function. Use default import for ESM.

convertPathsToAliases

wrong:

const convertPathsToAliases = require('convert-tsconfig-paths-to-webpack-aliases');

correct:

const convertPathsToAliases = require('convert-tsconfig-paths-to-webpack-aliases').default;

For CommonJS, access the default export via the '.default' property.

Quickstart

Demonstrates integrating the utility into a webpack.config.js to synchronize TypeScript paths with Webpack aliases, including handling comments in tsconfig.json.

// webpack.config.js
const path = require('path');
const fs = require('fs');
const stripJsonComments = require('strip-json-comments'); // You might need to install 'strip-json-comments'

const convertPathsToAliases = require('convert-tsconfig-paths-to-webpack-aliases').default;

// Load tsconfig.json and remove comments
const tsconfigPath = path.resolve(__dirname, 'tsconfig.json');
const tsconfigContent = fs.readFileSync(tsconfigPath, 'utf8');
const tsconfig = JSON.parse(stripJsonComments(tsconfigContent));

const aliases = convertPathsToAliases(tsconfig);

module.exports = {
  mode: 'development',
  entry: './src/index.ts',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  resolve: {
    extensions: ['.ts', '.js'],
    alias: aliases,
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
};

// tsconfig.json (example - ensure no comments if you require directly without stripJsonComments)
/*
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
*/

view raw JSON →