Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

tsc-esm-fix

Package Overview
Dependencies
Maintainers
1
Versions
77
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

tsc-esm-fix

Make tsc-compiled `es2020/esnext` bundles compatible with esm/mjs requirements

  • 2.20.21
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
16K
increased by5.11%
Maintainers
1
Weekly downloads
 
Created
Source

tsc-esm-fix

Make TS projects compatible with esm/mjs requirements

CI Maintainability Test Coverage npm (tag)

Problem

This workaround is aimed to bypass a bunch of tsc, ts-jest and esbuild issues right here and right now.

  • TS/13422 / TS/16577: tsc should add .js extensions for relative module paths if compiled as es2020/esnext.
  • ts-jest/1174: import.meta is not allowed.
  • esbuild/1043: empty output for interface files that breaks reimport.
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 .js extension to be added to all .d.ts files of external ESM packages too. Well, good luck with that.

Solutions

  1. Post-process tsc-compiled outputs each time after build.
  2. Patch project sources once as Sindre recommends in the ESM migration guide
  3. 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
    • Does not affect string literals and comments: depseek
  • Handles conditional exports (https://nodejs.org/api/packages.html#conditional-exports)
  • 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 >=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';

// 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]
OptionDescriptionDefault
--tsconfigPath to project's ts-config(s)tsconfig.json
--srcEntry points where the ts-source files are placed. If defined src option suppresses target
--targettsc-compiled output directoryIf not specified inherited from tsconfig.json compilerOptions.outDir
--dirnameVarReplace __dirname usages with import.metatrue
--filenameVarReplace __filename var references with import.meta statementstrue
--extAppend extension to relative imports/re-exports.js
--unlinkRemove original files if ext changestrue
--fillBlankFill blank files with export {}false
--forceDefaultExportInjects export default undefined if not presentfalse
--sourceMapPatch source map files to point to the updated files.false
--cwdcwdprocess.cwd()
--outOutput dir. Defaults to cwd, so files would be overwrittenprocess.cwd()
--debugPrints 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
  sourceMap?: 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

Keywords

FAQs

Package last updated on 31 Dec 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc