rollup-plugin-tsconfig-paths

1.5.2 verified Mon Apr 27 auth: no javascript

A Rollup plugin that resolves TypeScript path aliases (e.g., "~/*") defined in tsconfig.json, enabling cleaner imports in bundled output. Current stable version is 1.5.2, released periodically with minor fixes. It supports Rollup 2, 3, and 4, and ships TypeScript types. Unlike alternatives like @rollup/plugin-alias, this plugin directly reads tsconfig paths, reducing configuration duplication. It can auto-detect tsconfig via TS_NODE_PROJECT env var or cwd search, and offers log level control.

Common errors

error Cannot find module '~/*' ↓

cause Plugin not installed, not added to plugins array, or tsconfig paths not configured correctly.

fix

Install the plugin, add to rollup.config.js, ensure tsconfig has paths and baseUrl.

error TypeError: tsConfigPaths is not a function ↓

cause Incorrect import: using named import instead of default.

fix

Use import tsConfigPaths from 'rollup-plugin-tsconfig-paths' (ESM) or const tsConfigPaths = require('rollup-plugin-tsconfig-paths').default (CJS).

error The 'tsConfigPath' option must be a string or an array of strings ↓

cause Passing an object or other type to tsConfigPath.

fix

Pass a string path or array of strings.

Warnings

gotcha Plugin must come before @rollup/plugin-node-resolve to resolve aliases before Node resolution. ↓

fix Order plugins: tsConfigPaths() first, then nodeResolve().

gotcha tsconfig.json must have "moduleResolution": "node" for path resolution to work. ↓

fix Set 'moduleResolution': 'node' in compilerOptions.

gotcha If multiple tsconfig files are specified, only the first one's paths are used for resolution. ↓

fix Use a single tsconfig or merge paths manually.

gotcha Environment variable TS_NODE_PROJECT overrides the tsConfigPath option if set. ↓

fix Unset TS_NODE_PROJECT or pass explicit tsConfigPath.

deprecated No known deprecations as of v1.5.2.

Install

npm install rollup-plugin-tsconfig-paths

yarn add rollup-plugin-tsconfig-paths

pnpm add rollup-plugin-tsconfig-paths

Imports

default

wrong

const { tsConfigPaths } = require('rollup-plugin-tsconfig-paths')

correct

import tsConfigPaths from 'rollup-plugin-tsconfig-paths'

The default export is a factory function. Named export is not available.

RollupPluginTsconfigPathsOptions

wrong

import { RollupPluginTsconfigPathsOptions } from 'rollup-plugin-tsconfig-paths'

correct

import type { RollupPluginTsconfigPathsOptions } from 'rollup-plugin-tsconfig-paths'

Type import in TypeScript; not available as value.

tsConfigPaths (factory call)
wrong
```
new tsConfigPaths()
```
correct
```
tsConfigPaths({ tsConfigPath: './tsconfig.app.json' })
```
Call as function, not constructor. Options object is optional.

Quickstart

Shows minimal Rollup config using the plugin with tsconfig path resolution and common plugin chaining.

import tsConfigPaths from 'rollup-plugin-tsconfig-paths';
import nodeResolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

// tsconfig.json must have paths defined, e.g. "~/*": ["./*"]
export default {
  input: 'src/index.ts',
  plugins: [
    tsConfigPaths({
      tsConfigPath: './tsconfig.json',
      logLevel: 'warn'
    }),
    nodeResolve({ extensions: ['.ts', '.js'] }),
    commonjs()
  ],
  output: { file: 'dist/bundle.js', format: 'esm' }
};