سرفصل‌های آموزشی
آموزش npm
publish کردن پکیج در npm

publish کردن پکیج در npm

بعد از این که پروژه‌مان را نوشتیم، می‌توانیم آن را در قالب یک پکیج در npm منتشر کنیم. قبل از انتشار یک پکیج در npm، لازم است مراحلی را طی کنیم و پیش‌نیازهایی داشته باشیم:

1. اولاً یک حساب کاربری npm داشته باشیم. برای این کار هم کافیست به سایت npmjs.com برویم و یک حساب کاربری ایجاد نماییم. توجه شود برای «استفاده» از پکیج‌های npm نیازی به حساب کاربری نیست، ولی برای «منتشر کردنِ» یک پکیج، لازم است که حساب داشته باشیم. اگر پکیجی که می‌خواهیم منتشر کنیم private باشد، حتماً باید یک حساب کاربری پولی داشته باشیم، اگر هم می‌خواهیم پکیجمان بصورت عمومی منتشر شود، حساب کاربری رایگان کفایت می‌کند. در فصل دوم (مباحث پیشرفته‌تر در npm) به این موضوع بصورت مفصل پرداخته‌ایم

2. برای این که درباره پکیجمان و همچنین طرز استفاده از آن اطلاعات بدهیم، لازم است که فایلی با نام README.md در دایرکتوری روتِ پروژه‌ قرار دهیم. نوشته‌های این فایل همان توضیحاتی هستند که در صفحه مربوط به پکیج در سایت npm نمایش داده می‌شود. این فایل به ما کمک می‌کند تا تجربه کاربری مناسبی را در اختیار کسانی قرار دهیم که از پکیجمان استفاده می‌کنند. در توضیحاتی که از طریق README.md می‌دهیم، خوب است مواردی گنجانده شود، از جمله: راهنمایی نصب پکیج، پیکربندی آن، نحوه استفاده از آن در کد، و هر چیزی که فکر می‌کنیم برای کاربر مفید خواهد بود.
عبارت md. مخفف markdown است. markdown یک markup language سبک است که سینتکس ساده‌ای دارد و بوسیله ابزاری با همین نام، می‌توان به راحتی آن را به html و بسیاری فرمت‌های دیگر تبدیل کرد. این فرمت در حوزه وب خیلی کاربرد دارد و از آن برای استایل دادن به نوشته‌ها استفاده می‌شود. به این ترتیب که برخی کاراکترها در فرمت md. معنای خاصی دارند و استایل خاصی به نوشته‌ها می‌دهند، مثلاً با قرار دادن آن‌ها در قسمتی از متن، می‌توان آن قسمت را بعنوان هدر تعریف کرد، شماره گذاری کرد، bold کرد و ... .

برای دانستن بیشتر در این مورد، می‌توانید به آدرس زیر سری بزنید:

https://guides.github.com/features/mastering-markdown/

3. نام‌گذاری درست برای پکیج اهمیت بالایی دارد. وقتی داریم اسمی برای یک پکیجِ اسکوپ‌دار انتخاب می‌کنیم، یادمان باشد که این نام باید منحصربه‌فرد باشد، گویا(descriptive) باشد، توهین‌آمیز نباشد و از علامت تجاری دیگران استفاده نکند، و در کل نباید ناقض قیدهایی باشد که در قوانین npm trademark وجود دارد و پایبند به سیاست‌ها و قوانین npm باشد.
برای نام‌گذاری پکیج‌های بدون اسکوپ، باید توجه داشت نامی که انتخاب می‌کنیم قبلاً توسط دیگران گرفته نشده باشد، از نظر هجایی شبیه نام‌های دیگر نباشد، و برای دیگران گیج‌کننده نباشد و آن‌ها را در تشخیص نویسنده پکیج و ... دچار مشکل نکند.
خوب است که قبل از انتخاب نام برای پکیج، سری به سایت npm بزنیم و با یک جستجو، بررسی کنیم اسمی شبیهِ اسمی که برای پکیجمان در نظر داریم قبلاً توسط دیگران استفاده شده‌است یا نه، و اگر استفاده شده بود در نام‌گذاری‌مان تجدید نظر نماییم. اسم نباید با dot یا underscore شروع شود و در کل هم باید URL-safe باشد، یعنی بتوان آن را بدون مشکل در url مرورگر قرار داد.
آدرس زیر توضیحات بیشتری در مورد این استاندارد نام‌گذاری می‌دهد:

https://docs.npmjs.com/files/package.json#name

4. قبل از انتشار پکیج، خوب است که license آن را مشخص کنیم. خوب است با توجه به استاندارد semver (برای مطالعه درباره استاندارد semver این مقاله از سکان را مطالعه کنید) و نیز با توجه قواعد نسخه‌بندی در npm (برای مطالعه بیشتر به مقاله نسخه‌بندی در npm از همین مجموعه مقالات مراجعه کنید) شماره نسخه‌اش را به درستی تعیین کنیم. اگر پروژه ما به دیگران امکان همکاری(contributing) می‌دهد، می‌توان در قالب فایلی به نام CONTRIBUTING.md از آن‌ها دعوت به همکاری کنیم و هر توضیحی که لازم می‌دانیم را از این طریق در اختیار آن‌ها قرار دهیم. همان‌طور که مشخص است فرمت این فایل نیز md. می‌باشد.

