چرا @wordpress/scripts استاندارد ساخت بلاک در وردپرس شده است؟

@wordpress/scripts یک پکیج رسمی npm است که ابزارهای ساخت، کامپایل و بسته‌بندی را برای توسعه بلاک‌ها، افزونه‌ها و قالب‌های وردپرس فراهم می‌کند و از سال ۲۰۱۹ به استاندارد عملی صنعت تبدیل شده است. این پکیج با انتزاع پیچیدگی‌های Webpack، Babel و ابزارهای linting، یک محیط توسعه یکپارچه ایجاد کرده که در آن توسعه‌دهنده بدون نگرانی از پیکربندی، روی کد تمرکز می‌کند. دستورات ساده‌ای مانند wp-scripts build و wp-scripts start فرآیندهای پیچیده کامپایل را مدیریت می‌کنند و نتیجه آن، بسته‌هایی سازگار با استانداردهای وردپرس است. در این راهنما، معماری، دستورات، پیکربندی سفارشی، و نکات پیشرفته این ابزار بررسی می‌شود.

نخستین بار که با پیکربندی Webpack برای یک بلاک ساده دست‌وپنجه نرم کردم، ساعتی را صرف تنظیم Babel، PostCSS و Source Maps کردم. چند سال بعد، وقتی wp-scripts را دیدم، متوجه شدم آن ساعت‌ها دیگر تکرار نخواهد شد. این راهنما حاصل استفاده روزمره از این ابزار در پروژه‌های واقعی است. 🛠️

@wordpress/scripts چیست؟

@wordpress/scripts (که در ادامه به اختصار wp-scripts نامیده می‌شود) یک پکیج npm رسمی است که توسط تیم هسته گوتنبرگ توسعه یافته و مجموعه‌ای از ابزارهای ساخت، کامپایل، و linting را برای پروژه‌های وردپرس فراهم می‌کند. این پکیج در نسخه ۵.۰ وردپرس (سال ۲۰۱۹) معرفی شد و از آن زمان به استاندارد ساخت افزونه‌ها و بلاک‌ها تبدیل شده است.

wp-scripts در هسته خود، چند ابزار شناخته‌شده را بسته‌بندی کرده: Webpack برای بسته‌بندی، Babel برای ترجمه جاوااسکریپت مدرن، PostCSS برای پردازش CSS، ESLint و Prettier برای کیفیت کد، و Jest برای تست. اما نکته کلیدی این است که همه این ابزارها از پیش پیکربندی شده‌اند و با استانداردهای وردپرس هماهنگ شده‌اند.

در نگاه اول، wp-scripts یک wrapper ساده روی ابزارهای موجود به نظر می‌رسد. اما در واقع، این پکیج یک قرارداد توسعه‌ای است: به جای اینکه هر توسعه‌دهنده پیکربندی خود را بسازد، همه از یک پیکربندی واحد استفاده می‌کنند که توسط تیم هسته نگهداری می‌شود. برای آشنایی با مبانی بلاک‌ها، مقاله Gutenberg چیست و چگونه ویرایش محتوای وردپرس را متحول کرد؟ را ببینید.

wp-scripts یک ابزار نیست؛ یک قرارداد است. قراردادی که تضمین می‌کند پروژه شما با استانداردهای اکوسیستم وردپرس هماهنگ باشد.

چرا به استاندارد ساخت بلاک تبدیل شد؟

تبدیل شدن wp-scripts به استاندارد صنعت، حاصل ترکیب چند عامل کلیدی است که هر یک به تنهایی می‌توانست این پکیج را مطرح کند.

۱. حذف پیکربندی تکراری

پیش از wp-scripts، هر توسعه‌دهنده‌ای که یک بلاک می‌ساخت، باید پیکربندی Webpack، Babel و PostCSS را از صفر می‌نوشت. این پیکربندی به‌طور معمول ۱۰۰ تا ۳۰۰ خط کد بود و اشتباهات کوچک در آن می‌توانست ساعت‌ها وقت تلف کند. wp-scripts این پیکربندی را به یک dependency کاهش داده است.

۲. هماهنگی با اکوسیستم وردپرس

