You want to transform your project into an ECMAScript module (ESM)? Look no further! This tool (ts2esm) converts your TypeScript import and export declarations into ESM-compatible ones. 🪄
It also works with JavaScript projects since TypeScript is a superset of JavaScript.
Simply run this command to install ts2esm globally on your machine:
npm i -g ts2esmYou can also run it locally (without being globally installed):
npx ts2esmConvert your CommonJS projects (TypeScript or JavaScript) into ECMAScript modules with a single command. Just launch the program inside the directory of your project (it will ask you for your tsconfig.json path):
ts2esmYou can also provide a list of tsconfigs (no prompt):
ts2esm packages/foo/tsconfig.json packages/bar/tsconfig.jsonNote: The path can be specified absolutely (i.e. /home/user/cornerstone3D/tsconfig.json) or relative (i.e. ../../cornerstone3D/tsconfig.json).
There is also a debug mode with verbose logging:
ts2esm --debugWarning
Make sure you have a backup (in Git or similar) of your code as "ts2esm" will modify your source code.
Important
Use TypeScript 5.2 or later as there have been breaking changes to the Node.js settings, which you don't want to miss.
Important
Since TypeScript 5.3 import assertions are replaced with import attributes.
This workflow migrates a CommonJS project and checks its types:
# Build your project
npx tsc
# Check your types
npx @arethetypeswrong/cli --pack .
# Convert to ESM
npx ts2esm tsconfig.json
# Rebuild your project
npx tsc
# Check your types again
npx @arethetypeswrong/cli --pack . --ignore-rules cjs-resolves-to-esmWatch this 5-minute video and learn how to migrate from CommonJS to ESM:
Here you can see the transformations that ts2esm applies.
Before:
import {AccountAPI} from '../account';
import {RESTClient} from './client/RESTClient';
import {removeSuffix} from '@helpers/removeSuffix';After:
import {AccountAPI} from '../account/index.js';
import {RESTClient} from './client/RESTClient.js';
import {removeSuffix} from '@helpers/removeSuffix.js';Before:
export * from './account';
export * from './UserAPI';After:
export * from './account/index.js';
export * from './UserAPI.js';Before:
import listAccounts from '../test/fixtures/listAccounts.json';After:
import listAccounts from '../test/fixtures/listAccounts.json' with {type: 'json'};Before:
import styles from './MyComponent.module.css';After:
import styles from './MyComponent.module.css' with {type: 'css'};The ts2esm program adjusts your relative imports, adding extensions like index.js or .js to make them ESM-compatible. Say goodbye to import errors such as TS2305, TS2307, TS2834, and TS2835!
Errors that get automatically fixed (🛠️):
TypeError [ERR_IMPORT_ASSERTION_TYPE_MISSING]: Module needs an import assertion of type "json"
error TS2834: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Consider adding an extension to the import path.
error TS2835: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'.
With ESM, you can no longer use Node.js objects like __filename or __dirname. Here is a simple snippet to replicate their behavior using the import.meta property:
import path from 'node:path';
import url from 'node:url';
const __filename = url.fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);This program was born from an inspiring conversation I had with Basarat Ali Syed. I recommend checking out Basarat's coding tutorials. 👍
Ideally, the extension change would be available as a codefix in TypeScript itself. Then all conversions could be applied using ts-fix.