Future-Proofing JavaScript with ESM and CJS Compatibility Techniques

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

You probably think this is a frontend problem. It isn’t. CLI tools, Dockerized apps, Lambda functions, microservices in Node.js: for all of them, module format matters.

Build tooling wants ESM. Legacy code wants CJS. Your job is to feed both without the whole thing folding in on itself like a badly wired monorepo.

The ESM vs. CJS TL;DR#

I’ll skip the history lesson. Here’s what actually matters in practice:

So no, slapping .mjs on everything and praying is not a strategy. Do it properly.

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

Set "type": "module" in a library’s package.json, and you’ve just locked that library into ESM-only territory.

Now every CJS consumer is stuck doing bundler gymnastics to use it. Bad trade.

Do this instead. Define dual entry points and let the consuming app pick what it wants.

Example: Dual-Compatible package.json#

This is the config I actually ship in real packages. Clean, and it works:

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#

Reach for a bundler like rollup or tsup and compile both module types from one source. Here’s a 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. One build, both formats, no drama.

Docker and DevOps Considerations#

Shipping Node apps in Docker? You should be. And when you do, test both module formats inside the container. I’ve watched far too many CI pipelines pass locally and then fall over the moment node inside Alpine choked on the wrong module format.

Here’s what I do:

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. In Docker, the small inconsistencies are the ones that kill you.

Real-World Example: CLI Tool Distribution#

We built a small CLI tool that ended up spreading across several dev teams. Some pulled it in with require(). Others imported it as an ESM module in their Vite setups.

We could have picked one and annoyed half of them. We went dual-mode instead. Here’s what worked:

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

The result? One package, two module styles, nobody complaining.

Takeaway#

Supporting both ESM and CJS is about more than compatibility. It’s about longevity. The Node.js ecosystem is not flipping to ESM-only overnight, and you want your package to work today, and still work five years from now.

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