ECMAScript modules (esm) is the official way to handle imports and exports in Javascript, but CommonJS (cjs) has been part of the ecosystem do so long that support for it still feels necessary.
In this post I'll show my method for publishing an npm package that exports both esm and cjs compatible code.
The code is available on stackblitz.
Note: it is better to view the code on stackblitz as the embedding shows some errors that aren't real.
src
For example purposes, the src/
directory is more complicated than it needs to be. There is an index.ts
file, which exports modules from the arithmetic/
directory.
tools
Besides Typescript, this process also relies on tsc-alias
and @alcalzone/esm2cjs
.
The first is used to add .js
extensions for imports, which isn't necessary in all contexts, but doesn't hurt.
The second compiles esm projects to cjs.
So right away, you can see there is quite a lot happening in the build process — tsc, tsc-alias, and esm2cjs.
This isn't ideal for large projects, but for small projects the build time is minimal.
configs
This is the minimal tsconfig config needed:
{
"compilerOptions": {
"declaration": true,
"declarationDir": "dist/types",
"esModuleInterop": true,
"lib": ["ES2021"],
"module": "ESNext",
"moduleResolution": "Node",
"outDir": "dist/esm",
"target": "ES2021"
},
"tsc-alias": {
"resolveFullPaths": true,
"verbose": true
},
"include": ["src"],
"exclude": ["node_modules", "test"]
}
Note the config for tsc-alias
.
package.json
The most complicated part is the package.json
:
{
"name": "tsc-as-cjs-esm",
"version": "0.1.0",
"main": "./dist/cjs/index.js",
"module": "./dist/esm/index.js",
"types": "./dist/types/index.d.ts",
"files": ["dist"],
"exports": {
"./package.json": "./package.json",
".": {
"types": "./dist/types/index.d.ts",
"require": "./dist/cjs/index.js",
"import": "./dist/esm/index.js"
}
},
"scripts": {
"start": "tsc --watch",
"build": "tsc && tsc-alias -p tsconfig.json",
"postbuild": "esm2cjs --in dist/esm --out dist/cjs -l error"
},
"devDependencies": {
"@alcalzone/esm2cjs": "^1.1.2",
"tsc-alias": "^1.8.8",
"typescript": "^5.2.2"
}
}
The exports
block lets node know where to look when importing or requiring a module.
building
You can build the package by running npm run build
. This causes:
- Typescript to compile the project
- tsc-alias to add file extensions
- esm2cjs to create a cjs package from the above output
This creates a dist/
directory that looks like this:
dist
├── cjs
├── esm
└── types
Inside esm/
and cjs/
each, there is a package.json
.
// dist/esm/package.json
{
"type": "module"
}
and
// dist/cjs/package.json
{
"type": "commonjs"
}
After that, running npm pack
creates a tarball and copies the root package.json
to the package.
testing
Create a package that uses esm modules with a package.json:
{
"name": "test",
"main": "index.js",
"type": "module"
}
Note the "type": "module"
,
Move the tarball into the repo (not necessary) and install the it using npm i tsc-as-cjs-esm-0.1.0.tgz
.
Then in index.js
, you can do:
import { add } from "tsc-as-cjs-esm";
console.log(add(1, 2));
If you remove the "type": "module"
line, you'll get an error and have to use cjs syntax:
const math = require("tsc-as-cjs-esm");
const add = math.add;
console.log(add(1, 2));
Top comments (0)