ESM and CJS Compatibility

🔀 What is ESM and CJS Compatibility?

JavaScript has evolved with two major module systems: CommonJS (CJS) and ECMAScript Modules (ESM). While CommonJS has been the backbone of Node.js for years, ESM is the modern, standardized module format in JavaScript. ESM and CJS Compatibility is all about making sure these two formats can work together seamlessly — especially in fast runtimes like Bun.

📦 Understanding the Two Module Systems

Before we dive into Bun’s compatibility layer, let’s quickly differentiate ESM and CJS:

• CommonJS (CJS): Uses require() and module.exports
• ESM (ECMAScript Modules): Uses import and export statements

// CommonJS
const fs = require('fs');
module.exports = { readFile };

// ESM
import fs from 'fs';
export const readFile = () => {};

Both systems work well on their own, but mixing them introduces quirks — and that’s where Bun steps in.

⚙️ How Bun Handles Compatibility

Bun is built to support both module formats out-of-the-box. Whether you're importing a CJS module in ESM or vice versa, Bun knows how to resolve and execute the code correctly.

• ✅ Automatically detects module type based on package.json and file extension
• ✅ Allows importing CommonJS inside ESM using import
• ✅ Allows requiring ESM inside CommonJS (with some limitations)

// ESM importing CJS
import express from 'express';

// CJS requiring ESM (limited)
const chalk = require('chalk'); // Works if chalk exposes a CJS build

🧠 The Role of package.json

Bun relies on the type field in package.json to determine how to treat a module:

• "type": "module" → Treats .js as ESM
• "type": "commonjs" or no type → Treats .js as CJS

To make sure your project is compatible:

// For ESM
{
  "type": "module"
}

🔄 Mixing ESM and CJS in the Same Project

Yes, you can mix both formats! This is particularly useful when using third-party libraries:

• Write your app in ESM
• Import CJS packages from npm

// ESM File
import bodyParser from 'body-parser';
import { myFunc } from './utils.cjs';

Bun handles the interop under the hood, converting CJS exports into ESM-compatible bindings.

📁 File Extensions That Matter

The extension you use impacts module resolution:

• .mjs → Always treated as ESM
• .cjs → Always treated as CJS
• .js → Behavior depends on package.json

// Example
import helper from './helper.cjs'; // Triggers CJS resolution

📌 Limitations to Watch Out For

While Bun makes module interop easy, there are a few caveats:

• Top-level await is only allowed in ESM
• Named exports from CJS can be tricky
• ESM dynamic imports must use import(), not require()

// Not allowed
const lib = require('./lib.mjs'); // ❌ Won't work in CJS

// Correct
const lib = await import('./lib.mjs'); // ✅ Works in ESM

🚀 Bun’s Superpower: Speed + Flexibility

What sets Bun apart is that it doesn’t just support both formats — it does so with incredible speed. Its internal module resolution engine (written in Zig) handles both ESM and CJS faster than traditional Node.js setups.

Whether you’re using legacy CJS code or writing future-proof ESM modules, Bun ensures they can co-exist without friction.

✅ Final Thoughts: Embrace Dual Compatibility

Bun makes bridging the gap between ESM and CJS easier than ever. You don’t need to refactor your entire codebase or abandon existing packages. Instead, you can mix, match, and migrate gradually.

By understanding how Bun handles ESM and CJS compatibility, you gain the freedom to build modern apps without worrying about module conflicts or breaking builds. It’s flexibility and speed, all in one.

So go ahead — import, require, and write with confidence. Bun has your back.