نشر ملفات التصريحات في TypeScript
مقدمة
بعد أن كتبتَ ملفّ تصريحاتٍ باتباع الخطوات في هذا الدليل، حان الوقت الآن لنشره على منصّة npm. هناك طريقتان رئيسيتان لنشر ملفات تصريحاتك على npm:
- تجميعه (bundling) مع حزمة npm الخاصة بك.
- أو نشره على منظمة @types على npm.
إذا كانت حزمتك مكتوبة بلغة TypeScript، فمن الأفضل اتباع الطريقة الأولى. استعمل الخيار --declaration لتوليد ملفات التصريحات. بهذه الطريقة ستكون تصريحاتك متزامنة دائمًا مع شيفرة JavaScript.
إن لم تكن حزمتك مكتوبة بلغة TypeScript، عندها فالطريقة الثانية أفضل.
تضمين التصريحات في حزمة npm الخاصة بك
إذا كانت حزمتك تحتوي على ملفّ main.js رئيسيّ، فستحتاج إلى الإشارة إلى ملف التصريحات الرئيسي في ملفّ package.json كذلك. اضبط الخاصية types للإشارة إلى ملف التصريحات المُجمَّع الخاص بك. مثلًا:
{
"name": "awesome",
"author": "Vandelay Industries",
"version": "1.0.0",
"main": "./lib/main.js",
"types": "./lib/main.d.ts"
}
لاحظ أن حقل "typings" مرادف للحقل "types" ويؤدي نفس الغرض، لذا يمكن استخدامه كذلك.
لاحظ كذلك أنّه إذا كان ملف تصريحاتك مسمًّى بالاسم index.d.ts وكان في جذر الحزمة (بجانب الملف index.js) فلا حاجة لتحديد الخاصية "types"، لكن من المفضَّل فعل ذلك.
الاعتماديات
تُدير npm جميع الاعتماديات. تأكد من أنّ جميع حزم التصريحات التي تعتمد عليها موجودة بشكل صحيح في قسم "dependencies" في ملفّ package.json الخاص بك. مثلًا، تخيل أننا كتبنا حزمةً تعتمد على Browserify وTypeScript:
{
"name": "browserify-typescript-extension",
"author": "Vandelay Industries",
"version": "1.0.0",
"main": "./lib/main.js",
"types": "./lib/main.d.ts",
"dependencies": {
"browserify": "latest",
"@types/browserify": "latest",
"typescript": "next"
}
}
تعتمد حزمتنا هنا على الحزمتين browserify وtypescript. حزمة browserify لا تُحزِّم ملفات تصريحاتها في حزم npm الخاصة بها، لذا احتجنا إلى الاعتماد على @types/browserify للحصول على تصريحاتها. أمّا typescript فتُحزِّم ملفات تصريحاتها معها، لذا لا حاجة لأي اعتماديّات إضافية.
تعرِض حزمتنا التصريحات من كلا هاتين الحزمتين، لذا إن استخدم أي مستخدم حزمتنا فسيحتاج إلى امتلاك هذه الاعتماديات كذلك. لذا استعملنا الخاصية "dependencies" عوضًا عن "devDependencies"، لأنّنا لو لم نفعل لَاحتاج مستخدم الحزمة إلى تثبيت هذه الاعتماديات يدويا. لو برمجنا مثلًا تطبيق سطر أوامر، ولو لم تكن الحزمة قابلة للاستخدام كمكتبة لاستعملنا في هذه الحالة الخاصية "devDependencies".
أخطاء ينبغي تجنبها
/// <reference path="..." />
لا تستخدم /// <reference path="..." /> في ملفات تصريحاتك:
/// <reference path="../typescript/lib/typescriptServices.d.ts" />
....
استعمل /// <reference types="..." /> كبديل:
/// <reference types="typescript" />
....
تأكد من إلقاء نظرة مجدّدًا على قسم استخدام الاعتماديات للاستزادة.
تحزيم التصريحات التي تعتمد على اعتماديات أخرى
إذا كانت تعريفات أنواعك تعتمد على حزمة أخرى، فاتبع القواعد التالية:
- لا تدمج الحزمة مع حزمتك، أبق على كل واحدة في ملفّ خاص بها.
- لا تنسخ كذلك التصريحات في حزمتك إلى الحزمة التي تعتمد عليها.
- اعتمد على حزمة تصريحات الأنواع الخاصة بها في npm إذا لم تُحزَّم ملفات التصريحات مع الحزمة.
النشر إلى منظمة @types
تُنشَر الحزم الموجودة على منظمة @types تلقائيًّا من مستودع DefinitelyTyped باستخدام الأداة types-publisher. إن أردت أن تُنشَر تصريحاتك كحزمة من حزم @types، فالمرجو إرسال طلب سحب (pull request) إلى مستودع DefinitelyTyped. يمكنك الحصول على المزيد من التفاصيل في صفحة إرشادات المساهمة.