التجميع باستخدام Rollup وtsup للمكتبات

الإعداد الافتراضي لـ Vite مُحسّن للتطبيقات؛ فهو يجمع كل شيء، ويتعامل مع الأصول، وينشئ index.html. أما مكتبة المكوّنات فتحتاج إلى مخرجات مختلفة: ملفات JavaScript بصيغة ESM/CJS خالصة، دون تكلفة إضافية وقت التشغيل، ودون تضمين React، مع تعريفات TypeScript مناسبة. يعمل وضع المكتبات في Vite، لكن Rollup وtsup مصممان لهذا الغرض بدرجة أكبر.

ظل Rollup أداة التجميع القياسية لمكتبات JavaScript لسنوات. فهو ينتج مخرجات نظيفة وفعالة مع إمكانات ممتازة لحذف الشيفرة غير المستخدمة، ويدعم صيغتي مخرجات ESM وCJS. ويزيل رفع النطاق في Rollup تكلفة أغلفة الوحدات، منتجًا حزم مكتبة بأصغر حجم ممكن.

tsup أداة تجميع TypeScript عديمة الإعدادات، ومدعومة بواسطة esbuild. وهي أسرع بكثير من Rollup؛ إذ يترجم esbuild خلال ميكروثوانٍ بدلًا من ميلي ثانية. وينتج الإعداد الأدنى: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } صيغتي الوحدات وتعريفات TypeScript تلقائيًا.

خيارات tsup الأساسية هي: entry، وهي مصفوفة ملفات نقاط الدخول. وformat، التي تحدد صيغ المخرجات: ['esm', 'cjs']. وdts: true، التي تنشئ ملفات تعريف TypeScript بصيغة .d.ts إلى جانب مخرجات JS. وtarget، التي تحدد الحد الأدنى لبيئة JavaScript، مثل esnext أو es2020. وsplitting: false، التي تُبقي المخرجات في ملفات مفردة.

يُجمّع esbuild (عبر tsup) أسرع من Rollup بمقدار يتراوح بين 10 و100 مرة. ينتج Rollup مخرجات محسّنة بدرجة أكبر قليلًا، مع دقة أفضل في tree-shaking وتحكم أكبر في حدود الأجزاء. بالنسبة إلى معظم مكتبات المكوّنات، تتفوق سرعة tsup أثناء التطوير. أما عند الحاجة إلى أقصى تحكم في tree-shaking أو عند إعدادات الإدخال المتعددة المعقدة، فيُفضّل استخدام Rollup.

أهم إعداد لأداة التجميع في مكتبة React هو: لا تُضمّن React أو ReactDOM في الحزمة مطلقًا. حددهما كاعتماديتين خارجيتين لاستبعادهما من مخرجاتك. إذا ضمّنت مكتبتك React، فسينتهي الأمر بالمستخدمين إلى نسختين من React — واحدة من حزمتك وأخرى من تطبيقهم. وهذا يعطّل جميع React Hooks بسبب وجود مثيلات متعددة من React.

في إعدادات tsup، استخدم الخيار external: external: ['react', 'react-dom']. وفي إعدادات Rollup، عيّن external: ['react', 'react-dom', 'react/jsx-runtime']. أدرج react/jsx-runtime إذا كانت مكتبتك تستخدم JSX Transform. واجعل أي اعتماديات نظيرة أخرى تعلنها مكتبتك خارجية أيضًا.

يتطلب إعداد Rollup الأدنى لمكتبة TypeScript ثلاث إضافات: @rollup/plugin-typescript لترجمة TypeScript، و@rollup/plugin-node-resolve لحل الاستيرادات من node_modules، و@rollup/plugin-commonjs لتحويل الاعتماديات بصيغة CommonJS إلى ESM ضمن الحزمة. أضف rollup-plugin-dts لملفات التصريحات.

إخراج نموذجي لمكتبة بصيغتين: dist/esm/index.js وdist/esm/index.d.ts لمستخدمي ESM، وdist/cjs/index.js وdist/cjs/index.cjs لمستخدمي CJS. يربط حقل exports في package.json هذه المسارات بالبيئات الصحيحة. وتوضع ملفات تصريحات TypeScript بجوار ملفات JavaScript المناظرة لها.

تستفيد المكتبات الكبيرة من نقاط دخول متعددة، بحيث يستورد المستخدمون ما يحتاجون إليه فقط. مثال: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. يحصل كل إدخال على ملفات إخراج خاصة به. ويربط حقل exports في package.json كل مسار عام بمخرجاته: './utils' → './dist/utils.js'.

أضف أمر البناء إلى scripts في package.json: "build": "tsup". يقرأ tsup إعداداته من tsup.config.ts في المجلد الجذر. وينبغي أن يشغّل سكربت prepublish عملية البناء: إذ يضمن "prepublishOnly": "npm run build" بناء حزمتك دائمًا قبل نشرها إلى npm.

لماذا يجب تحديد React كاعتمادية خارجية عند تجميع مكتبة مكوّنات React؟

يوفر tsup (المدعوم من esbuild) تجميعًا سريعًا دون إعدادات تقريبًا، باستخدام format: ['esm', 'cjs'] وdts: true. ويوفر Rollup تحكمًا أدق في tree-shaking باستخدام @rollup/plugin-typescript. القاعدة الأساسية: حدّد دائمًا react وreact-dom وجميع الاعتماديات النظيرة كاعتماديات خارجية لمنع تضمينها في الحزمة. أخرج الملفات إلى dist/esm/ وdist/cjs/ مع تصريحات TypeScript موازية. وتتيح نقاط الدخول المتعددة للمستخدمين tree-shaking أكثر دقة.