Kuna nini tofauti kati ya CommonJS na ES Modules katika Node?

Question

Accepted Answer

Node inasaidiana na **mifumo miwili ya moduli**: **CommonJS (CJS)** — ya awali, inayotumia `require`/`module.exports` — na **ES Modules (ESM)** — kiwango, kinachotumia `import`/`export`. Wanaishi kwa syntax, tabia ya upakaji, na kuunganisha.

## CommonJS — ya awali ya Node

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

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

## ES Modules — kiwango

```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
```

## Tofauti muhimu

```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)
```

## Kuwezesha ESM

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

Au tumia kiengezo cha `.mjs` moja kwa moja. Bila hii, Node kwa kawaida `.js` kwa CommonJS.

## Uchumi wa kuunganisha

```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");
```

Ukingo mbaya: CJS haiwezi `require()` pakiti za ESM-tu — maumivu ya kawaida ya harakati. Kumbuka pia kwamba ESM inakosa `__dirname` (tumia `import.meta.url`).

## Kwa nini hili linastahili

Kujua mifumo yote miwili ni muhimu kwa kazi halisi ya Node: ESM ni siku zijazo (kiwango, tree-shakeable, top-level await, umefaiana na kivinjari) na chaguo sahihi kwa miradi mipya, lakini idadi kubwa ya ikolohiziaji ya npm na msimbo uliopo ni CommonJS.

Kuelewa tofauti za syntax, jinsi ya kuwezesha ESM (`"type": "module"`), na mipango ya kuunganisha (hasa CJS-haiwezi-require-ESM) inazuia mafiki ya kawaida na hitilafu zinazotokea wakati wa kuzichanganya.