module.exports وexports في Node.js مع أمثلة

module.exports هي القيمة التي يعطيها ملف Node.js لأي ملف آخر يحمّله عبر require(). تبدأ ككائن فارغ: أضف إليها خصائص لتصدّر عدة أشياء، أو أسند إليها قيمة جديدة (دالة أو صنفًا) لتصدّر شيئًا واحدًا. أما exports فمتغير مختصر يشير إلى الكائن نفسه، لذلك يعمل exports.add = ...، لكن exports = ... يقطع الصلة ولا يصدّر شيئًا.

const fs = require('fs');

// setup: write a second module next to index.js
fs.writeFileSync('math.js', `
module.exports.add = (a, b) => a + b;
exports.multiply = (a, b) => a * b;
module.exports.PI = 3.14159;
`);

const math = require('./math');

console.log(math.add(2, 3), math.multiply(4, 5), math.PI);
console.log(Object.keys(math));

طبع 5 20 3.14159، ثم [ 'add', 'multiply', 'PI' ]. أضافت الأسطر الثلاثة في math.js خصائص إلى الكائن نفسه، سواء مرّت عبر module.exports أو exports، وأعاد require('./math') ذلك الكائن.

تصدير دالة أو صنف أو كائن

حين يكون للوحدة شيء رئيسي واحد، أسنده إلى module.exports مباشرة. عندها يحصل المستدعي على الدالة نفسها، لا على كائن يحيط بها:

const fs = require('fs');

// setup: two modules, one exports a function, one a class
fs.writeFileSync('greet.js', `
module.exports = function greet(name) {
    return 'Hello, ' + name;
};
`);
fs.writeFileSync('user.js', `
class User {
    constructor(name) { this.name = name; }
    describe() { return this.name + ' (user)'; }
}
module.exports = User;
`);

const greet = require('./greet');
const User = require('./user');

console.log(greet('Ada'));
console.log(new User('Grace').describe());

طبع Hello, Ada وGrace (user). إذا رأيت TypeError: greet is not a function فالمستدعي استخدم الشكل الخطأ: اكتب const { greet } = require(...) لخاصية في كائن، وconst greet = require(...) لقيمة مُسندة.

module.exports مقابل exports: فخ إعادة الإسناد

قبل أن يعمل ملفك، يضبط Node.js exports = module.exports. يشير الاسمان إلى كائن واحد، وrequire يعيد module.exports. إسناد قيمة جديدة إلى exports لا يغيّر إلا المتغير المحلي:

const fs = require('fs');

// setup: the same export written two ways
fs.writeFileSync('broken.js', 'exports = { version: 2 };');
fs.writeFileSync('working.js', 'module.exports = { version: 2 };');

console.log('broken:', require('./broken'));
console.log('working:', require('./working'));

صدّر broken.js القيمة {}، لأن exports صار يشير إلى كائن جديد لا يعيده أحد. وصدّر working.js القيمة { version: 2 }.

أبسط قاعدة: اكتب دائمًا module.exports. يعمل في كل الحالات، والشيفرة تقول ما تفعله.

require تعيد الكائن المخزّن نفسه

ينفّذ Node.js شيفرة الوحدة مرة واحدة، أول مرة تُستدعى فيها، ويخزّن module.exports. كل require لاحق للملف نفسه يعيد ذلك الكائن ذاته، فتكون الحالة داخل الوحدة مشتركة بين كل الملفات التي تحمّلها:

const fs = require('fs');

// setup: a module that counts and logs when it loads
fs.writeFileSync('counter.js', `
console.log('counter.js is running');
let count = 0;
module.exports = { next: () => ++count };
`);

const a = require('./counter');
const b = require('./counter.js');

a.next();
a.next();
console.log('b sees', b.next());
console.log('same object:', a === b);

ظهر counter.js is running مرة واحدة، وأعاد b.next() القيمة 3، وa === b قيمته true، لأن مفتاح الذاكرة المؤقتة هو المسار المحلول للملف، و./counter و./counter.js يُحلّان إلى الملف نفسه. لهذا يكون اتصال قاعدة البيانات أو كائن الإعدادات الذي يُنشأ في وحدة واحدة مشتركًا في التطبيق كله.

module.exports وES modules

تستخدم ES modules الكلمتين export وimport بدلًا من ذلك. وتتقابل الصيغ هكذا:

// CommonJS                              // ES modules
module.exports = greet;                  export default greet;
module.exports.add = add;                export { add };
const greet = require('./greet');        import greet from './greet.js';
const { add } = require('./math');       import { add } from './math.js';

يمكن لـ ES module أن تستورد ملف CommonJS عبر import: تصل module.exports الخاصة به على أنها الاستيراد الافتراضي. ومنذ Node.js 22.12 تستطيع require() أيضًا تحميل ES module لا تحتوي على await في المستوى الأعلى. لمعرفة متى تختار أيهما، راجع CommonJS مقابل ES modules.

أخطاء شائعة

خلط exports.x مع module.exports = ... في ملف واحد. الإسناد يستبدل الكائن، فيضيع كل exports.x كُتب قبله. اختر أسلوبًا واحدًا لكل ملف.

تصدير قيمة تتغير لاحقًا. module.exports = { count } ينسخ الرقم لحظة التحميل؛ وحين تحدّث الوحدة count يبقى المستدعون يرون القيمة القديمة. صدّر دالة تعيدها، كما يفعل counter.js أعلاه.

حذف ./. require('math') يبحث عن حزمة في node_modules، لا عن math.js بجوار ملفك. الملفات المحلية تبدأ دائمًا بـ ./ أو ../.