Quelle est la différence entre CommonJS et ES Modules dans Node ?

Question

Accepted Answer

Node supporte **deux systèmes de modules** : **CommonJS (CJS)** — l'original, utilisant `require`/`module.exports` — et **ES Modules (ESM)** — le standard, utilisant `import`/`export`. Ils diffèrent par la syntaxe, le comportement de chargement et l'interopérabilité.

## CommonJS — l'original de Node

```js
// math.js
function add(a, b) { return a + b; }
module.exports = { add };

// app.js
const { add } = require("./math"); // synchronous, runtime
```

## ES Modules — le standard

```js
// math.mjs (or .js with "type": "module")
export function add(a, b) { return a + b; }
export default something;

// app.mjs
import { add } from "./math.mjs"; // static, hoisted
```

## Différences clés

```text
                 CommonJS              ES Modules
Syntax           require/module.exports import/export
Loading          synchronous, runtime  static, hoisted
Top-level await  no                    yes
Tree-shaking     hard                  yes (statically analyzable)
File extension   .cjs / .js (default)  .mjs / .js with "type":"module"
__dirname/__filename available         not available (use import.meta.url)
```

## Activer ESM

```json
// package.json
{ "type": "module" }  // now .js files are treated as ESM
```

Ou utilisez l'extension `.mjs` explicitement. Sans cela, Node utilise par défaut `.js` en CommonJS.

## Pièges de l'interopérabilité

```js
// ESM can import CommonJS:
import pkg from "some-cjs-lib"; // works (default import)

// CommonJS CANNOT require() a pure-ESM package (it's async):
const esm = require("esm-only-pkg"); // ❌ ERR_REQUIRE_ESM
// must use dynamic import: const esm = await import("esm-only-pkg");
```

Le point faible : CJS ne peut pas `require()` des packages ESM-only — une douleur courante lors des migrations. Notez aussi que ESM manque `__dirname` (utilisez `import.meta.url`).

## Pourquoi c'est important

Connaître les deux systèmes est essentiel pour le travail réel avec Node : ESM est l'avenir (standard, tree-shakeable, top-level await, aligné avec le navigateur) et le bon choix pour les nouveaux projets, mais une grande partie de l'écosystème npm et du code existant est CommonJS.

Comprendre les différences de syntaxe, comment activer ESM (`"type": "module"`), et les limitations d'interopérabilité (notamment CJS-ne-peut-pas-require-ESM) prévient la confusion et les erreurs fréquentes qui surviennent en les mélangeant.