Ts2esm NPM | npm.io

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.

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