README
tsc-esm-fix
Make TS projects compatible with esm/mjs requirements
Problem
This workaround is aimed to bypass a pair of tsc and ts-jest issues right here and right now.
- TS/13422 / TS/16577: tsc should add
.js
extensions for relative module paths if compiled ases2020/esnext
. - ts-jest/1174:
import.meta
is not allowed.
Solutions
- Post-process tsc-compiled outputs everytime after the build.
- Patch project sources once as Sindre recommends in ESM migration guide
This lib may be applied in both cases.
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'
- Follows
outDir
found in tsconfig.json. - Searches and replaces
__dirname
and__filename
refs withimport.meta
. - 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
Install
yarn add -D tsc-esm-fix
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 --target='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';
// external cjs module
import * as e1def from 'e1/a/b/c';
import * as e1root from 'e1';
const { e1 } = e1def;
const { e1: e1x } = e1root;
export { e1, e1x };
// external esm module with `main` in pkg.json
export { m1 } from 'm1';
export { m1 as m1x } from 'm1/index';
// external esm module with `exports` in pkg.json
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';
// Dir with index.js file inside: ./qux.js/index.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 |
--cwd |
cwd | process.cwd() |
--out |
Output dir. Defaults to cwd , so files would be overwritten |
process.cwd() |
--debug |
Prints debug notes |
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
ext: boolean | string
unlink?: boolean,
debug?: boolean | IFunction
}
Alternatives
- https://github.com/mothepro/tsc-esm
- https://github.com/digital-loukoum/tsc-esm
- https://github.com/beenotung/fix-esm-import-path
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
- TypeScript/issues/13422: TypeScript and script type="module"
- TypeScript/issues/28288: Feature: disable extensionless imports
- ts-jest/issues/1174: import.meta not allowed
- stackoverflow.com/how-to-use-import-meta-when-testing-with-jest
- Pure ESM package
- stackoverflow.com/alternative-for-dirname-in-node-when-using-the-experimental-modules-flag
- ecma262/#sec-imports
- ERR_REQUIRE_ESM
- Publishing Node modules with TypeScript and ES modules