Bundling and publishing: ESM, CJS, and exports

Two module formats, and how Node chooses

Node runs your code as one of two formats, and the choice is made before any import resolves. A package is ESM if its package.json has "type": "module" (or the file ends in .mjs); otherwise it is CommonJS (or .cjs). This single field changes everything downstream: ESM uses static import/export and top-level await; CJS uses require/module.exports. You cannot require() an ESM-only package from CJS without await import(), and ESM consumers can import a CJS package but only get its default export cleanly.

The hard problem is publishing for both kinds of consumer — a dual package. The tempting answer is to ship a dist/esm/ and a dist/cjs/ build of the same code. It works until it doesn’t: a consumer whose dependency graph pulls your CJS copy on one path and your ESM copy on another now has two distinct module instances loaded at once. Two copies means two class identities, so instanceof fails across the boundary, and any module-level state (a cache, a registry, a singleton) is silently duplicated. This is the dual-package hazard, and it is genuinely hard to fully avoid. For most new libraries the pragmatic answer is ship ESM-only — Node has supported ESM in production for years — or use a build tool that emits both and keep all shared identity/state in a single internal CJS core that both wrappers re-export.

# ESM-only is the simplest contract: one format, no hazard
# package.json
{
  "type": "module",
  "exports": "./dist/index.js"
}

The exports map: entry points and encapsulation

If two packages share a boundary and one can reach arbitrarily deep into the other’s internals, you lose the ability to refactor without breaking your consumers — and the fix is not tests, it’s the exports map.

The "exports" field is the modern entry point and supersedes "main". It does two jobs at once. First, conditional resolution: you map the same specifier to different files depending on how it’s loaded — "import" for ESM, "require" for CJS, "types" for TypeScript, and "default" as the fallback. Order matters; Node reads conditions top-to-bottom and takes the first match, so "types" and the most specific conditions go first, "default" last. Second, subpath exports: "./feature" exposes a deep entry without leaking your folder layout.

The part seniors care about most is encapsulation. Once you define "exports", only the listed subpaths are importable. A consumer can no longer reach your-pkg/dist/internal/secret.js — that import throws ERR_PACKAGE_PATH_NOT_EXPORTED. This is the field that would have saved the hook team: with an exports map, the internal file was never part of the contract, so moving it is free. Keep "main" as a fallback for ancient tooling that ignores exports, and always provide a "types" condition so TypeScript consumers get real types instead of any.

{
  "name": "their-lib",
  "type": "module",
  "main": "./dist/index.cjs",        // fallback for old tools
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",  // first: TS reads this
      "import": "./dist/index.js",   // ESM consumers
      "require": "./dist/index.cjs", // CJS consumers
      "default": "./dist/index.js"   // last-resort fallback
    },
    "./feature": "./dist/feature.js" // explicit subpath; nothing else is reachable
  }
}

Together these fields form a layered contract: type and exports define the module surface, files and sideEffects shape what lands in the tarball and how bundlers treat it, and bin/engines cover CLI and runtime compatibility. Skip any one of them and you ship a contract with an invisible hole — the kind that surfaces in someone else’s CI three months later.

Tree-shaking, the CLI bin, and publish hygiene

ESM’s static structure is what lets a bundler tree-shake — analyze imports at build time and drop code no one reaches. CJS resists this: require is a dynamic function call, so a bundler usually can’t prove a branch is dead. You help the bundler with "sideEffects": false, a promise that importing your modules does nothing but define exports (no global mutation, no polyfill registration). With that flag, an unused export of yours can be pruned entirely; without it the bundler must keep modules around in case the import itself mattered.

A CLI is just a "bin" mapping from command name to a file. Three things must line up or the command silently fails to run: the target file needs a shebang #!/usr/bin/env node as its first line, it needs execute permission (chmod +x), and on install npm creates the symlink into node_modules/.bin for you. Forget the shebang and the shell tries to run JS as a shell script; forget the permission bit and you get “permission denied.”

{
  "bin": { "their-cli": "./dist/cli.js" },
  "files": ["dist"],
  "engines": { "node": ">=18.17" },
  "sideEffects": false
}

Finally, ship the build, not the source. A bundler like tsup/esbuild/rollup emits dist/ plus .d.ts declarations; use the "files" allowlist (or .npmignore) so the tarball contains only dist — not your src/, tests, or .env. Run npm pack --dry-run to see the exact file list before you publish. Bump versions by semver (a removed export or new exports map is major). And publish with npm publish --provenance from CI so npm records a signed attestation linking the artifact to the commit and workflow that built it — a supply-chain defense against tampered or typosquatted releases.