ts2esm
v2.0.0
Published
Transforms TypeScript imports and exports into ESM-compatible declarations.
Downloads
1,021
Maintainers
Readme
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 yourpackage.json
- Set module to
"nodenext"
in yourtsconfig.json
- Set moduleResolution to
"nodenext"
in yourtsconfig.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'.
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.