ESM و CommonJS و package exports: Node بيلاقي الـ modules إزاي

أهلًا بيك. أي backend حقيقي فيه مئات الملفات، وكل ملف بياخد حاجات من ملفات تانية. الملف ده اسمه module. والمشكلة إن Node فيه نزامين للـ modules، عايشين مع بعض: CommonJS، القديم، بـ require و module dot exports. و ESM، الرسمي في JavaScript، بـ import و export. وأي مكتبة هتستخدمها هتكون واحد منهم أو الاتنين، فلازم تفهمهم كويس. نبدأ بـ CommonJS. math dot cjs بيصدّر add و PI بـ module dot exports. وفي main dot cjs: require بتجيبهم، و destructuring. وكمان require لـ node colon path، والـ node colon دي معناها: module من جُوّه Node نفسه. و underscore underscore filename و dirname: متغيرات موجودة لوحدها في CommonJS. نشغّل.

const { add, PI } = require("./math.cjs");
const path = require("node:path");

console.log(add(2, 3), PI);
console.log(__filename.endsWith("main.cjs"), path.basename(__dirname));

$ node main.cjs
5 3.14
true my-backend

خمسة وتلاتة وأربعتاشر، و true، واسم الـ folder. require في CommonJS synchronous: بتقرا الملف وتشغّله وترجّع النتيجة فورًا، وده سبب إنها ممكن تتكتب في أي مكان، حتى جُوّه if. دلوقتي ESM. بنزوّد في package dot json سطر type module، ومعناه: أي ملف dot js في المشروع ده ESM. math dot js بيعمل export لكل حاجة قدامها. والـ export default: الحاجة الأساسية في الملف، وبتتجاب من غير curly braces. وفي main dot js: import، والـ path لازم فيه الامتداد dot js. و import dot meta dot dirname بدل underscore underscore dirname. وفي الآخر await برة أي function، ودي اسمها top-level await، ومسموحة في ESM بس. نشغّل main dot js.

import hello, { add, PI } from "./math.js";
import path from "node:path";

console.log(add(2, 3), PI, hello("مُنى"));
console.log(path.basename(import.meta.dirname), import.meta.filename.endsWith("main.js"));

// top-level await: مسموح في ESM بس
const wait = await Promise.resolve("await برة أي function");
console.log(wait);

$ node main.js
5 3.14 أهلًا مُنى
my-backend true
await برة أي function

كله اشتغل: الحساب، والـ default، واسم الـ folder، والـ top-level await. ESM هو المستقبل، وكل الكورس من هنا ورايح هيكون ESM. بس خلينا نشوف الأخطاء اللي هتقابلك وإنتَ بتنقل. أول خطأ: require جُوّه ملف ESM. نشغّل.

const { add } = require("./math.js");
console.log(add(1, 1));

$ node main.js

file:///home/you/my-backend/main.js:1
const { add } = require("./math.js");
                ^

ReferenceError: require is not defined in ES module scope, you can use import instead
This file is being treated as an ES module because it has a '.js' file extension and '/home/you/my-backend/package.json' contains "type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.
    at file:///home/you/my-backend/main.js:1:17
    at ModuleJob.run (node:internal/modules/esm/module_job:430:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:661:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

Node.js v24.14.1

ReferenceError: require is not defined in ES module scope. وبص على الرسالة، Node بنفسه بيقولك الحل: الملف ده ESM بسبب type module، فاستخدم import، أو غيّر الامتداد لـ dot cjs. تاني خطأ: import من غير امتداد. نشغّل.

import { add } from "./math";
console.log(add(1, 1));

$ node main.js

node:internal/modules/run_main:107
    triggerUncaughtException(
    ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/you/my-backend/math' imported from /home/you/my-backend/main.js
Did you mean to import "./math.js"?
    at finalizeResolution (node:internal/modules/esm/resolve:275:11)
    at moduleResolve (node:internal/modules/esm/resolve:865:10)
    at defaultResolve (node:internal/modules/esm/resolve:991:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:719:20)
    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:736:38)
    at ModuleLoader.resolveSync (node:internal/modules/esm/loader:765:52)
    at #resolve (node:internal/modules/esm/loader:701:17)
    at ModuleLoader.getOrCreateModuleJob (node:internal/modules/esm/loader:621:35)
    at ModuleJob.syncLink (node:internal/modules/esm/module_job:160:33)
    at ModuleJob.link (node:internal/modules/esm/module_job:245:17) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/you/my-backend/math'
}

Node.js v24.14.1