wp-scripts از پکیج‌های @wordpress/* مانند @wordpress/blocks، @wordpress/components و @wordpress/data به صورت بومی پشتیبانی می‌کند. این بدان معناست که توسعه‌دهنده می‌تواند این پکیج‌ها را import کند و بدون پیکربندی اضافی از آن‌ها استفاده نماید. این هماهنگی در سایر ابزارهای build وجود ندارد یا نیازمند پیکربندی دستی است.

۳. نگهداری توسط تیم هسته

wp-scripts توسط همان تیمی نگهداری می‌شود که گوتنبرگ را می‌سازد. این بدان معناست که هر تغییر در معماری گوتنبرگ، بلافاصله در wp-scripts بازتاب می‌یابد. توسعه‌دهندگان با استفاده از wp-scripts، به‌طور خودکار با آخرین استانداردهای گوتنبرگ هماهنگ می‌شوند.

۴. یکپارچگی با create-block

ابزار create-block که برای اسکافولد کردن بلاک‌ها استفاده می‌شود، به‌طور پیش‌فرض wp-scripts را در پروژه جدید نصب می‌کند. این یکپارچگی باعث شده که هر بلاک جدیدی که در اکوسیستم ساخته می‌شود، از همان ابتدا با wp-scripts کار کند.

۵. پشتیبانی از WordPress Playground و wp-env

هر دو ابزار Playground و wp-env از خروجی wp-scripts پشتیبانی می‌کنند. این هماهنگی باعث شده که توسعه‌دهندگان بتوانند بسته‌های تولیدشده توسط wp-scripts را مستقیماً در این محیط‌ها اجرا کنند. برای مطالعه درباره wp-env، مقاله @wordpress/env چیست و چرا محیط توسعه لوکال وردپرس را متحول کرد؟ را ببینید.

پیش از wp-scripts: هرج‌ومرج پیکربندی

برای درک اهمیت wp-scripts، باید به چالش‌های پیش از آن نگاه کرد. در سال‌های نخست گوتنبرگ (۲۰۱۸-۲۰۱۹)، توسعه‌دهندگان بلاک با مشکلات متعددی مواجه بودند.

مشکل نسخه‌های ناسازگار

Webpack نسخه ۴ با Webpack نسخه ۵ سازگار نبود. Babel نسخه ۶ با Babel ۷ تفاوت‌های قابل توجهی داشت. هر بار که یکی از این ابزارها به‌روزرسانی می‌شد، پیکربندی پروژه‌ها می‌شکست. توسعه‌دهندگان مجبور بودند ساعت‌ها وقت صرف رفع ناسازگاری‌ها کنند.

مشکل تعدد پیکربندی‌ها

هر پروژه پیکربندی خود را داشت. اگر توسعه‌دهنده‌ای بین سه پروژه جابجا می‌شد، باید با سه پیکربندی متفاوت کار می‌کرد. این تعدد نه تنها زمان یادگیری را افزایش می‌داد بلکه انتقال کد بین پروژه‌ها را نیز دشوار می‌کرد.

مشکل نامشخص بودن بهترین شیوه‌ها

در آن زمان، هیچ مرجع رسمی برای اینکه بهترین شیوه ساخت بلاک چیست وجود نداشت. هر تیم رویکرد خود را اتخاذ می‌کرد. این پراکندگی باعث شد که اکوسیستم بلاک‌ها ناهمگون باشد و یادگیری از پروژه‌های دیگر دشوار شود.

wp-scripts این هرج‌ومرج را با یک پیکربندی واحد، نگهداری‌شده توسط تیم هسته، جایگزین کرد. این رویکرد مشابه کاری است که Create React App برای اکوسیستم React انجام داد. برای مطالعه درباره مدیریت پکیج، مقاله npm یا Yarn؛ کدام برای مدیریت پکیج سریع‌تر است؟ را ببینید.

معماری فنی و لایه‌های انتزاعی

wp-scripts از چند لایه انتزاعی تشکیل شده که هر یک نقش مشخصی در فرآیند ساخت دارند. درک این لایه‌ها برای استفاده حرفه‌ای از wp-scripts ضروری است.

لایه اول: CLI

لایه CLI رابط کاربری wp-scripts است. دستوراتی مانند wp-scripts build، wp-scripts start و wp-scripts lint-js در این لایه تعریف شده‌اند. هر دستور، یک اسکریپت Node.js را فراخوانی می‌کند که مسئولیت اجرای فرآیند مربوطه را بر عهده دارد.

لایه دوم: پیکربندی پیش‌فرض

wp-scripts مجموعه‌ای از پیکربندی‌های پیش‌فرض را در پوشه config/ نگهداری می‌کند. این پیکربندی‌ها شامل webpack.config.js، .babelrc، .eslintrc، jest.config.js و سایر ابزارهاست. این پیکربندی‌ها برای پروژه‌های وردپرس بهینه‌سازی شده‌اند.

لایه سوم: بسته‌بندی Webpack

قلب wp-scripts، پیکربندی Webpack است. این پیکربندی شامل Loaderها برای JavaScript، CSS، SCSS، تصاویر و فونت‌هاست. همچنین Pluginهایی مانند MiniCssExtractPlugin و CopyWebpackPlugin در آن یکپارچه شده‌اند. برای مطالعه درباره Webpack، مقاله Webpack یا Vite؛ کدام برای باندل کردن سریع‌تر است؟ را ببینید.

لایه چهارم: پکیج‌های وردپرس

wp-scripts از طریق مکانیزم Dependency Extraction، پکیج‌های @wordpress/* را به صورت خارجی (External) در نظر می‌گیرد. این بدان معناست که این پکیج‌ها در بسته نهایی گنجانده نمی‌شوند و در عوض به متغیرهای سراسری wp.blocks، wp.components و غیره Map می‌شوند. این رویکرد حجم بسته را به شدت کاهش می‌دهد.

معماری wp-scripts بر پایه انتزاع تدریجی بنا شده: هر لایه پیچیدگی لایه زیرین را پنهان می‌کند و یک رابط ساده‌تر ارائه می‌دهد.

نصب و راه‌اندازی اولیه

نصب wp-scripts ساده است و نیازمند Node.js نسخه ۱۸ یا بالاتر است. مراحل نصب به شرح زیر است:

گام اول: مقداردهی اولیه npm

npm init -y

این دستور یک فایل package.json پایه ایجاد می‌کند. سپس می‌توانید فیلدهای آن را مطابق نیاز ویرایش کنید.

گام دوم: نصب wp-scripts

npm install --save-dev @wordpress/scripts

این دستور wp-scripts و تمام وابستگی‌های آن را نصب می‌کند. پس از نصب، دستور wp-scripts در پوشه node_modules/.bin/ در دسترس خواهد بود.

گام سوم: تعریف اسکریپت‌ها در package.json

{
    "scripts": {
        "build": "wp-scripts build",
        "start": "wp-scripts start",
        "format": "wp-scripts format",
        "lint:js": "wp-scripts lint-js",
        "lint:css": "wp-scripts lint-style",
        "test:unit": "wp-scripts test-unit-js"
    }
}

با این پیکربندی، می‌توانید با npm run build بسته تولیدی بسازید و با npm run start در حالت Watch کار کنید. برای مطالعه درباره ساختار فایل‌های افزونه، مقاله ساختار فایل‌های یک افزونه استاندارد وردپرس را ببینید.

دستورات اصلی و کاربردهای آن‌ها

wp-scripts مجموعه‌ای از دستورات را ارائه می‌دهد که هر یک برای یک هدف مشخص طراحی شده‌اند. جدول زیر مهم‌ترین این دستورات را معرفی می‌کند.

حالت توسعه: wp-scripts start

دستور start پروژه را در حالت توسعه اجرا می‌کند. در این حالت، Webpack فایل‌های منبع را زیر نظر دارد و با هر تغییر، بسته را مجدداً می‌سازد. خروجی این حالت شامل Source Maps است که اشکال‌زدایی را ساده می‌کند. همچنین Hot Module Replacement (HMR) فعال است، اگرچه در محیط وردپرس به دلیل معماری کلاسیک، HMR به‌طور کامل کار نمی‌کند.

حالت تولید: wp-scripts build

دستور build بسته‌های نهایی را برای انتشار می‌سازد. در این حالت، کد Minify شده، Source Maps حذف می‌شوند، و فایل‌ها با هش محتوا نام‌گذاری می‌شوند. این حالت برای انتشار در مخزن وردپرس یا CI/CD طراحی شده است.

بررسی کیفیت کد

دستورات lint-js و lint-style از پیکربندی‌های استاندارد وردپرس استفاده می‌کنند. این پیکربندی‌ها بر پایه @wordpress/eslint-plugin و @wordpress/stylelint-config هستند و شامل قواعد اختصاصی برای وردپرس مانند الزام استفاده از نیم‌فاصله در ترجمه‌ها می‌شوند.

block.json و تعامل با wp-scripts

در نسخه‌های اخیر گوتنبرگ، فایل block.json به عنوان منبع واحد حقیقت (Single Source of Truth) برای تعریف بلاک معرفی شده است. wp-scripts به‌طور خودکار فایل block.json را پردازش کرده و بسته‌های مناسب را می‌سازد.

ساختار block.json

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "my-plugin/my-block",
    "title": "My Block",
    "category": "widgets",
    "icon": "smiley",
    "editorScript": "file:./index.js",
    "editorStyle": "file:./index.css",
    "style": "file:./style-index.css",
    "render": "file:./render.php"
}

کلیدهای editorScript، editorStyle و style به فایل‌های منبع اشاره می‌کنند. wp-scripts این فایل‌ها را پردازش کرده و بسته‌های نهایی را در پوشه build/ قرار می‌دهد.

پردازش خودکار توسط wp-scripts

هنگام اجرای wp-scripts build، ابزار به‌طور خودکار فایل block.json را در پوشه ریشه پروژه جستجو می‌کند. اگر پیدا شود، فایل‌های منبع را کامپایل کرده و یک نسخه کپی از block.json با مسیرهای به‌روز در پوشه build/ قرار می‌دهد. این پردازش خودکار باعث می‌شود که توسعه‌دهنده نگران پیکربندی نباشد. برای مطالعه درباره بلاک‌های سفارشی، مقاله آموزش ساخت بلوک سفارشی گوتنبرگ را ببینید.

سفارشی‌سازی webpack.config.js

در برخی پروژه‌ها، پیکربندی پیش‌فرض wp-scripts کافی نیست و نیاز به سفارشی‌سازی دارید. wp-scripts امکان توسعه پیکربندی پیش‌فرض را از طریق فایل webpack.config.js فراهم می‌کند.

روش اول: تابع Map

ساده‌ترین روش سفارشی‌سازی، استفاده از یک تابع در فایل webpack.config.js است که پیکربندی پیش‌فرض را دریافت کرده و آن را تغییر می‌دهد:

const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );

module.exports = {
    ...defaultConfig,
    resolve: {
        ...defaultConfig.resolve,
        alias: {
            ...defaultConfig.resolve.alias,
            '@my-alias': path.resolve( __dirname, 'src/my-module' ),
        },
    },
};

در این مثال، یک alias جدید برای مسیر src/my-module تعریف شده است. این alias در تمام importهای پروژه قابل استفاده است.

روش دوم: استفاده از getWebpackConfig

روش پیشرفته‌تر، استفاده از تابع getWebpackConfig است که در نسخه‌های اخیر wp-scripts اضافه شده. این تابع امکان تغییر پیکربندی پیش‌فرض با استفاده از یک تابع Callback را فراهم می‌کند:

const { getWebpackConfig } = require( '@wordpress/scripts/bin/get-webpack-config' );

module.exports = getWebpackConfig( {
    outputPath: 'dist',
    entry: {
        index: './src/index.js',
        admin: './src/admin.js',
    },
} );

افزودن Entry Point سفارشی

در پروژه‌های افزونه، ممکن است نیاز داشته باشید چندین Entry Point تعریف کنید. wp-scripts به‌طور پیش‌فرض فایل src/index.js را به عنوان نقطه ورود می‌شناسد، اما می‌توانید با تغییر پیکربندی، چندین نقطه ورود اضافه کنید:

const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );

module.exports = {
    ...defaultConfig,
    entry: {
        'my-block': './src/my-block.js',
        'admin-panel': './src/admin-panel.js',
    },
};

سفارشی‌سازی wp-scripts مانند جواهرسازی است: در بیشتر موارد پیکربندی پیش‌فرض کافی است، اما در پروژه‌های خاص می‌توان آن را با ظرافت تنظیم کرد.

مدیریت Entry Points و خروجی بسته‌ها

wp-scripts به‌طور پیش‌فرض از پوشه src/ به عنوان محل فایل‌های منبع و پوشه build/ به عنوان محل خروجی استفاده می‌کند. ساختار پیشنهادی به شرح زیر است:

my-plugin/
├── src/
│   ├── index.js       # Entry اصلی (بلاک)
│   ├── index.scss     # استایل اصلی
│   ├── style.scss     # استایل فرانت‌اند
│   └── view.js        # اسکریپت فرانت‌اند
├── build/             # خروجی (تولیدشده)
├── block.json
├── package.json
└── readme.txt

هنگام اجرای wp-scripts build، فایل‌های src/ پردازش شده و در build/ قرار می‌گیرند. فایل‌های CSS از SCSS کامپایل شده و به index.css و style-index.css تبدیل می‌شوند. فایل‌های جاوااسکریپت با Dependency Extraction به بسته‌های وردپرس Map می‌شوند.

ابزارهای تست و linting یکپارچه

wp-scripts مجموعه‌ای از ابزارهای تست و کیفیت کد را به‌طور یکپارچه فراهم می‌کند. این ابزارها از پیکربندی‌های استاندارد وردپرس استفاده می‌کنند و به‌طور خودکار با پروژه شما یکپارچه می‌شوند.

ESLint و Prettier

دستور wp-scripts lint-js از ESLint با پیکربندی @wordpress/eslint-plugin استفاده می‌کند. این پیکربندی شامل قواعد اختصاصی وردپرس است، از جمله الزام استفاده از __() برای ترجمه، استفاده از @wordpress/i18n و رعایت ساختار استاندارد. دستور wp-scripts format نیز از Prettier برای فرمت خودکار کد استفاده می‌کند.

Stylelint

دستور wp-scripts lint-style از Stylelint با پیکربندی @wordpress/stylelint-config استفاده می‌کند. این پیکربندی شامل قواعد مربوط به ترتیب خصوصیات CSS، استفاده از متغیرها، و سازگاری با RTL است.

Jest برای تست واحد

دستور wp-scripts test-unit-js از Jest برای اجرای تست‌های واحد استفاده می‌کند. Jest در wp-scripts به‌طور پیش‌فرض با ماژول‌های وردپرس سازگار شده و توابع Mocking برای @wordpress/data، @wordpress/i18n و سایر پکیج‌ها فراهم کرده است.

Playwright برای تست E2E

دستور wp-scripts test-e2e از Playwright برای تست‌های End-to-End استفاده می‌کند. این ابزار در نسخه‌های اخیر wp-scripts اضافه شده و امکان نوشتن تست‌های یکپارچه با مرورگر واقعی را فراهم می‌کند. برای مطالعه درباره تست‌ها، مقاله چک‌لیست عیب‌یابی حرفه‌ای خطاهای وردپرس را ببینید.

ادغام با create-block و اسکافولدینگ

ابزار create-block که به‌طور رسمی توسط تیم گوتنبرگ نگهداری می‌شود، برای اسکافولد کردن پروژه‌های بلاک طراحی شده است. این ابزار به‌طور پیش‌فرض wp-scripts را در پروژه جدید نصب کرده و پیکربندی می‌کند.

ایجاد بلاک جدید

npx @wordpress/create-block my-block

این دستور یک پروژه کامل با ساختار استاندارد ایجاد می‌کند: پوشه src/ برای فایل‌های منبع، فایل block.json برای تعریف بلاک، package.json با اسکریپت‌های wp-scripts، و پوشه build/ برای خروجی. پس از ایجاد، می‌توانید با npm start در حالت توسعه کار کنید.

شخصی‌سازی قالب اسکافولد

create-block از قالب‌های (Templates) قابل شخصی‌سازی پشتیبانی می‌کند. با استفاده از --template می‌توانید قالب مورد نظر خود را تعیین کنید. همچنین می‌توانید با --variant نسخه‌های مختلف اسکافولد (مانند static، dynamic، interactive) را انتخاب کنید.

ادغام با wp-env و محیط توسعه

wp-scripts به‌طور طبیعی با wp-env ادغام می‌شود. ترکیب این دو ابزار، یک محیط توسعه کامل را فراهم می‌کند که در آن: - wp-scripts مسئول ساخت و بسته‌بندی کد است. - wp-env مسئول اجرای وردپرس و کانتینرهای Docker است.

پیکربندی نمونه

{
    "scripts": {
        "start": "wp-env start && wp-scripts start",
        "build": "wp-scripts build",
        "wp-env": "wp-env"
    },
    "devDependencies": {
        "@wordpress/env": "^10.0.0",
        "@wordpress/scripts": "^30.0.0"
    }
}

با این پیکربندی، یک دستور npm run start هم محیط Docker را راه‌اندازی می‌کند و هم حالت Watch wp-scripts را فعال می‌کند. تغییرات در کد منبع، به‌طور خودکار در محیط wp-env بازتاب می‌یابد.

استفاده در CI/CD و خط لوله انتشار

wp-scripts برای استفاده در CI/CD طراحی شده است. از آنجا که پیکربندی ثابت و قابل تکرار است، می‌توان آن را در GitHub Actions، GitLab CI یا Jenkins بدون تغییر استفاده کرد.

پیکربندی GitHub Actions

name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint:js
      - run: npm run test:unit
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build
          path: build/

این Workflow کد را lint کرده، تست‌های واحد را اجرا کرده، بسته تولیدی را می‌سازد، و آن را به عنوان artifact بارگذاری می‌کند. این رویکرد در پروژه‌های واقعی مانند مخزن گوتنبرگ و افزونه‌های محبوب استفاده می‌شود. برای مطالعه درباره CI/CD، مقاله CI/CD برای پروژه‌های وردپرسی چگونه پیاده‌سازی می‌شود؟ را ببینید.

عملکرد و بهینه‌سازی بسته‌ها

wp-scripts به‌طور پیش‌فرض چند تکنیک بهینه‌سازی را اعمال می‌کند که کیفیت بسته نهایی را تضمین می‌کند.

۱. Dependency Extraction

پکیج‌های @wordpress/* به صورت External تعریف می‌شوند. این بدان معناست که در بسته نهایی گنجانده نمی‌شوند و در عوض به متغیرهای سراسری Map می‌شوند. نتیجه این رویکرد، کاهش چشمگیر حجم بسته است.

۲. Code Splitting

wp-scripts از Code Splitting پشتیبانی می‌کند. با استفاده از import() داینامیک، می‌توانید بخش‌هایی از کد را به صورت Lazy Load بارگذاری کنید. این ویژگی برای افزونه‌های بزرگ که بخش‌های مختلفی دارند، حیاتی است.

۳. Minification و Tree Shaking

در حالت Build، کد به‌طور خودکار Minify می‌شود و Tree Shaking اعمال می‌گردد. Tree Shaking کدی که استفاده نمی‌شود را حذف می‌کند و حجم بسته را کاهش می‌دهد.

۴. Source Maps در حالت Development

در حالت Start، Source Maps تولید می‌شوند که اشکال‌زدایی را بسیار ساده‌تر می‌کند. در حالت Build، Source Maps به‌طور پیش‌فرض غیرفعال هستند تا حجم بسته کاهش یابد.

خطاهای رایج و عیب‌یابی

در استفاده از wp-scripts، برخی خطاهای رایج می‌توانند تجربه را تحت تأثیر قرار دهند. در ادامه، مهم‌ترین این خطاها بررسی می‌شود.

خطای «Cannot find module @wordpress/scripts»

این خطا زمانی رخ می‌دهد که wp-scripts به درستی نصب نشده باشد. راه‌حل:

rm -rf node_modules package-lock.json
npm install

خطای Build پس از تغییر block.json

اگر فایل block.json تغییر کند اما بسته‌های قدیمی باقی بمانند، خطا رخ می‌دهد. راه‌حل:

rm -rf build/
npm run build

خطای Timeout در CI

در محیط‌های CI با منابع محدود، Build ممکن است Timeout بخورد. راه‌حل شامل افزایش Timeout، استفاده از Node.js نسخه ۲۰، و کش کردن node_modules است.

خطای نسخه Node.js

wp-scripts نسخه‌های اخیر نیازمند Node.js ۱۸ یا بالاتر است. با دستور node -v نسخه خود را بررسی کنید.

خطای ESLint با پیام «Definition for rule ... not found»

این خطا ناشی از نسخه قدیمی پلاگین‌های ESLint است. راه‌حل، به‌روزرسانی @wordpress/scripts و اجرای مجدد npm install است.

خطاهای wp-scripts تقریباً همیشه به یکی از سه علت برمی‌گردند: نسخه Node.js، نصب ناقص پکیج‌ها، یا بسته‌های Cache قدیمی. با بررسی این سه، بیشتر مشکلات حل می‌شوند.

دیدگاه مهندسی پیشرفته

از منظر مهندسی نرم‌افزار، wp-scripts یک پیاده‌سازی از مفهوم Convention over Configuration است. در این الگو، ابزار مجموعه‌ای از قراردادها را تعریف می‌کند (مانند پوشه src/ برای فایل‌های منبع و build/ برای خروجی) و توسعه‌دهنده فقط زمانی که نیاز به تغییر داشته باشد، پیکربندی می‌نویسد. این رویکرد مشابه کاری است که Ruby on Rails برای توسعه وب و Spring Boot برای Java انجام داده‌اند.

در سطح معماری، wp-scripts از الگوی Facade استفاده می‌کند. این الگو یک رابط ساده را روی مجموعه‌ای از زیرسیستم‌های پیچیده ارائه می‌دهد. در مورد wp-scripts، رابط ساده wp-scripts build است، اما در پشت آن، ده‌ها ابزار و پیکربندی در حال هماهنگی هستند.

یکی از جنبه‌های پیشرفته، استفاده از پکیج @wordpress/dependency-extraction-webpack-plugin است. این پکیج یک تحلیل ایستا (Static Analysis) از importهای کد انجام می‌دهد و مشخص می‌کند که کدام پکیج‌ها باید External شوند. سپس یک فایل .asset.php تولید می‌کند که شامل لیست وابستگی‌ها و نسخه بسته است. این فایل توسط وردپرس برای مدیریت صف اسکریپت‌ها استفاده می‌شود.

در سطح پیشرفته‌تر، wp-scripts از Webpack ۵ با قابلیت Module Federation پشتیبانی می‌کند. این قابلیت به بسته‌های مختلف اجازه می‌دهد در زمان اجرا کد خود را به اشتراک بگذارند. اگرچه این قابلیت هنوز در اکوسیستم وردپرس به‌طور گسترده استفاده نمی‌شود، اما پتانسیل بالایی برای معماری‌های میکرو-فرانت‌اند دارد.

برای مهندسان ارشد، درک تعامل wp-scripts با سیستم Build گوتنبرگ اهمیت دارد. گوتنبرگ خود از یک پیکربندی Webpack پیچیده استفاده می‌کند که شامل چندین پکیج است. wp-scripts این پیکربندی را ساده‌سازی کرده اما همچنان از همان اصول پیروی می‌کند. توسعه‌دهندگانی که می‌خواهند بلاک‌های پیچیده بسازند، باید با این اصول آشنا باشند.

در آینده، انتظار می‌رود که wp-scripts با قابلیت‌هایی مانند پشتیبانی از Vite به عنوان Bundler جایگزین، ادغام عمیق‌تر با Interactivity API، و بهبود عملکرد در پروژه‌های بزرگ گسترش یابد. روند حرکت از Webpack به سمت ابزارهای سریع‌تر مانند Vite و esbuild در اکوسیستم JavaScript، احتمالاً بر wp-scripts نیز تأثیر خواهد گذاشت. برای مطالعه درباره Vite، مقاله Webpack یا Vite؛ کدام برای باندل کردن سریع‌تر است؟ را ببینید.

پرسش‌های پرتکرار درباره @wordpress/scripts

@wordpress/scripts چیست و چه کاربردی دارد؟

@wordpress/scripts یک پکیج npm رسمی است که ابزارهای ساخت، کامپایل، linting و تست را برای پروژه‌های وردپرس فراهم می‌کند. این پکیج بر پایه Webpack، Babel، ESLint، Prettier و Jest ساخته شده و برای توسعه بلاک‌ها، افزونه‌ها و قالب‌ها استفاده می‌شود.

تفاوت wp-scripts با Webpack معمولی چیست؟

wp-scripts یک پیکربندی پیش‌فرض روی Webpack است که برای وردپرس بهینه شده است. این پکیج پیچیدگی‌های پیکربندی Webpack، Babel و PostCSS را پنهان کرده و یک API ساده مبتنی بر CLI ارائه می‌دهد. همچنین از پکیج‌های @wordpress/* به صورت بومی پشتیبانی می‌کند.

چگونه یک بلاک با wp-scripts بسازم؟

ساده‌ترین راه استفاده از npx @wordpress/create-block my-block است. این دستور یک پروژه کامل با wp-scripts و ساختار استاندارد ایجاد می‌کند. سپس با npm start در حالت توسعه کار می‌کنید و با npm run build بسته نهایی را می‌سازید.

آیا می‌توانم webpack.config.js را سفارشی کنم؟

بله، می‌توانید یک فایل webpack.config.js در ریشه پروژه ایجاد کنید و پیکربندی پیش‌فرض wp-scripts را گسترش دهید. این کار از طریق import کردن پیکربندی پیش‌فرض و تغییر آن انجام می‌شود.

آیا wp-scripts از TypeScript پشتیبانی می‌کند؟

بله، wp-scripts از TypeScript به صورت بومی پشتیبانی می‌کند. کافی است فایل‌های خود را با پسوند .ts یا .tsx بسازید و در package.json اسکریپت‌های مربوطه را تنظیم کنید. برای مطالعه درباره TypeScript، مقاله تایپ اسکریپت از صفر: چرا جاوااسکریپت تنها کافی نیست؟ را ببینید.

آیا wp-scripts در CI/CD قابل استفاده است؟

بله، wp-scripts برای استفاده در CI/CD طراحی شده است. پیکربندی ثابت آن تضمین می‌کند که Build در هر محیطی یکسان باشد. می‌توان آن را در GitHub Actions، GitLab CI یا Jenkins استفاده کرد.

چگونه بسته‌های wp-scripts را بهینه کنم؟

wp-scripts به‌طور پیش‌فرض از Dependency Extraction، Minification و Tree Shaking استفاده می‌کند. برای بهینه‌سازی بیشتر، می‌توانید از Code Splitting با import() داینامیک استفاده کنید و از پکیج‌های اضافی در کد پرهیز نمایید.

آیا wp-scripts جایگزین ابزارهای build دیگر می‌شود؟

wp-scripts یک استاندارد دوفاکتو در اکوسیستم وردپرس است، اما ابزارهای دیگری مانند Vite و esbuild نیز می‌توانند برای ساخت بلاک استفاده شوند. انتخاب بین این ابزارها بستگی به نیاز پروژه و آشنایی تیم دارد.

آنچه در عمل اهمیت دارد

@wordpress/scripts یک تغییر پارادایمی در نحوه ساخت افزونه‌ها و بلاک‌های وردپرس است. این پکیج با حذف پیکربندی تکراری، تضمین هماهنگی با اکوسیستم وردپرس، و ارائه ابزارهای یکپارچه تست و linting، بهره‌وری توسعه‌دهندگان را به‌طور قابل توجهی افزایش داده است. از منظر معماری، wp-scripts یک Facade تمیز روی مجموعه‌ای از ابزارهای پیچیده است که یک API ساده و قابل پیش‌بینی ارائه می‌دهد.

برای توسعه‌دهندگان، تسلط بر wp-scripts به یک مهارت ضروری تبدیل شده است. این ابزار نه تنها در ساخت بلاک کاربرد دارد، بلکه در توسعه افزونه، قالب، و ادغام با CI/CD نیز نقش کلیدی ایفا می‌کند. با گسترش قابلیت‌های گوتنبرگ در نسخه‌های آینده، wp-scripts نیز احتمالاً با قابلیت‌های جدید گسترش خواهد یافت و موقعیت خود را به عنوان استاندارد اکوسیستم مستحکم‌تر خواهد کرد. 🚀

اگر این ابزار را در پروژه‌ای واقعی پیاده‌سازی کرده‌اید، برای ما جالب است بدانید کدام جنبه آن بیشترین ارزش را برایتان ایجاد کرده است. تجربه خودتان را در دیدگاه‌ها بنویسید؛ به‌خصوص اگر پیکربندی سفارشی خلاقانه‌ای در webpack.config.js ساخته‌اید که می‌تواند برای خواننده بعدی مفید باشد.