How do ES Modules differ from CommonJS in Node.js, and what are the migration challenges?

Question

At a Node.js-heavy company:

> "We're migrating our codebase from CommonJS to ES Modules. Some packages only ship CJS, some only ESM. Our Jest tests broke after switching. What are the key differences and how do we handle interoperability?"

Interview OS Community · Accepted Answer

## Key Differences

| Feature | CommonJS (CJS) | ES Modules (ESM) |
|---------|----------------|-------------------|
| **Syntax** | `require()` / `module.exports` | `import` / `export` |
| **Loading** | Synchronous | Asynchronous |
| **Tree-shaking** | ❌ Not possible | ✅ Static analysis |
| **Top-level await** | ❌ No | ✅ Yes |
| **Execution** | Runs at require time | Parsed, then executed |
| **Mutability** | Exports are copies | Exports are live bindings |
| **`this` at top** | `module.exports` | `undefined` |

## Interoperability

```typescript
// CJS importing ESM (dynamic import only)
const { default: esmModule } = await import("./esm-module.mjs");

// ESM importing CJS (named imports may not work)
import cjsModule from "./cjs-module.cjs"; // ✅ default import works
import { specific } from "./cjs-module.cjs"; // ⚠️ May fail
```

## Migration Challenges

1. **`__dirname` and `__filename`** not available in ESM:
```typescript
// ESM replacement
import { fileURLToPath } from "url";
import { dirname } from "path";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
```

2. **JSON imports** require assertion:
```typescript
import pkg from "./package.json" with { type: "json" };
```

3. **Jest ESM support**: Use `--experimental-vm-modules` or switch to Vitest
4. **Package.json**: `"type": "module"` makes all `.js` files ESM by default

## Best Practice for New Projects
```json
// package.json
{ "type": "module" }
```
Use `.mts`/.mts` extensions for explicit ESM, `.cts` for CJS.

Interview OS

How do ES Modules differ from CommonJS in Node.js, and what are the migration challenges?

Question Details

Suggested Solution

Key Differences

Interoperability

Migration Challenges

Best Practice for New Projects

Discussion (0)