ts2esm

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.

Installation

Simply run this command to install ts2esm globally on your machine:

npm i -g ts2esm

You can also run it locally (without being globally installed):

npx ts2esm

Usage

Convert 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):

ts2esm

You can also provide a list of tsconfigs (no prompt):

ts2esm packages/foo/tsconfig.json packages/bar/tsconfig.json

Note: 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 --debug

[!WARNING]
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.

Video Tutorial

Watch this 5-minute video and learn how to migrate from CommonJS to ESM:

Examples

Here you can see the transformations that ts2esm applies.

Import Declarations

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';

Export Declarations

Before:

export * from './account';
export * from './UserAPI';

After:

export * from './account/index.js';
export * from './UserAPI.js';

JSON Import Attributes

Before:

import listAccounts from '../test/fixtures/listAccounts.json';

After:

import listAccounts from '../test/fixtures/listAccounts.json' with {type: 'json'};

CSS Import Attributes

Before:

import styles from './MyComponent.module.css';

After:

import styles from './MyComponent.module.css' with {type: 'css'};

How it works

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'.

Noteworthy

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);

Credits

This program was born from an inspiring conversation I had with Basarat Ali Syed. I recommend checking out Basarat's coding tutorials. 👍

Used By

Vision

Ideally, the extension change would be available as a codefix in TypeScript itself. Then all conversions could be applied using ts-fix.

References

• TypeScript's Module Resolution
• TypeScript AST Viewer
• Are the types wrong?