ERR MODULE NOT FOUND، ومعاه: Did you mean to import math dot js؟ في CommonJS، require كانت بتجرّب الامتدادات لوحدها. ESM لا: لازم تكتب اسم الملف كامل. الفروق كلها في الـ slide دي، صوّرها. الجزء الأهم في الدرس: الـ exports في package dot json. لما تكتب import من اسم package، Node بيدوّر عليها في node_modules، ويقرا package dot json بتاعها. package اسمها at acme slash money، والـ exports بتاعها بيقول: الـ dot، يعني الاسم لوحده: لو حد عمل import، ياخد index dot mjs، ولو require، ياخد index dot cjs. ودي اسمها conditional exports. وفيه subpath تاني: slash format. و package dot json نفسه مسموح. وأي ملف تاني، زي internal، مقفول. main dot js بيعمل import للـ package ولـ format. وبيعمل require لنفس الـ package، بـ createRequire، ودي الطريقة اللي تجيب بيها CommonJS من جُوّه ESM. نشغّل.

export const secret = "ده مش للاستخدام من برة";

$ node main.js
19.99 ج.م
{ calls: 1, kind: 'esm' } { calls: 1, kind: 'cjs' }

تسعتاشر وتسعة وتسعين بقت بالقروش وطبعناها بالجنيه. بس بص على السطر التاني: calls في نسخة الـ ESM واحد، وفي نسخة الـ CJS واحد! يعني الـ package اتحمّلت مرتين، وكل نسخة ليها state لوحدها. ده اسمه dual package hazard، ولو الـ package فيها cache أو connection pool أو singleton، هيبقى عندك اتنين من غير ما تحس. الحل: النسخة الـ CJS تبقى wrapper بسيط بيستخدم نفس الـ state، أو الـ package تبقى ESM بس. دلوقتي نحاول نوصل لملف مقفول: internal dot mjs. نشغّل.

import { secret } from "@acme/money/internal.mjs";
console.log(secret);

$ node main.js

node:internal/modules/esm/resolve:314
  return new ERR_PACKAGE_PATH_NOT_EXPORTED(
         ^

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './internal.mjs' is not defined by "exports" in /home/you/my-backend/node_modules/@acme/money/package.json imported from /home/you/my-backend/main.js
    at exportsNotFound (node:internal/modules/esm/resolve:314:10)
    at packageExportsResolve (node:internal/modules/esm/resolve:662:9)
    at packageResolve (node:internal/modules/esm/resolve:774:12)
    at moduleResolve (node:internal/modules/esm/resolve:859:18)
    at defaultResolve (node:internal/modules/esm/resolve:991:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:719:20)
    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:736:38)
    at ModuleLoader.resolveSync (node:internal/modules/esm/loader:765:52)
    at #resolve (node:internal/modules/esm/loader:701:17)
    at ModuleLoader.getOrCreateModuleJob (node:internal/modules/esm/loader:621:35) {
  code: 'ERR_PACKAGE_PATH_NOT_EXPORTED'
}

Node.js v24.14.1

ERR PACKAGE PATH NOT EXPORTED: الـ subpath ده مش متصدّر. وده بالزبط الهدف: صاحب الـ package بيقرر الـ public API بتاعها، والملفات الداخلية يغيّرها براحته من غير ما يكسر حد. وخد بالك: أول ما تحط exports، أي path مش مكتوب فيها بيتقفل، حتى package dot json، علشان كده كتبناه صراحةً.

معلومة جديدة في Node: من الإصدار اتنين وعشرين وطالع، require بقت تقدر تجيب ملف ESM عادي. بشرط واحد: الملف ده ما يكونش فيه top-level await، لأن require synchronous ومش هتعرف تستنى. ولو فيه، هتطلع ERR REQUIRE ASYNC MODULE. التحدي: package ليها باب واحد. هتكمّل package dot json بتاع at acme slash slug بـ exports: import و require. تكتب slugify في النسختين. وتستخدمها من main dot js مرة بـ import، ومرة بـ require. الشروط وحالات الاختبار في الكومنت.

الحل. exports فيها الـ dot بالـ conditions، و package dot json. index dot mjs بـ export. index dot cjs بـ module dot exports. و main dot js: import عادي، و createRequire للنسخة التانية. نشغّل.

import { slugify } from "@acme/slug";
import { createRequire } from "node:module";

console.log(slugify("  Hello Node World "));

const require = createRequire(import.meta.url);
const cjs = require("@acme/slug");
console.log(cjs.slugify("CJS Works"));

$ node main.js
hello-node-world
cjs-works

hello node world بالـ dashes، و cjs works. الدرس الجاي: الـ Promises و async await بالتفصيل، لأن كل سطر بيكلم database أو شبكة هيبقى async.

{
  "name": "my-backend",
  "private": true,
  "type": "module"
}

// ESM: export
export function add(a, b) {
  return a + b;
}
export const PI = 3.14;
export default function hello(name) {
  return `أهلًا ${name}`;
}

{
  "name": "@acme/money",
  "version": "1.0.0",
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.cjs"
    },
    "./format": "./format.mjs",
    "./package.json": "./package.json"
  }
}

let calls = 0;
export function toPiasters(pounds) {
  calls++;
  return Math.round(pounds * 100);
}
export const stats = () => ({ calls, kind: "esm" });

let calls = 0;
exports.toPiasters = (pounds) => {
  calls++;
  return Math.round(pounds * 100);
};
exports.stats = () => ({ calls, kind: "cjs" });