Future-Proofing JavaScript with ESM and CJS Compatibility Techniques

Why You Should Care (Even as a DevOps Engineer)#

You might think this is a frontend problem. It’s not. If you’re building CLI tools, Dockerized apps, Lambda functions, or microservices in Node.js — module format matters.

Build tooling expects ESM. Legacy code expects CJS. And your job is to make sure they both get what they want without the whole thing collapsing like a badly written monorepo.

The ESM vs. CJS TL;DR#

Let’s not do a full history lesson. Here’s what you actually need to know:

And no, you can’t just slap .mjs on everything and hope it works. Let’s do it right.

Rule #1: Don’t Use "type": "module" in Shared Packages#

If your library sets "type": "module" in package.json, you’re locking it into ESM-only land.

That means anyone using CJS can’t touch it without some bundler gymnastics. Not cool.

Instead, define dual entry points — let the consuming app decide what it wants.

Example: Dual-Compatible package.json#

Here’s the clean, working config I use in real-world packages:

1
{
2
  "name": "example-library",
3
  "version": "1.0.0",
4
  "description": "Dual ESM and CJS compatible library",
5
  "main": "dist/index.cjs",
6
  "module": "dist/index.mjs",
7
  "exports": {
8
    ".": {
9
      "require": "./dist/index.cjs",
10
      "import": "./dist/index.mjs"
11
    }
12
  },
13
  "keywords": ["esm", "cjs", "npm", "compatibility"],
14
  "license": "MIT"
15
}

Common Mistakes#

• Mixing CJS and ESM in the same file: Just don’t. Keep them separate.
• Forgetting .cjs and .mjs extensions: Node cares. A lot.
• Assuming bundlers will “just handle it”: Spoiler — they won’t.

Build Setup for Both Formats#

Use a bundler like rollup or tsup to compile both module types. Example config:

1
tsup src/index.ts \
2
  --format cjs,esm \
3
  --dts \
4
  --out-dir dist

That gives you dist/index.cjs, dist/index.mjs, and dist/index.d.ts. Bundle once, support both — no drama.

Docker and DevOps Considerations#

If you’re shipping Node apps in Docker — and you should be — test both module formats inside containers. I’ve seen countless CI pipelines break because they worked locally but failed when node inside Alpine couldn’t parse the wrong module format.

Here’s what I recommend:

1. Use node:18-alpine as your base image (or 20, if you’re brave).

2. Validate both formats in your CI pipeline:

   1
   node -e "require('./dist/index.cjs')"
   2
   node --input-type=module -e "import('./dist/index.mjs')"
   

3. Lock your build environment with package-lock.json and exact versions.

Consistency is king. And in Docker, inconsistency kills.

Real-World Example: CLI Tool Distribution#

We built a small CLI tool used across multiple dev teams. Some integrated it via require(), others imported it as an ESM module in their Vite-powered setups.

Instead of picking one and making half the users mad, we went dual-mode. Here’s what worked:

• Split output with tsup
• Defined conditional exports
• Wrote one internal API, wrapped with two interfaces (CJS and ESM)

Result? One package, two module styles, zero complaints.

Takeaway#

Supporting both ESM and CJS isn’t just about compatibility — it’s about longevity. The Node.js ecosystem isn’t switching overnight. You want your package to work today, and still work five years from now.

So build smart. Support both. And don’t make your users fight the module loader.