There comes a time when you have to dual publish ESM (ECMAScript) and CJS (CommonJS) for your TypeScript projects. This guide should walk you through the steps to get this working properly with tsdown.
NOTE: if you are using tsup there is a codemod provided by tsdown to migrate.
tsdown setup
First let’s install tsdown with your favorite package manager, in this case I’ll be using pnpm.
pnpm i -D tsdown
Now we can create the tsdown.config.ts file that will have our configuration.
import { defineConfig } from "tsdown";
export default defineConfig([
{
entry: ["src/index.ts"],
format: ["esm", "cjs"],
dts: true,
sourcemap: true,
clean: true,
outDir: "dist"
}
]);
package json setup
It’s important to get these right otherwise types will fail to resolve in every scenario.
Add the following to your package.json file.
{
// ...
"files": [
"dist"
],
"main": "./dist/index.cjs",
"module": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"import": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
"require": {
"types": "./dist/index.d.cts",
"default": "./dist/index.cjs"
}
}
}
// ...
}
validation
We can us the are the types wrong CLI to interrogate the output and ensure type resolution is working in all scenarios.
npx -y @arethetypeswrong/cli --pack .
Which should yield something like this if all goes well.
No problems found 🌟
┌───────────────────┬───────────────────────────────┐
│ │ "tsdown-dual-publish-esm-cjs" │
├───────────────────┼───────────────────────────────┤
│ node10 │ 🟢 │
├───────────────────┼───────────────────────────────┤
│ node16 (from CJS) │ 🟢 (CJS) │
├───────────────────┼───────────────────────────────┤
│ node16 (from ESM) │ 🟢 (ESM) │
├───────────────────┼───────────────────────────────┤
│ bundler │ 🟢 │
└───────────────────┴───────────────────────────────┘
Demo
Here is a simple demo I’ve create to show what we’ve seen here.
If you want to migrate from tsup this is a repo to follow.
What the ouput of test looks like.
> tsdown
ℹ tsdown v0.14.2 powered by rolldown v1.0.0-beta.34
ℹ Using tsdown config: /Users/hacksore/code/tsdown-dual-publish-esm-cjs/tsdown.config.ts
ℹ entry: src/index.ts
ℹ tsconfig: tsconfig.json
ℹ Build start
ℹ Cleaning 4 files
ℹ [CJS] dist/index.cjs 0.10 kB │ gzip: 0.11 kB
ℹ [CJS] 1 files, total: 0.10 kB
ℹ [CJS] dist/index.d.cts 0.09 kB │ gzip: 0.10 kB
ℹ [CJS] 1 files, total: 0.09 kB
ℹ [ESM] dist/index.js 0.10 kB │ gzip: 0.11 kB
ℹ [ESM] dist/index.d.ts 0.09 kB │ gzip: 0.10 kB
ℹ [ESM] 2 files, total: 0.19 kB
✔ Build complete in 575ms
tsdown-dual-publish-esm-cjs v0.0.0
Build tools:
- typescript@~5.8.3
- tsdown@^0.14.2
No problems found 🌟
┌───────────────────┬───────────────────────────────┐
│ │ "tsdown-dual-publish-esm-cjs" │
├───────────────────┼───────────────────────────────┤
│ node10 │ 🟢 │
├───────────────────┼───────────────────────────────┤
│ node16 (from CJS) │ 🟢 (CJS) │
├───────────────────┼───────────────────────────────┤
│ node16 (from…
