مخرجات الحزم المزدوجة ESM وCJS

إن ESM (وحدات ECMAScript) هو معيار وحدات JavaScript الرسمي الذي يستخدم الصياغتين import وexport. ويمكن تحليل ESM تحليلاً ثابتًا، إذ تستطيع أدوات التجميع تحديد الصادرات المستخدمة بدقة وقت البناء، مما يتيح tree-shaking. وتدعم المتصفحات الحديثة وNode.js لغة ESM دعمًا أصليًا.

يستخدم CJS (CommonJS) الصياغتين require() وmodule.exports. وكان نظام الوحدات الأصلي في Node.js، ولا يزال مطلوبًا للتوافق مع بيئات Node.js الأقدم، وJest (الذي كان يستخدم CJS تاريخيًا)، والشيفرة التي تستخدم require(). ويُقيَّم CJS ديناميكيًا، مما يجعل tree-shaking أصعب.

ينبغي لحزمة npm الحديثة أن تشحن بصيغتي ESM وCJS لزيادة التوافق إلى أقصى حد. يحصل مستخدمو ESM (مثل Vite وNext.js وأدوات التجميع الحديثة) على استيرادات تدعم tree-shaking. ويحصل مستخدمو CJS (مثل سكربتات Node.js الأقدم وJest دون إعدادات) على توافق مع require(). ويحدد حقل exports في package.json لـ Node وأدوات التجميع الصيغة التي ينبغي استخدامها.

يُعد حقل exports في package.json الطريقة الحديثة لتعريف نقاط الدخول الشرطية. مثال: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. تقرأ أدوات التجميع وNode.js 12+ حقل exports لاختيار الصيغة الصحيحة تلقائيًا.

لا تفهم الأدوات الأقدم حقل exports. ولتحقيق التوافق، عيّن أيضًا: main ليشير إلى مخرجات CJS (كخيار احتياطي لـ require في Node القديم)، وmodule ليشير إلى مخرجات ESM (كتلميح لـ webpack وrollup، وهو غير قياسي لكنه مدعوم على نطاق واسع). تفضّل الأدوات الحديثة exports، بينما تعود الأدوات القديمة إلى main وmodule.

يؤدي ضبط "type": "module" في package.json إلى التعامل مع جميع ملفات .js في الحزمة على أنها ESM. وإذا كنت تشحن بصيغتين، فستحتاج بعد ذلك إلى امتدادات صريحة: استخدم .mjs لملفات ESM و.cjs لملفات CJS عند ضبط type على module، أو العكس. يتولى tsup ذلك تلقائيًا.

يحدد استخدام امتدادي الملفين .mjs (ESM) و.cjs (CJS) الصيغة صراحةً بغض النظر عن حقل type. وهذا يزيل أي التباس. يستطيع tsup إخراج: index.js (ESM) وindex.cjs (CJS) عند ضبط format على ['esm', 'cjs'] وعدم تعيين حقل type، بما يطابق الاصطلاح الأكثر شيوعًا.

عندما توفر حزمة ما صيغتي ESM وCJS، قد تُحمّل أداة تجميع المستخدم كلا الإصدارين في العملية نفسها — مثلًا، إصدار ESM للتطبيق الرئيسي وإصدار CJS لاختبار Jest. وإذا كانت الحزمة تحتوي على حالة على مستوى الوحدة (مثل سياق React)، فستملك كلتا المثيلتين حالة مستقلة. وهذه هي مشكلة الحزمة مزدوجة الصيغة.

للحد من هذه المشكلة: أبقِ الحالة على مستوى الوحدة خارج مكتبتك (من دون أنماط singleton)، واستخدم شروط exports بدقة لضمان تحميل صيغة واحدة فقط، ووثّق ضرورة إعداد المستخدمين لأداة التجميع لديهم لاستخدام ESM في الاختبارات. وتمثل هذه المشكلة مصدر قلق رئيسيًا للمكتبات التي تحتوي على singleton مشتركة.

تحقق من عمل الصيغتين بعد البناء. اختبر CJS باستخدام: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". واختبر ESM باستخدام: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". ينبغي أن تُحل الصيغة الصحيحة في كلتا الحالتين دون أخطاء قبل النشر.

يدعم حقل exports نقاط دخول متعددة: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. ويمكن للمستخدمين عندئذٍ الاستيراد من 'your-lib' أو 'your-lib/utils' والحصول على الصيغة الصحيحة.

ما الغرض الأساسي من حقل exports في package.json الخاص بالمكتبة؟

يستخدم ESM الصيغتين import وexport ويتيح tree-shaking. ويستخدم CJS الصيغة require() للتوافق مع Node.js. اشحن الصيغتين عبر حقل exports في package.json باستخدام شرطي import وrequire. أما البدائل القديمة فهي: main (لـ CJS) وmodule (لـ ESM). استخدم الامتدادين .mjs و.cjs أو type: module لتحديد الصيغة صراحةً. اختبر الصيغتين باستخدام واجهة سطر أوامر node بعد البناء. وانتبه إلى مشكلة الحزمة مزدوجة الصيغة عند استخدام حالة singleton.