ts-transform-esm-import

Rewrite TypeScript import paths to ES Modules import paths. TypeScript 4.9+!. A fork of ts-transform-import-path-rewrite.

Features

Feature	Status	Note
Add .js extension	✅
Resolving baseUrl	✅
CommonJS main	✅
CommonJS subpath	✅
CommonJS module	✅
ESM single string entry	✅
ESM Subpath imports	✅	https://nodejs.org/api/packages.html#subpath-imports
ESM Subpath patterns	❌	https://nodejs.org/api/packages.html#subpath-patterns
ESM Conditional exports	❌	https://nodejs.org/api/packages.html#conditional-exports

Before:

1// Files in `node_modules`.
2import 'npmModule';
3import 'npmModule/lib';
4
5// Files resolved by `tsconfig.baseUrl`.
6import 'subDir/file';
7import 'rootFile';
8
9// Relative paths.
10import './rootFile';
11import './subDir/file';

After:

1// Files in `node_modules`.
2import '../node_modules/npmModule/dist/main.js';
3import '../node_modules/npmModule/lib.js';
4
5// Files resolved by `tsconfig.baseUrl`.
6import './subDir/file.js';
7import './rootFile.js';
8
9// Relative paths.
10import './rootFile.js';
11import './subDir/file.js';

Usage

See example for a runnable project.

• Install ts-patch and follow its instructions.
• Use this project as a plugin of ts-patch.

An example tsconfig.json

1{
2  "compilerOptions": {
3    "declaration": true,
4    "newLine": "lf",
5    "strict": true,
6    "module": "ESNext",
7    "moduleResolution": "node",
8    "outDir": "./dist",
9    "baseUrl": "src",
10    "rootDir": "./src",
11    "plugins": [
12      {
13        "transform": "ts-transform-esm-import",
14        "after": true,
15        "afterDeclarations": true,
16        "type": "config",
17
18        "rootDir": "./src",
19        "outDir": "./dist/src",
20        "resolvers": [{ "dir": "./src", "sourceDir": true }, { "dir": "./node_modules" }]
21      }
22    ]
23  }
24}

Options

• rootDir source files root directory, should be the rootDir in tsconfig.json.
• outDir output directory, should be the outDir in tsconfig.json.
• after, afterDeclarations, type see ts-patch Options.
• resolvers a list of resolvers that define how imports are transformed.
  • dir: string search location for imports.
  • (Optional) sourceDir: boolean whether search location contains source files (ts files).
  • (Optional) filter: string regex string, run resolver only when filter tests true
  • (Optional) mode: string overrides default resolving mode, possible values:
    • addExt only adds extensions to imports.

Resolver examples

To transform imports in node_modules:

1{
2  "rootDir": "./src",
3  "outDir": "./dist/src",
4  "resolvers": [{ "dir": "./node_modules" }]
5}

To transform imports using TypeScript baseUrl, set sourceDir to true, which indicates that we are travelling inside the source directory:

1{
2  "rootDir": "./src",
3  "outDir": "./dist/src",
4  "resolvers": [{ "dir": "./src", "sourceDir": true }]
5}

To apply a resolver only on a subset of imports, use the filter field (a regex value). For example, to rewrite imports starting with @myOrg/:

1{
2  "rootDir": "./src",
3  "outDir": "./dist/src",
4  "resolvers": [{ "dir": "./node_modules", "filter": "^@myOrg/" }]
5}

Sometimes the default resolving mode might confuse you. You can override it via the mode field. Currently, only one option (addExt) is supported, which simply adds a .js extension if needed.

1{
2  "rootDir": "./src",
3  "outDir": "./dist/src",
4  "resolvers": [{ "dir": "./node_modules", "mode": "addExt" }]
5}

You can combine multiple resolvers. For example, to do the following things altogether:

• Add missing .js extensions to all imports starting with @myOrg/
• Transform imports using TypeScript baseUrl
• Transform imports in node_modules

Use the following config:

1{
2  "rootDir": "./src",
3  "outDir": "./dist/src",
4  "resolvers": [
5    { "dir": "./node_modules", "filter": "^@myOrg/", "mode": "addExt" },
6    { "dir": "./src", "sourceDir": true },
7    { "dir": "./node_modules" }
8  ]
9}

FAQ

Import paths not rewritten

Make sure your module field in tsconfig.json is not commonjs, esnext is recommended.