Ts2esm NPM | npm.io

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:

Add "type": "module" in your package.json
Set module to "nodenext" in your tsconfig.json
Set moduleResolution to "nodenext" in your tsconfig.json
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

Afterwards, just launch the program inside the directory of your project (it will ask you for your tsconfig.json):

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