‏راهنمای مهاجرت از pnpm v10 به v11

pnpm نسخه ۱۱ با یه سری تغییرات اساسی اومده که هر کسی داره از v10 آپگرید می‌کنه باید باهاشون آشنا بشه. این نسخه نحوه‌ی خوندن کانفیگ رو کاملاً زیر و رو کرده و چند تا ابزار و تنظیم قدیمی رو حذف یا جایگزین کرده.

خبر خوب اینه که تیم pnpm یه کدمود رسمی آماده کرده که بیشتر این تغییرات رو به‌صورت خودکار روی پروژه‌ات اعمال می‌کنه. کافیه توی ریشه‌ی پروژه‌ات اجرایش کنی تا خیلی از کارهای تکراری رو برات انجام بده.

مهم‌ترین کاری که کدمود انجام می‌ده اینه که دیگه pnpm از فیلد pnpm توی package.json تنظیمات نمی‌خونه. همه‌ی کانفیگ‌ها باید برن توی فایل pnpm-workspace.yaml. کدمود این انتقال رو خودش انجام می‌ده.

فایل .npmrc هم تغییر کرده. از این به بعد، pnpm فقط تنظیمات مربوط به احراز هویت و رجیستری رو از .npmrc می‌خونه. بقیه‌ی تنظیمات مثل hoist-pattern یا node-linker باید برن توی pnpm-workspace.yaml با فرمت camelCase. این کارم کدمود انجام می‌ده.

چند تا تنظیم قدیمی هم با هم ادغام شدن. مثلاً onlyBuiltDependencies، neverBuiltDependencies و ignoredBuiltDependencies همه تبدیل شدن به یه مپ واحد به اسم allowBuilds. همینطور سه تا تنظیم مدیریت نسخه‌ی پکیج منیجر (managePackageManagerVersions، packageManagerStrict و packageManagerStrictVersion) حالا همه زیر یه کلید واحد به اسم pmOnFail قرار می‌گیرن.

ولی یه سری تغییرات هستن که کدمود نمی‌تونه خودش انجام بده و باید دستی بهشون رسیدگی کنی. مثلاً اگه توی تنظیمات audit از CVE ID استفاده می‌کردی، باید اونا رو به GHSA ID تبدیل کنی. همچنین متغیرهای محیطی npm_config_* دیگه خونده نمی‌شن و باید همه‌جا (CI، داکر، پروفایل شل) اسمشون رو به pnpm_config_* تغییر بدی.

چند تا تغییر رفتاری هم هست که ممکنه غافل‌گیرت کنه. pnpm link دیگه از global store پکیج حل نمی‌کنه و باید مسیر نسبی یا مطلق بدی. دستور pnpm install -g بدون آرگومان دیگه کار نمی‌کنه و باید از pnpm add -g استفاده کنی. pnpm server هم کلاً حذف شده. یه نکته‌ی جالب دیگه اینه که اگه توی package.json اسکریپتی با اسم clean، setup، deploy یا rebuild داری، pnpm v11 اونا رو به‌جای دستورات built-in اجرا می‌کنه.

نکات کلیدی:

• کدمود رسمی بیشتر تغییرات رو خودکار اعمال می‌کنه
• تنظیمات دیگه از فیلد pnpm در package.json خونده نمی‌شن و باید توی pnpm-workspace.yaml باشن
• .npmrc فقط برای تنظیمات auth و registry به‌کار می‌ره
• متغیرهای npm_config_* باید به pnpm_config_* تغییر نام بدن
• allowBuilds جایگزین چند تنظیم build dependency شده
• pmOnFail جایگزین سه تنظیم مدیریت نسخه‌ی پکیج منیجر شده
• pnpm server حذف شده و pnpm link رفتار جدیدی داره
• اسکریپت‌های هم‌نام با دستورات built-in الان اولویت بیشتری دارن