ts2esm
v2.2.7
Published
Transforms TypeScript imports and exports into ESM-compatible declarations.
Downloads
1,476
Maintainers
Readme
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.