LogoENEnglish

Packages در Node.js

یک Package در Node.js مجموعه‌ای از فایل‌ها و پوشه‌هاست که توسط فایل package.json توصیف می‌شود. این فایل مشخص می‌کند که ماژول‌ها چگونه باید بارگذاری شوند، نوع ماژول‌ها (CommonJS یا ES Module) چیست، و چه مسیرهایی به‌عنوان entry point یا exports در دسترس هستند. Node.js از دو سیستم ماژول (CommonJS و ES Modules) پشتیبانی می‌کند و با استفاده از فیلدهای type, main, exports, و imports در package.json می‌توان رفتار بارگذاری را کنترل کرد.

package.jsontype: "module" / "commonjs"main و exportssubpath exports / imports

~2 دقیقه مطالعه • بروزرسانی ۹ دی ۱۴۰۴

1. تعریف Package


یک Package پوشه‌ای است که شامل فایل package.json می‌باشد. این پوشه و زیرپوشه‌های آن تا رسیدن به پوشه‌ای با package.json دیگر یا پوشه node_modules بخشی از همان Package محسوب می‌شوند.


2. تعیین سیستم ماژول


  • فایل‌های با پسوند .mjs همیشه ES Module هستند.
  • فایل‌های .cjs همیشه CommonJS هستند.
  • فایل‌های .js بسته به فیلد type در package.json به‌عنوان ES Module یا CommonJS تفسیر می‌شوند.
  • اگر فیلد type وجود نداشته باشد، فایل‌های .js به‌طور پیش‌فرض CommonJS هستند.

3. Syntax Detection


اگر فایل .js فاقد فیلد type باشد، Node.js کد را بررسی می‌کند. وجود دستورهای import, export, import.meta یا await در سطح بالا باعث می‌شود فایل به‌عنوان ES Module تفسیر شود.


4. Resolution و Loading


  • require(): مخصوص CommonJS، از پوشه‌ها به‌عنوان ماژول پشتیبانی می‌کند و پسوندها را به‌ترتیب .js, .json, .node امتحان می‌کند.
  • import: مخصوص ES Modules، نیاز به پسوند کامل دارد و از URLها پشتیبانی می‌کند.

5. فیلد type در package.json


این فیلد مشخص می‌کند که فایل‌های .js درون Package به‌عنوان ES Module یا CommonJS تفسیر شوند:


// package.json
{
  "type": "module"
}

6. Entry Points


  • main: نقطهٔ ورود پیش‌فرض (قدیمی‌تر).
  • exports: روش مدرن‌تر برای تعریف چندین entry point و کنترل دقیق subpaths.

7. Subpath Exports


با استفاده از exports می‌توان مسیرهای خاصی را در دسترس قرار داد:


// package.json
{
  "exports": {
    ".": "./index.js",
    "./submodule.js": "./src/submodule.js"
  }
}

8. Subpath Imports


فیلد imports برای تعریف مسیرهای خصوصی داخلی استفاده می‌شود. این مسیرها باید با # شروع شوند:


// package.json
{
  "imports": {
    "#dep": "./dep-polyfill.js"
  }
}

9. Conditional Exports


امکان تعریف مسیرهای متفاوت برای شرایط مختلف وجود دارد:


// package.json
{
  "exports": {
    "import": "./index-module.js",
    "require": "./index-require.cjs"
  }
}

10. Self-Referencing


یک Package می‌تواند خودش را با نامش import یا require کند، به شرطی که فیلد exports تعریف شده باشد.


نتیجه‌گیری


مدیریت Packages در Node.js با استفاده از فایل package.json امکان کنترل دقیق نوع ماژول‌ها، مسیرهای ورود، و رفتار بارگذاری را فراهم می‌کند. استفادهٔ صحیح از فیلدهای type, exports, و imports باعث می‌شود بسته‌ها قابل پیش‌بینی، امن و سازگار با ابزارهای مدرن باشند.


نوشته و پژوهش شده توسط دکتر شاهین صیامی

Next Article