5. بصورت پیش‌فرض و هنگام انتشار یک پکیج، تمامی‌ فایل‌ها و فولدرهای موجود در دایرکتوری روتِ پروژه انتشار می‌‌یابد. کسی هم که بعداً از پکیج ما استفاده می‌کند، مثلاً با دستور npm install اقدام به نصب پکیج ما می‌کند، همان فایل‌ها و فولدرها را دریافت خواهد کرد. می‌توان تعیین کرد که از بین این فایل‌ها و فولدرها کدام‌ها منتشر شوند و کدام‌ها نه. این کار سه راه دارد:
• استفاده از فایل npmignore. که با استفاده از آن می‌شود فایل‌هایی که در دایرکتوری پروژه هستند و ما نمی‌خواهیم منتشر شوند را مشخص کنیم. (یعنی بعضی فایل‌ها را استثنا کنیم و آن‌ها را در لیست سیاه قرار دهیم)

• همین کار را می‌توان با استفاده از gitignore. هم انجام داد. (اگر در مسیر پروژه هم gitignore. وجود داشته باشد و هم npmignore. ، فایل gitignore. اولویت دارد)

• می‌توان با استفاده از مشخصه “files” در فایل package.json مشخص کرد که چه فایل‌هایی انتشار یابند. (فایل‌هایی را که می‌خواهیم انتشار یابند در لیست سفید قرار دهیم)
برای مطالعه عمیق‌تر در این باره می‌توانید به آدرس زیر مراجعه کنید:

https://zellwk.com/blog/ignoring-files-from-npm-package/

6. روش استاندارد این است که قبل از انتشار پکیج، آن را تست کنیم.

7. همان‌طور که گفتیم برای منتشر کردن پکیجی که خودمان آن را نوشته‌ایم، حتماً نیاز به حساب کاربری داریم. بعد از ایجاد حساب کاربری و نوشتن کد پکیج، به سراغ انتشار آن می‌رویم ...
در این مرحله باید چک کنیم که سیستم ما بعنوان کاربر npm لاگین باشد. جهت لاگین شدن می‌توانیم از دستور npm login استفاده کنیم. با اجرای این دستور، npm نام کاربری و گذرواژه‌ای را که هنگام ثبت‌نام در سایت npm استفاده کرده بودیم از ما می‌پرسد و اگر صحیح واردشان کنیم، با موفقیت لاگین خواهد کرد. زمانی هم که می‌خواهیم از حسابمان خارج شویم، به راحتی و با دستور npm logout این کار را می‌کنیم. یکی از دستورات کاربردیِ npm، دستور npm whoami است. این دستور به ما می‌گوید که سیستم ما با چه حسابی وارد npm شده و نام کاربریِ آن حساب را برایمان چاپ می‌کند. اگر هم لاگین نباشیم، این موضوع را به ما اطلاع می‌دهد.
بعد از این که مطمئن شدیم به درستی لاگین کرده‌ایم، با دستور npm publish پکیج را منتشر می‌کنیم. البته این انتشار ملاحظاتی دارد، مثلاً این که برای انتشار پکیج‌های private نیاز به عضویت پولی داریم و ... که در این باره نیز در قسمت مباحث پیشرفته، بیشتر توضیح داده‌ایم. اما ساختار کلی دستور npm publish به این شکل است:

این دستور پکیج ما را در رجیستری منتشر می‌کند و به این ترتیب تمامی فایل‌هایی که در دایرکتوری پکیج وجود داشت (بغیر از موارد استثنا که ذکر آن رفت) روی npm می‌رود و دیگران می‌توانند آن را install و استفاده کنند.
اگر پکیجمان را بصورت public منتشر کرده باشیم، صفحه مربوط به پکیج در سایت npm آدرس زیر را خواهد داشت:

https://npmjs.com/package/package-name

برای کسب اطلاعات بیشتر درباره این مسائل می‌توانید به مستند npm مراجعه کنید:

https://docs.npmjs.com/cli/publish

نکته آنکه نسخه انتشار یافته یک پکیج را می‌توان با دستور npm unpublish از روی رجیستری npm حذف کرد. خود این حذف کردن هم قوانین و ملاحظاتی دارد که طبق معمول پیشنهاد می‌کنیم به مستند اصلیِ آن مراجعه نمایید:

https://docs.npmjs.com/cli/unpublish

اگر درباره مبحث انتشار پکیج در npm سؤال و یا نظری داشتید، آن را در بخش نظرات یا در تالار گفتگو با ما در میان بگذارید.
در قسمت بعد از این مجموعه مقالات، یاد می‌گیریم که چه‌طور از قابلیت scripting در npm استفاده کنیم. همراه ما باشید...

online-support-icon