tsc-esm-fix
Make TS projects compatible with esm/mjs requirements
Problem
This workaround is aimed to bypass a bunch of tsc, ts-jest and esbuild issues right here and right now.
moduleResolution: nodenext
Nightly build TypeScript 4.7 provides experimental esm support. But it still forces to add extensions by hand (tested on 4.7.0-dev.20220408).
src/main/ts/q/u/x/index.ts:1:21 - error TS2835: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node12' or 'nodenext'. Did you mean '../../../foo.js'?
1 import { foo } from '../../../foo'
Moreover, if understand TS/49271 correctly, nodenext
+ pkg.json type: module
requires the .js
extension in .d.ts
files of external ESM packages too. Well, good luck with that.
Solutions
- Post-process tsc-compiled outputs each time after build.
- Patch project sources once as Sindre recommends in ESM migration guide
- Use ttypescript with transformer-append-js-ext plugin
This lib covers options 1 and 2.
Features
- Injects extensions to imports/re-exports statements.
import {foo} from './foo'
→ import {foo} from './foo.js'
import {baz} from 'external/baz'
→ import {baz} from 'external/baz.js'
- Note, including the file extension is only necessary for packages without an "exports" field. So in this case all the external refs remain as are.
- Pays attention to index files:
import {bar} from './bar'
→ import {bar} from './bar/index.js'
- Handles
.
and ..
shortcuts
export * from '.'
→ export * from './index.js'
export * from '..'
→ export * from '../index.js'
- Injects
.js
extensions into .d.ts
libdef files
- Follows
outDir
found in tsconfig.json. - Searches and replaces
__dirname
and __filename
refs with import.meta
. - Fills blank files with
export {}
(esbuild issue 1043) - Patches source map files to point to the updated files.
- Patches
require
statements with new file refs if ext changes (hybrid/dual pkg) - Changes file extensions (applied to local deps only).
- Supports Windows-based runtimes.
Getting started
Requirements
Node.js ^12.20.0 || ^14.13.1 || >=16.0.0
Fetching
npm i -dev tsc-esm-fix
yarn add -D tsc-esm-fix
# or w/o saving to package.json
npx tsc-esm-fix [options]
Usage examples
tsc-esm-fix [options]
# to post-process outputs each time
tsc-esm-fix --target='target/es6'
# to patch ts sources once
tsc-esm-fix --src='src/main/ts' --ext='.js'
import { fix } from 'tsc-esm-fix'
await fix({
dirnameVar: true,
filenameVar: true,
ext: true
})
Input
code ref
import { foo } from './foo';
import './bar';
import * as e1def from 'e1/a/b/c';
import * as e1root from 'e1';
const { e1 } = e1def;
const { e1: e1x } = e1root;
export { e1, e1x };
export { m1 } from 'm1';
export { m1 as m1x } from 'm1/index';
export { e2 } from 'e2';
export { e2 as es3 } from 'e2/index';
export { e2 as es4 } from 'e2/alias';
export { e2foo } from 'e2/foo';
export { e2bar } from 'e2/bar-bundle';
export * from './foo';
export * from './baz';
export * from './q/u/x';
export const foobaz = foo + 'baz';
export { foo as foo1 } from './foo.js';
export { qux } from './qux.js';
export const dirname = __dirname;
export const filename = __filename;
console.log(foobaz);
Output
import { foo } from './foo.js';
import './bar.js';
import * as e1def from 'e1/a/b/c/index.js';
import * as e1root from 'e1';
const { e1 } = e1def;
const { e1: e1x } = e1root;
export { e1, e1x };
export { m1 } from 'm1';
export { m1 as m1x } from 'm1/index.js';
export { e2 } from 'e2';
export { e2 as es3 } from 'e2/index';
export { e2 as es4 } from 'e2/alias';
export { e2foo } from 'e2/foo';
export { e2bar } from 'e2/bar-bundle';
export * from './foo.js';
export * from './baz/index.js';
export * from './q/u/x/index.js';
export const foobaz = foo + 'baz';
export { foo as foo1 } from './foo.js';
export { qux } from './qux.js/index.js';
export const dirname = /file:\\\\/\\\\/(.+)\\\\/[^/]/.exec(import.meta.url)[1];
export const filename = /file:\\\\/\\\\/(.+)/.exec(import.meta.url)[1];
CLI
tsc-esm-fix [opts]
Option | Description | Default |
---|
--tsconfig | Path to project's ts-config(s) | tsconfig.json |
--src | Entry points where the ts-source files are placed. If defined src option suppresses target | |
--target | tsc-compiled output directory | If not specified inherited from tsconfig.json compilerOptions.outDir |
--dirnameVar | Replace __dirname usages with import.meta | true |
--filenameVar | Replace __filename var references with import.meta statements | true |
--ext | Append extension to relative imports/re-exports | .js |
--unlink | Remove original files if ext changes | true |
--fillBlank | Fill blank files with export {} | false |
--forceDefaultExport | Injects export default undefined if not present | false |
--sourceMap | Patch source map files to point to the updated files. | false |
--cwd | cwd | process.cwd() |
--out | Output dir. Defaults to cwd , so files would be overwritten | process.cwd() |
--debug | Prints debug notes | |
--target vs --src
When --src
option is used, the util just modifies file contents in place.
--target
also renames files to change their extension.
You may prevent deletion original of files by using --no-unlink
.
glob patterns
By default, the util looks for ts/tsx
files in src
directory and js/d.ts
files in target
. But you can specify custom patterns via corresponding options. For example: --src='src/main/ts/**/*.ts'
.
const patterns =
sources.length > 0
? sources.map((src) => src.includes('*') ? src : `${src}/**/*.{ts,tsx}`)
: targets.map((target) => target.includes('*') ? target : `${target}/**/*.{js,d.ts}`)
JS/TS API
import { fix, IFixOptions } from 'tsc-esm-fix'
const fixOptions: IFixOptions = {
tsconfig: 'tsconfig.build.json',
dirnameVar: true,
filenameVar: true,
ext: true
}
await fix(fixOptions)
export interface IFixOptions {
cwd: string
src?: string | string[]
target?: string | string[]
out?: string
tsconfig?: string | string[]
dirnameVar: boolean
filenameVar: boolean
fillBlank?: boolean
forceDefaultExport?: boolean
ext: boolean | string
unlink?: boolean,
debug?: boolean | IFunction
}
Alternatives
Contributing
Feel free to open any issues: bug reports, feature requests or questions.
You're always welcome to suggest a PR. Just fork this repo, write some code, add some tests and push your changes.
Any feedback is appreciated.
References
License
MIT