Dual publish ESM and CJS with tsdown

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([
  {
    // NOTE: this is the default but update if your entrypoint differs
    entry: "src/index.ts",
    format: ["esm", "cjs"],
    sourcemap: true,
  }
]);

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 created to show what we've seen here.

Hacksore / tsdown-dual-publish-esm-cjs

tsdown-dual-publish-esm-cjs

If you want to migrate from tsup this is a repo to follow.

pnpm i
pnpm test

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

…

View on GitHub