{"id":11959,"library":"rollup-plugin-typescript-paths","title":"Rollup TypeScript Path Aliases Plugin","description":"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/*`.","status":"active","version":"1.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/simonhaenisch/rollup-plugin-typescript-paths","tags":["javascript","rollup-plugin","typescript"],"install":[{"cmd":"npm install rollup-plugin-typescript-paths","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-typescript-paths","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-typescript-paths","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for TypeScript API access to resolve paths.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"const typescriptPaths = require('rollup-plugin-typescript-paths');","symbol":"typescriptPaths","correct":"import { typescriptPaths } from 'rollup-plugin-typescript-paths';"},{"note":"The main plugin function, `typescriptPaths`, is a named export, not a default export. Importing it as a default will result in a runtime error.","wrong":"import typescriptPaths from 'rollup-plugin-typescript-paths';","symbol":"typescriptPaths (incorrect default)","correct":"import { typescriptPaths } from 'rollup-plugin-typescript-paths';"},{"note":"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.","symbol":"Options (type)","correct":"import type { Options } from 'rollup-plugin-typescript-paths';"}],"quickstart":{"code":"/* rollup.config.js */\nimport { typescriptPaths } from 'rollup-plugin-typescript-paths';\nimport typescript from '@rollup/plugin-typescript'; // Used here for declaration generation\n\n// --- Context: Minimal tsconfig.json for this example ---\n// Create a `tsconfig.json` in your project root with:\n// {\n//   \"compilerOptions\": {\n//     \"target\": \"es2018\",\n//     \"module\": \"esnext\",\n//     \"baseUrl\": \".\",\n//     \"paths\": {\n//       \"@components/*\": [\"src/components/*\"],\n//       \"@utils\": [\"src/lib/utils/index.ts\"]\n//     },\n//     \"lib\": [\"es2018\", \"dom\"],\n//     \"declaration\": true,\n//     \"emitDeclarationOnly\": true,\n//     \"strict\": true\n//   },\n//   \"include\": [\"src/**/*.ts\"],\n//   \"exclude\": [\"node_modules\"]\n// }\n\n// --- Context: Source files for this example ---\n// Create `src/index.ts`:\n// import { greeting } from '@utils';\n// import { Button } from '@components/Button';\n// console.log(greeting('Rollup'));\n// new Button().render();\n\n// Create `src/lib/utils/index.ts`:\n// export const greeting = (name: string) => `Hello, ${name}!`;\n\n// Create `src/components/Button.ts`:\n// export class Button { render() { console.log('Button rendered!'); } }\n\nexport default {\n  input: 'src/index.ts',\n  output: {\n    dir: 'dist',\n    format: 'es',\n    sourcemap: true,\n  },\n  plugins: [\n    // Use @rollup/plugin-typescript for declaration files only, or skip if already transpiled\n    typescript({ declaration: true, declarationDir: 'dist/types', emitDeclarationOnly: true }),\n    typescriptPaths({\n      // Optional: Set to true if you want to resolve non-relative paths\n      // based on tsconfig's baseUrl even if no `paths` are matched.\n      nonRelative: true,\n      // Optional: Custom path to your tsconfig.json if not in project root\n      // tsConfigPath: './configs/tsconfig.build.json',\n      transform: (path, id) => {\n        // Example: Log the resolved paths for debugging\n        // console.log(`Resolved import ${id} to ${path}`);\n        return path;\n      }\n    }),\n  ],\n};","lang":"typescript","description":"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."},"warnings":[{"fix":"Update your import to `import { typescriptPaths } from 'rollup-plugin-typescript-paths';` and ensure you call it in your plugins array: `plugins: [typescriptPaths()]`.","message":"The 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.","severity":"breaking","affected_versions":"<1.2.1"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `nonRelative: true` to the `typescriptPaths` plugin options: `typescriptPaths({ nonRelative: true })`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.4.0"},{"fix":"Review your Rollup output or module resolution results after updating to ensure all modules are correctly resolved. This fix generally improves resolution accuracy.","message":"In `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.","severity":"gotcha","affected_versions":">=1.3.1"},{"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.","message":"Older 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.","severity":"gotcha","affected_versions":"<1.2.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using the correct ESM named import: `import { typescriptPaths } from 'rollup-plugin-typescript-paths';` in your Rollup configuration file.","cause":"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.","error":"TypeError: (0 , rollup_plugin_typescript_paths__WEBPACK_IMPORTED_MODULE_0__.typescriptPaths) is not a function"},{"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.","cause":"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.","error":"RollupError: Could not resolve 'my-aliased-module' from 'src/entry.ts' (or similar 'Could not resolve' error for an aliased path)"},{"fix":"Ensure you call the plugin function when adding it to your plugins array: `plugins: [typescriptPaths()]` instead of `plugins: [typescriptPaths]`.","cause":"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.","error":"Error: Plugin 'typescriptPaths' did not return a plugin object."}],"ecosystem":"npm"}