Future-Proofing JavaScript with ESM and CJS Compatibility Techniques

JavaScript’s module system is like Git: powerful, confusing, and somehow still a daily source of pain.

If you’ve tried publishing an NPM package lately, you’ve probably wrestled with ECMAScript Modules (ESM) and CommonJS (CJS). Maybe you’ve added "type": "module" to your package.json and watched half your consumers scream. Maybe you didn’t, and now tree-shaking doesn’t work. Either way, it’s a mess.

Let’s clean it up.

This guide walks through how to build dual-compatible JavaScript packages — ones that work whether they’re require()’d or import’ed, without breaking your CI pipeline or sacrificing modern best practices.

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:

Format	ESM	CJS
Syntax	`import/export`	`require/module.exports`
Node.js	Default in `.mjs` or `"type": "module"`	Default in `.js` or `"type": "commonjs"`
Pros	Native in browsers, tree-shaking, async imports	Ubiquitous, works everywhere
Cons	Can’t `require()` it	Can’t `import` it (without wrappers)

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
}

Why this works#

main: Used by CJS consumers and legacy bundlers
module: Used by modern bundlers like Vite, Webpack (for ESM)
exports: Official Node.js way to define conditional entry points

✅ This setup lets both require() and import work cleanly without surprises.

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:

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

Validate both formats in your CI pipeline:

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

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.

Patreon Exclusives#

🏆 Join my Patreon and dive deep into the world of Docker and DevOps with exclusive content tailored for IT enthusiasts and professionals. As your experienced guide, I offer a range of membership tiers designed to suit everyone from newbies to IT experts.

Tools I Personally Trust#

If you’re building, breaking, and trying to keep your digital life sane (like every good DevOps engineer), these are tools I actually use every day:

🛸 Proton VPN (60% off link) - my shield on the internet. Keeps my Wi-Fi secure, hides my IP, and blocks trackers. Even on sketchy café Wi-Fi, I’m safe.

🔑 Proton Pass (50% off link) - my password vault. End-to-end encrypted logins, 2FA, and notes - all mine and only mine.

🦑 GitKraken Pro (50% off link) - my visual Git sidekick. Beautiful commit graph, easy merges, and fewer “WTF just happened?” moments.

💜 These links give you discounts - and help support the channel at no extra cost.

Gear & Books I Trust#

📕 Essential DevOps books
🖥️ Studio streaming & recording kit
📡 Streaming starter kit

🎬 YouTube
🐦 X (Twitter)
🎨 Instagram
🐘 Mastodon
🧵 Threads
🎸 Facebook
🦋 Bluesky
🎥 TikTok
💻 LinkedIn
📣 daily.dev Squad
✈️ Telegram
🐈 GitHub

Community of IT Experts#

👾 Discord

Refill My Coffee Supplies#

💖 PayPal
🏆 Patreon
🥤 BuyMeaCoffee
🍪 Ko-fi
💎 GitHub
⚡ Telegram Boost

🌟 Bitcoin (BTC): bc1q2fq0k2lvdythdrj4ep20metjwnjuf7wccpckxc
🔹 Ethereum (ETH): 0x76C936F9366Fad39769CA5285b0Af1d975adacB8
🪙 Binance Coin (BNB): bnb1xnn6gg63lr2dgufngfr0lkq39kz8qltjt2v2g6
💠 Litecoin (LTC): LMGrhx8Jsx73h1pWY9FE8GB46nBytjvz8g

Is this content AI-generated?

No. Every article on this blog is written by me personally, drawing on decades of hands-on IT experience and a genuine passion for technology.

I use AI tools exclusively to help polish grammar and ensure my technical guidance is as clear as possible. However, the core ideas, strategic insights, and step-by-step solutions are entirely my own, born from real-world work.

Because of this human-and-AI partnership, some detection tools might flag this content. You can be confident, though, that the expertise is authentic. My goal is to share road-tested knowledge you can trust.