ts2esm

You want to transform your TypeScript project into an ECMAScript module (ESM)? Look no further! This tool (ts2esm) converts your import and export declarations into ESM-compatible ones. It's the ideal tool for converting a CommonJS project to ESM. It also works with plain JavaScript projects! 🪄

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.

Step-by-Step Guide

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-esm

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.

Require Statements

Before:

const fs = require('node:fs');
const path = require('path');

After:

import fs from 'node:fs';
import path from 'path';

Module Exports

Before:

const Benny = 1;
const Code = 2;

module.exports = Benny;
module.exports.Code = Code;

After:

const Benny = 1;
const Code = 2;

export default Benny;
export {Code};

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

Attributions

• ts2esm got highlighted in Deno's article on How to convert CommonJS to ESM
• ts2esm helped migrating cornerstonejs/cornerstone3D from CommonJS to ESM

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?