dts-paths

Replace alias paths with relative paths after typescript compilation.

Usage

1. Install

npm i -D dts-paths typescript

2. Compile declaration files first

tsc --emitDeclarationOnly

3. Rewrite alias paths in emitted files

import { resolvePaths } from 'dts-paths';

await resolvePaths('./dist/types', {
  tsconfig: './tsconfig.json'
});

4. Optional configuration

import { resolvePaths } from 'dts-paths';

await resolvePaths('./dist/types', {
  // Supports tsconfig path or inline tsconfig object
  tsconfig: './tsconfig.json',
  // Number of concurrent tasks for scanning/rewrite/rename stages
  concurrency: 16,
  // Skip files that do not need to be processed
  exclude: path => path.includes('/internal/'),
  // Rewrite module specifiers before resolving
  mapSpecifier: ({ specifier, importer }) => {
    if (importer.endsWith('legacy.d.ts') && specifier === 'lodash-es') {
      return 'lodash';
    }

    return specifier;
  },
  // Custom extension mapping strategy for import specifiers and file renaming
  mapExtension: ({ extname, importer }) => {
    // Import specifier rewrite stage
    if (importer && extname === '.ts') {
      return '.js';
    }

    // File rename stage: *.ts -> *.js, *.cts -> *.cjs, *.mts -> *.mjs by default
    return extname;
  },
  // Called when a specifier cannot be resolved
  onResolveFailed: ({ specifier, importer }) => {
    console.warn(`[dts-paths] failed to resolve '${specifier}' from '${importer}'`);
  }
});

API

resolvePaths(root, options?)

Returns Promise<Set<string>>; the set contains files whose content was rewritten. If a rewritten declaration file is renamed by mapExtension, the returned path is the renamed file path. Scan-stage entry read errors are skipped and do not interrupt the process.

options.tsconfig

• Type: string | TsConfig
• Default: './tsconfig.json'
• Supports either a tsconfig path or an inline object.
• Supported inline TsConfig.compilerOptions fields:
  • paths
  • rootDir
  • preserveSymlinks
• Use inline object is treated as a virtual tsconfig in cwd, following standard tsconfig rules.

options.concurrency

• Type: number
• Default: os.cpus().length
• Controls concurrent tasks for directory scanning, specifier rewriting, and output-file renaming.

options.exclude

• Type: (path: string) => boolean
• Default: () => false
• Filters declaration files during scanning.
• path is the relative path (from root) built with POSIX separators (for example: foo/bar.d.ts).

options.mapSpecifier

• Type: (context: MapSpecifierContext) => string
• Default: identity mapping (specifier => specifier)
• Called before resolving a module specifier.
• context contains:
  • specifier: module specifier from the original import/export
  • importer: file path of the declaration file that imports the package

options.mapExtension

• Type: (context: MapExtensionContext) => string
• Default mapping:
  • .ts / .tsx / .jsx -> .js
  • .cts -> .cjs
  • .mts -> .mjs
• Called in two places:
  • while rewriting import/export specifiers (context.importer is defined)
  • while renaming declaration output files (context.importer is undefined)
• context contains:
  • path: resolved file path being processed
  • extname: original extension from the resolved target path
  • importer: declaration file path that triggered the resolution (optional during rename stage)

options.onResolveFailed

• Type: (context: OnResolveFailedContext) => void
• Default: throws an Error
• Called when a module specifier cannot be resolved.
• context contains:
  • specifier: unresolved module specifier from the original import/export
  • importer: file path of the declaration file that imports/exports the unresolved specifier