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.

Guide

Convert your CommonJS projects (TypeScript or JavaScript) into ECMAScript modules with these simple steps:

1. Add "type": "module" in your package.json
2. Set module to "nodenext" in your tsconfig.json
3. Set moduleResolution to "nodenext" in your tsconfig.json
4. Run ts2esm in the directory of your TypeScript project

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

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

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

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.

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

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?