ESM and CJS Dual Package Output

ESM (ECMAScript Modules) is the official JavaScript module standard using import and export syntax. ESM is statically analyzable — bundlers can determine at build time exactly which exports are used, enabling tree-shaking. Modern browsers and Node.js both support ESM natively.

CJS (CommonJS) uses require() and module.exports syntax. It was Node.js's original module system and is still needed for compatibility with older Node.js environments, Jest (which historically used CJS), and code that uses require(). CJS is dynamically evaluated, making tree-shaking harder.

A modern npm package should ship both ESM and CJS to maximize compatibility. ESM consumers (Vite, Next.js, modern bundlers) get tree-shakable imports. CJS consumers (older Node.js scripts, Jest without configuration) get require() compatibility. The package.json exports field tells Node and bundlers which format to use.

The exports field in package.json is the modern way to define conditional entry points. Example: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Bundlers and Node.js 12+ read exports to select the correct format automatically.

Older tooling does not understand the exports field. For compatibility, also set: main pointing to the CJS output (legacy Node require fallback), and module pointing to the ESM output (a hint for webpack/rollup, non-standard but widely supported). Modern tooling prefers exports, legacy tooling falls back to main/module.

Setting "type": "module" in package.json makes all .js files in the package treated as ESM. If you ship dual format, you then need explicit extensions: use .mjs for ESM files and .cjs for CJS files when type is module, or vice versa. tsup handles this automatically.

Using .mjs (ESM) and .cjs (CJS) file extensions explicitly marks the format regardless of the type field. This avoids ambiguity. tsup can output: index.js (ESM) and index.cjs (CJS) when format is ['esm', 'cjs'] and no type field is set, matching the most common convention.

When a package provides both ESM and CJS formats, a consumer's bundler might load both versions in the same process — for example, the ESM version for the main app and the CJS version for a Jest test. If the package has module-level state (like a React context), both instances have independent state. This is the dual package hazard.

To mitigate the hazard: keep module-level state out of your library (no singleton patterns), use the exports conditions precisely to ensure only one format loads, and document that tests should configure their bundler to use ESM. The hazard is a concern mainly for libraries with shared singletons.

Verify both formats work after building. Test CJS: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Test ESM: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Both should resolve without errors before publishing.

The exports field supports multiple entry points: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Consumers then import from 'your-lib' or 'your-lib/utils' and get the correct format.

What is the primary purpose of the exports field in a library's package.json?

ESM uses import/export and enables tree-shaking. CJS uses require() for Node.js compatibility. Ship both via the package.json exports field with import/require conditions. Legacy fallbacks: main (CJS) and module (ESM). Use .mjs/.cjs extensions or type: module for explicit format marking. Test both formats with node CLI after building. Beware the dual package hazard with singleton state.