Rollup TypeScript Path Aliases Plugin

Common errors

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

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

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

  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.
  fix Ensure you call the plugin function when adding it to your plugins array: `plugins: [typescriptPaths()]` instead of `plugins: [typescriptPaths]`.

Warnings

• breaking 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.
  Fix: Update your import to `import { typescriptPaths } from 'rollup-plugin-typescript-paths';` and ensure you call it in your plugins array: `plugins: [typescriptPaths()]`.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Add `nonRelative: true` to the `typescriptPaths` plugin options: `typescriptPaths({ nonRelative: true })`.
• gotcha 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.
  Fix: Review your Rollup output or module resolution results after updating to ensure all modules are correctly resolved. This fix generally improves resolution accuracy.
• gotcha 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.
  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.

Install

• npm install rollup-plugin-typescript-paths npm
• yarn add rollup-plugin-typescript-paths yarn
• pnpm add rollup-plugin-typescript-paths pnpm

Imports

• typescriptPaths
  wrong:

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

  correct:

  import { typescriptPaths } from '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)
  wrong:

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

  correct:

  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.

Quickstart

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;
      }
    }),
  ],
};