{DT}DevToolkit

ESM/CJS Compatibility Analyzer

Paste your package.json to analyze ES Modules and CommonJS compatibility. Detect exports issues, dual package hazards, and get actionable recommendations.

Paste Your package.json

Try an example:

Understanding ESM vs CommonJS

Node.js supports two module systems: ES Modules (ESM) using import/exportand CommonJS (CJS) using require/module.exports. Getting compatibility right is crucial for package authors.

The "type" Field

Set "type": "module" in package.json for ESM or "type": "commonjs"for CJS. Without it, Node.js defaults to CommonJS. Files can override with .mjs(ESM) or .cjs (CJS) extensions.

The "exports" Field

Modern packages should use the exports field to define entry points. It supports conditions like import, require, and typesfor different consumers.

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.mjs",
    "require": "./dist/index.cjs"
  }
}

Dual Package Hazard

When a package provides both ESM and CJS, code may load twice if both versions are imported. This breaks singletons, instanceof checks, and shared state. Use wrapper patterns or state isolation to prevent this.

Common Issues

  • ERR_REQUIRE_ESM: Trying to require() an ESM-only package. Use dynamic import or upgrade your code to ESM.
  • types not found: TypeScript requires types condition to be first in exports.
  • Module resolution: ESM requires file extensions. CJS doesn't.

Resources