Frontend Academy · درس

إدارة الإصدارات والنشر إلى npm

استخدم الإصدار الدلالي، وأتمت إنشاء سجل التغييرات باستخدام Changesets أو standard-version، وانشر المكتبة إلى npm أو سجل خاص

إدارة الإصدارات والنشر إلى npm درس مجاني في Frontend Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Frontend Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Frontend Academy 4 دروس في المجموع.

لماذا ننشر على npm؟

إذا كان أكثر من تطبيق يستخدم نظام التصميم، فانشره كحزمة. يثبّتها المستهلكون باستخدام npm أو yarn أو pnpm، ويثبّتون إصدارات محددة، ويحدّثونها وفق جدولهم الخاص.

الإصدار الدلالي (SemVer)

تتبع الإصدارات الصيغة MAJOR.MINOR.PATCH. يشير MAJOR إلى التغييرات الكاسرة للتوافق، وMINOR إلى الميزات الجديدة المتوافقة مع الإصدارات السابقة، وPATCH إلى إصلاحات الأخطاء فقط.

متى نرفع رقم الإصدار

أعدت تسمية خاصية؟ ارفع MAJOR. أضفت خاصية اختيارية جديدة؟ ارفع MINOR. أصلحت خطأ في CSS؟ ارفع PATCH. يمكن لإصدارات ما قبل 1.0 (0.x.y) أن تتضمن تغييرات كاسرة للتوافق في MINOR — لكن تحلَّ بالإنصاف.

package.json — البيان

اضبط شكل حزمتك على npm.

{
  "name": "@yourorg/design-system",
  "version": "1.4.2",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": { "import": "./dist/index.esm.js", "require": "./dist/index.cjs.js" },
    "./theme": "./dist/theme.js"
  },
  "files": ["dist", "README.md"],
  "peerDependencies": { "react": "^18.0.0" }
}

مخرجات البناء

أصدر CommonJS وESM وتعريفات الأنواع. تتولى أدوات مثل tsup أو vite build --lib معالجة ذلك.

// tsup.config.ts
export default {
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  clean: true,
  external: ['react', 'react-dom']
};

// package.json: "build": "tsup"

peerDependencies

أدرج React/Vue وما شابهها ضمن peerDependencies كي يستخدم المستهلكون إصداراتهم الخاصة. ويؤدي تحديدها كتبعيات عادية إلى تضمينها مرتين، مما يتسبب في تعطل hooks والسياق.

ملائم لـ Tree-shaking

استخدم صادرات ESM وتجنّب الآثار الجانبية حتى تتمكن أدوات التجميع من حذف المكوّنات غير المستخدمة. حدّد ذلك في package.json: "sideEffects": false (أو أدرج ملفات محددة مثل CSS).

النشر على npm

سجّل الدخول مرة واحدة، ثم انشر.

npm login

# Bump version + publish:
npm version patch   # 1.4.2 -> 1.4.3
npm publish

# Or scoped public package:
npm publish --access public

أتمتة الإصدارات باستخدام Changesets

Changesets هي مجموعة الأدوات الحديثة لنشر monorepo والمكتبات. تتضمن طلبات الدمج ملف «changeset» يصف التغيير؛ ثم ترفع CI الخاصة بالإصدار أرقام الإصدارات وتنشرها.

npm install -D @changesets/cli
npx changeset init

# In each PR:
npx changeset
# pick package, type (major/minor/patch), describe change
# commits .changeset/<random>.md

# CI on main:
npx changeset version  # bumps versions in package.json + generates changelog
npx changeset publish  # publishes to npm

سجل تغييرات مؤتمت

تنشئ Changesets ملف CHANGELOG.md لكل حزمة تلقائياً من أوصاف changeset، ليتمكن المستهلكون من معرفة ما تغيّر في كل إصدار.

وسوم توزيعات npm

استخدم dist-tags للإصدارات التجريبية: ينشر npm publish --tag beta الإصدار دون استبدال latest. ويمكن للمستهلكين الاشتراك فيه باستخدام npm install @yourorg/design-system@beta.

السجلات الخاصة

يمكن للحزم الداخلية استخدام GitHub Packages أو GitLab Package Registry أو Verdaccio المستضاف ذاتياً. اضبط ذلك باستخدام .npmrc: @yourorg:registry=https://npm.pkg.github.com.

إهمال الإصدارات القديمة

حدّد إصداراً على أنه مهمل لتحذير أدوات التثبيت.

npm deprecate @yourorg/design-system@1.0.0 'Use 2.x for React 18 support'

اختبار سريع

إذا أعدت تسمية خاصية في مكوّن مُصدّر، فما نوع الزيادة المطلوبة في رقم إصدار SemVer؟

مراجعة: تحديد الإصدارات والنشر

SemVer: ‏MAJOR.MINOR.PATCH — تغيير كاسر للتوافق، وميزة، وإصلاح. أنشئ CJS وESM والأنواع (باستخدام tsup وvite --lib). أدرج React/Vue ضمن peerDependencies. استخدم sideEffects:false لإتاحة tree-shaking. انشر باستخدام npm publish أو أتمت العملية باستخدام Changesets. أنشئ CHANGELOG تلقائياً. استخدم dist-tags للإصدارات التجريبية، والسجلات الخاصة للحزم الداخلية.

الأسئلة الشائعة

هل درس «إدارة الإصدارات والنشر إلى npm» مجاني؟

نعم — نص درس «إدارة الإصدارات والنشر إلى npm» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Frontend Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Frontend Academy 4 دروس في المجموع.

ماذا ستتعلم في «إدارة الإصدارات والنشر إلى npm»؟

استخدم الإصدار الدلالي، وأتمت إنشاء سجل التغييرات باستخدام Changesets أو standard-version، وانشر المكتبة إلى npm أو سجل خاص تتمرن على Frontend Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Frontend Academy؟

لا تُشترط خبرة سابقة. Frontend Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «إدارة الإصدارات والنشر إلى npm»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Frontend Academy هذا؟

نعم. كل درس في Frontend Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Frontend Academy