Registry / http-networking / rollup-plugin-typescript-paths

rollup-plugin-typescript-paths

library1.5.0jsnpmunverified

rollup-plugin-typescript-paths is a Rollup plugin designed to automatically resolve TypeScript path aliases (defined in tsconfig.json's `paths` and `baseUrl` options) *after* your TypeScript code has already been transpiled. It is currently stable at version `1.5.0` and receives regular updates, with several minor releases in the past year addressing features and bug fixes. This plugin fills a specific niche for projects that use separate TypeScript transpilation steps (e.g., Babel, swc, tsc --emitDeclarationOnly) before bundling with Rollup, rather than relying on Rollup plugins that handle TypeScript compilation directly (like `rollup-plugin-typescript`). Its key differentiators include requiring no configuration for basic usage, robust wildcard support, and leveraging the official TypeScript API's `nodeModuleNameResolver` for accurate path resolution. It ensures that Rollup understands imports like `@utils/foo` when `tsconfig.json` maps `@utils/*` to `src/helpers/utils/*`.

http-networking

npm install rollup-plugin-typescript-paths

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-TYPE

rollup-plugin-typescript-paths

http-networkingjavascriptv1.5.0

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.

typescriptPaths

✓ import { typescriptPaths } from 'rollup-plugin-typescript-paths';

✗ const typescriptPaths = require('rollup-plugin-typescript-paths');

The plugin is an ESM-first named export. CommonJS `require` syntax is not directly supported for the plugin function itself, and earlier versions (before v1.2.1) might have had a different export name, leading to 'not a function' errors.

typescriptPaths (incorrect default)

✓ import { typescriptPaths } from 'rollup-plugin-typescript-paths';

✗ import typescriptPaths from 'rollup-plugin-typescript-paths';

The main plugin function, `typescriptPaths`, is a named export, not a default export. Importing it as a default will result in a runtime error.

Options (type)

✓ import type { Options } from 'rollup-plugin-typescript-paths';

For TypeScript users, the configuration options interface can be imported for type safety when defining the plugin's configuration object. The exact type name `Options` is a common convention for such interfaces.

This quickstart demonstrates how to configure Rollup with `rollup-plugin-typescript-paths` to resolve TypeScript path aliases. It includes a runnable `rollup.config.js` and outlines the necessary `tsconfig.json` and source file structure to illustrate path resolution for `@utils` and `@components` aliases, assuming TypeScript transpilation (e.g., for declaration files) might occur in a separate step.

/* rollup.config.js */ import { typescriptPaths } from 'rollup-plugin-typescript-paths'; import typescript from '@rollup/plugin-typescript'; // Used here for declaration generation // --- Context: Minimal tsconfig.json for this example --- // Create a `tsconfig.json` in your project root with: // { // "compilerOptions": { // "target": "es2018", // "module": "esnext", // "baseUrl": ".", // "paths": { // "@components/*": ["src/components/*"], // "@utils": ["src/lib/utils/index.ts"] // }, // "lib": ["es2018", "dom"], // "declaration": true, // "emitDeclarationOnly": true, // "strict": true // }, // "include": ["src/**/*.ts"], // "exclude": ["node_modules"] // } // --- Context: Source files for this example --- // Create `src/index.ts`: // import { greeting } from '@utils'; // import { Button } from '@components/Button'; // console.log(greeting('Rollup')); // new Button().render(); // Create `src/lib/utils/index.ts`: // export const greeting = (name: string) => `Hello, ${name}!`; // Create `src/components/Button.ts`: // export class Button { render() { console.log('Button rendered!'); } } export default { input: 'src/index.ts', output: { dir: 'dist', format: 'es', sourcemap: true, }, plugins: [ // Use @rollup/plugin-typescript for declaration files only, or skip if already transpiled typescript({ declaration: true, declarationDir: 'dist/types', emitDeclarationOnly: true }), typescriptPaths({ // Optional: Set to true if you want to resolve non-relative paths // based on tsconfig's baseUrl even if no `paths` are matched. nonRelative: true, // Optional: Custom path to your tsconfig.json if not in project root // tsConfigPath: './configs/tsconfig.build.json', transform: (path, id) => { // Example: Log the resolved paths for debugging // console.log(`Resolved import ${id} to ${path}`); return path; } }), ], };

Debug

Known issues

breakingThe main plugin export was renamed in `v1.2.1` to `typescriptPaths` to align with Rollup's naming conventions. If you are using an older version, your import statement or plugin name in `rollup.config.js` might need to be updated.

fix

Update your import to `import { typescriptPaths } from 'rollup-plugin-typescript-paths';` and ensure you call it in your plugins array: `plugins: [typescriptPaths()]`.

affects: <1.2.1

gotchaThis plugin is specifically designed for use cases where your TypeScript code has *already been transpiled* to JavaScript before Rollup begins its bundling process. It should generally not be used in conjunction with `rollup-plugin-typescript` if that plugin is also configured to resolve paths or transpile to JavaScript, as this can lead to conflicts or redundant processing. It's best used when `rollup-plugin-typescript` is exclusively generating declaration files (e.g., `emitDeclarationOnly: true`), or when an external transpiler (like Babel or `tsc`) handles `.ts` to `.js` conversion.

fix

Ensure your build pipeline clearly separates transpilation and path resolution steps. If using `rollup-plugin-typescript`, configure it to only emit declaration files and let `rollup-plugin-typescript-paths` handle runtime path resolution.

affects: >=1.0.0

gotchaThe `nonRelative` option, introduced in `v1.4.0`, defaults to `false` for backward compatibility. If you expect non-relative imports (modules not explicitly mapped in `paths`) to resolve based solely on `baseUrl`, you must explicitly set `nonRelative: true` in the plugin options. Failing to do so will prevent such imports from being resolved by this plugin.

fix

Add `nonRelative: true` to the `typescriptPaths` plugin options: `typescriptPaths({ nonRelative: true })`.

affects: >=1.4.0

gotchaIn `v1.3.1`, a bug was fixed where relative imports could be incorrectly resolved if a path alias partially matched the import string. While this was a bug fix, it changed resolution behavior. If your build pipeline or tests inadvertently relied on this incorrect behavior (which is highly unlikely), updating might subtly alter your module graph or import paths.

fix

Review your Rollup output or module resolution results after updating to ensure all modules are correctly resolved. This fix generally improves resolution accuracy.

affects: >=1.3.1

gotchaOlder versions of the plugin (prior to `v1.2.3`) had issues parsing `tsconfig.json` files that contained comments. If you encounter unexpected `tsconfig` parsing failures or `paths` not being recognized while using an older version, the presence of comments in your `tsconfig.json` might be the underlying cause.

fix

Update to `v1.2.3` or newer to benefit from the fix for parsing comments in `tsconfig.json`. Alternatively, remove any comments from your `tsconfig.json` if using an older version.

affects: <1.2.3

Errors

Common errors & fixes

TypeError: (0 , rollup_plugin_typescript_paths__WEBPACK_IMPORTED_MODULE_0__.typescriptPaths) is not a function

The plugin function `typescriptPaths` is a named export, but it's being imported as a default export or used with CommonJS `require` syntax, which does not correctly resolve the named export.

fix

Ensure you are using the correct ESM named import: `import { typescriptPaths } from 'rollup-plugin-typescript-paths';` in your Rollup configuration file.

RollupError: Could not resolve 'my-aliased-module' from 'src/entry.ts' (or similar 'Could not resolve' error for an aliased path)

The TypeScript path alias is not correctly configured in `tsconfig.json`, `baseUrl` or `paths` are incorrect, the `tsConfigPath` option in the plugin is pointing to the wrong file, or `nonRelative` is not enabled for bare `baseUrl` resolution without explicit `paths` entries.

fix

Double-check your `compilerOptions.baseUrl` and `compilerOptions.paths` in `tsconfig.json`. If your `tsconfig.json` is not in the project root, specify its path using the `tsConfigPath` option (e.g., `typescriptPaths({ tsConfigPath: './configs/tsconfig.build.json' })`). For non-relative imports based on `baseUrl` without specific `paths` entries, set `nonRelative: true` in the plugin options.

Error: Plugin 'typescriptPaths' did not return a plugin object.

The `typescriptPaths` function was added to the Rollup `plugins` array without being called, meaning it was passed as a function reference instead of the returned plugin object.

fix

Ensure you call the plugin function when adding it to your plugins array: `plugins: [typescriptPaths()]` instead of `plugins: [typescriptPaths]`.

Upgrade

Version history

1.5.0latest on npm

Audit

Dependencies

typescriptrequiredRequired peer dependency for TypeScript API access to resolve paths.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/simonhaenisch/rollup-plugin-typescript-paths ↗

packagehttps://www.npmjs.com/package/rollup-plugin-typescript-paths ↗