آیا create-block بهترین راه ساخت بلاک سفارشی در وردپرس است؟

آیا create-block بهترین راه ساخت بلاک سفارشی در وردپرس است؟ این ابزار رسمی که توسط تیم هسته گوتنبرگ توسعه یافته، اسکافولدینگ پروژه بلاک را به یک دستور ساده تبدیل کرده و ساختار استانداردی شامل فایل‌های منبع، پیکربندی ساخت و تنظیمات ترجمه ایجاد می‌کند. اما پاسخ به این پرسش که آیا همیشه بهترین انتخاب است، به سناریوی پروژه بستگی دارد. create-block در پروژه‌های استاندارد و تیم‌محور مزیت‌های روشنی دارد، در حالی که برای بلاک‌های بسیار ساده یا معماری‌های خاص، ممکن است لایه‌های اضافی ایجاد کند. این راهنما به بررسی معماری، نقاط قوت، محدودیت‌ها و سناریوهای جایگزین می‌پردازد.

نخستین برخورد با create-block می‌تواند این توهم را ایجاد کند که این ابزار فقط یک تولیدکننده پوشه است. اما وقتی چندین پروژه بلاک را با آن پیش بردیم، مشخص شد که ارزش اصلی آن در تعریف قرارداد ساختار پروژه است، نه در تولید فایل. این راهنما حاصل کار با این ابزار در پروژه‌های تیمی و شخصی است. 🧱

create-block دقیقاً چه کاری انجام می‌دهد؟

create-block یک ابزار خط فرمان است که با دستور npx @wordpress/create-block اجرا می‌شود و یک پروژه کامل بلاک گوتنبرگ را در پوشه جاری ایجاد می‌کند. این ابزار بخشی از اکوسیستم رسمی وردپرس است و توسط همان تیمی نگهداری می‌شود که گوتنبرگ را توسعه می‌دهد.

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

نکته مهم این است که create-block خودش بلاک نمی‌سازد؛ ساختار پروژه را می‌سازد. منطق بلاک، ظاهر آن، و رفتارش همچنان توسط توسعه‌دهنده نوشته می‌شود. این تفکیک، مشابه کاری است که ابزارهایی مانند Create React App در اکوسیستم React انجام می‌دهند. برای آشنایی با مبانی بلاک‌ها، مقاله Gutenberg چیست و چگونه ویرایش محتوای وردپرس را متحول کرد؟ را ببینید.

create-block فایل تولید نمی‌کند؛ قرارداد تولید می‌کند. قراردادی که هر عضو تیم می‌داند کد بلاک کجا قرار می‌گیرد و چگونه ساخته می‌شود.

چرا create-block به سرعت محبوب شد؟

محبوبیت این ابزار نتیجه ترکیب چند عامل فنی و اکوسیستمی است که هر یک به تنهایی می‌توانست آن را مطرح کند، اما ترکیب آن‌ها موقعیت منحصربه‌فردی ایجاد کرده است.

یکپارچگی با ابزارهای رسمی

create-block به‌طور پیش‌فرض پکیج @wordpress/scripts را نصب می‌کند و پیکربندی ساخت را به‌طور کامل آماده تحویل می‌دهد. این بدان معناست که توسعه‌دهنده پس از اجرای یک دستور، به یک زنجیره ساخت کامل مجهز می‌شود که شامل Webpack، Babel، PostCSS، ESLint و Jest است. برای مطالعه درباره این زنجیره، مقاله چرا @wordpress/scripts استاندارد ساخت بلاک در وردپرس شده است؟ را ببینید.

پشتیبانی از block.json به عنوان منبع واحد

در نسخه‌های اخیر گوتنبرگ، فایل block.json به عنوان منبع واحد حقیقت برای تعریف بلاک معرفی شده است. create-block این فایل را در ریشه پروژه ایجاد می‌کند و تمام ارجاعات به اسکریپت‌ها، استایل‌ها و متادیتا را از آن می‌خواند. این رویکرد، ثبت بلاک در PHP را ساده‌تر کرده و از تکرار تعریف‌ها جلوگیری می‌نماید.

انتزاع پیچیدگی‌های بسته‌بندی

ساخت بلاک گوتنبرگ نیازمند درک Webpack، Babel و مکانیزم Dependency Extraction است. create-block این پیچیدگی‌ها را پنهان می‌کند و توسعه‌دهنده را از پیکربندی اولیه معاف می‌سازد. این انتزاع، منحنی یادگیری ساخت بلاک را به‌طور محسوسی کاهش داده است.

هماهنگی با جریان کاری تیمی

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

جدول ۱: عواملی که create-block را به انتخاب پیش‌فرض تبدیل کرد
عامل	اثر عملی
نصب خودکار wp-scripts	حذف پیکربندی ساخت از صفر
تولید block.json	منبع واحد حقیقت برای متادیتا
پشتیبانی از Variant	انتخاب الگوی مناسب برای هر نوع بلاک
ساختار استاندارد	یکسانی پروژه‌ها در تیم
نگهداری رسمی	هماهنگی با تغییرات گوتنبرگ

create-block در برابر ساخت دستی بلاک

برای ارزیابی اینکه آیا create-block بهترین راه است، باید آن را با ساخت دستی مقایسه کرد. ساخت دستی به معنای نوشتن تمام فایل‌ها و پیکربندی‌ها از صفر است.

مزایای create-block

سرعت راه‌اندازی: یک دستور در مقابل چند ساعت پیکربندی.
کاهش خطا: پیکربندی پیش‌فرض تست‌شده و به‌روز است.
هماهنگی نسخه‌ها: وابستگی‌های سازگار با یکدیگر نصب می‌شوند.
پشتیبانی از ترجمه: فایل‌های POT و پیکربندی i18n آماده است.
آماده برای CI/CD: اسکریپت‌های lint و test از ابتدا تعریف شده‌اند.

مزایای ساخت دستی

کنترل کامل بر ساختار: بدون فایل‌های اضافی یا قراردادهای تحمیلی.
حجم کمتر: فقط فایل‌های ضروری پروژه ساخته می‌شوند.
انعطاف در انتخاب ابزار: امکان استفاده از Vite یا esbuild به جای Webpack.
معماری سفارشی: مناسب برای پروژه‌هایی با ساختار غیرمعمول.

در عمل، ساخت دستی تقریباً همیشه به بازتولید همان ساختاری منجر می‌شود که create-block ارائه می‌دهد، اما با صرف زمان بیشتر و ریسک خطای بالاتر. به همین دلیل، برای اکثر پروژه‌ها create-block انتخاب عاقلانه‌تری است. برای مطالعه درباره تفاوت ابزارهای بسته‌بندی، مقاله Webpack یا Vite؛ کدام برای باندل کردن سریع‌تر است؟ را ببینید.

معماری فنی و لایه‌های اسکافولد

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

لایه اول: رابط خط فرمان

رابط CLI نقطه ورود ابزار است. این لایه آرگومان‌های خط فرمان را پارس کرده و آن‌ها را به پارامترهای داخلی تبدیل می‌کند. آرگومان‌هایی مانند --template، --variant، --namespace و --title در این لایه پردازش می‌شوند.

لایه دوم: موتور قالب

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

لایه سوم: مدیریت وابستگی

پس از تولید فایل‌ها، create-block وابستگی‌های npm را نصب می‌کند. این لایه اطمینان می‌دهد که نسخه‌های نصب‌شده با یکدیگر سازگار هستند و با نسخه‌های رسمی وردپرس هماهنگی دارند.

لایه چهارم: قلاب‌های توسعه

create-block از یک سیستم قلاب (Hook) داخلی پشتیبانی می‌کند که به توسعه‌دهندگان امکان می‌دهد فرآیند اسکافولد را سفارشی کنند. این قلاب‌ها در قالب‌های سفارشی و ابزارهای سازمانی کاربرد دارند.

نصب و راه‌اندازی گام‌به‌گام

راه‌اندازی create-block نیازمند Node.js نسخه ۱۸ یا بالاتر است. سه روش اصلی برای اجرا وجود دارد.

روش اول: اجرای مستقیم با npx

npx @wordpress/create-block my-block

این دستور آخرین نسخه create-block را دانلود کرده و یک پروژه با نام my-block در پوشه جاری ایجاد می‌کند. هیچ نصبی روی سیستم انجام نمی‌شود.

روش دوم: نصب سراسری

npm install -g @wordpress/create-block
create-block my-block

این روش برای توسعه‌دهندگانی مناسب است که به‌طور مکرر بلاک می‌سازند و می‌خواهند از دانلود مکرر جلوگیری کنند.

روش سوم: استفاده در پوشه افزونه موجود

npx @wordpress/create-block my-block --no-plugin

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

اجرای اولیه پس از نصب

cd my-block
npm start

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

ساختار پروژه تولیدشده

درک ساختار پروژه‌ای که create-block تولید می‌کند، برای کار حرفه‌ای با آن ضروری است. ساختار پیش‌فرض به شرح زیر است:

my-block/
├── src/
│   ├── block.json
│   ├── edit.js
│   ├── save.js
│   ├── index.js
│   ├── editor.scss
│   ├── style.scss
│   └── view.js
├── build/
├── node_modules/
├── package.json
├── readme.txt
├── .gitignore
├── .editorconfig
└── .eslintrc.js

نقش هر فایل

block.json: متادیتای بلاک، شامل نام، عنوان، آیکون، اتریبیوت‌ها و ارجاعات فایل‌ها.
edit.js: کامپوننت React برای نمایش بلاک در ویرایشگر.
save.js: تابع تولید HTML ذخیره‌شده در دیتابیس.
index.js: نقطه ورود که بلاک را ثبت می‌کند.
editor.scss: استایل مخصوص ویرایشگر.
style.scss: استایل مشترک ویرایشگر و فرانت‌اند.
view.js: اسکریپت فرانت‌اند برای بلاک‌های تعاملی.

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

یکسانی ساختار در پروژه‌های create-block، سرمایه‌ای پنهان است که ارزش آن در بازبینی کد و انتقال دانش بین اعضای تیم آشکار می‌شود.

انواع Variant و کاربرد هر یک

create-block از چندین Variant پشتیبانی می‌کند که هر یک الگوی متفاوتی برای نوع خاصی از بلاک ارائه می‌دهد. انتخاب Variant درست، نیمی از طراحی معماری بلاک است.

Variant پیش‌فرض (static)

این Variant برای بلاک‌هایی مناسب است که محتوای آن‌ها یک بار ذخیره شده و در دیتابیس باقی می‌ماند. خروجی تابع save به صورت HTML ثابت ذخیره می‌شود. مثال: بلاک کارت محتوا با عنوان، تصویر و توضیح ثابت.

Variant داینامیک (dynamic)

در این الگو، تابع save مقدار null برمی‌گرداند و رندر نهایی در سمت سرور توسط یک تابع PHP انجام می‌شود. این رویکرد برای بلاک‌هایی مناسب است که محتوای آن‌ها باید در زمان نمایش تولید شود. مثال: بلاک آخرین نوشته‌ها یا بلاک نمایش قیمت محصول.

Variant تعاملی (interactive)

این Variant در نسخه‌های اخیر اضافه شده و بر پایه Interactivity API بنا شده است. برای بلاک‌هایی مناسب است که در فرانت‌اند تعامل دارند، مانند شمارنده، تب‌بند یا فرم پویا. این الگو به‌طور خودکار ساختار اولیه Interactivity API را تنظیم می‌کند.

جدول ۲: مقایسه Variantهای create-block
Variant	مناسب برای	نقطه قوت
static	محتوای ثابت، کارت، نقل‌قول	سرعت نمایش، سادگی ساختار
dynamic	لیست پویا، قیمت، آخرین مطالب	داده همیشه تازه، وابستگی به Context
interactive	تب‌بند، شمارنده، فرم پویا	تعامل بدون بارگذاری مجدد

تعامل با block.json و منبع واحد حقیقت

یکی از مهم‌ترین تحولات گوتنبرگ در سال‌های اخیر، معرفی block.json به عنوان منبع واحد حقیقت برای متادیتای بلاک است. create-block این رویکرد را به‌طور کامل پیاده‌سازی می‌کند.

ساختار block.json تولیدشده

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "create-block/my-block",
    "version": "0.1.0",
    "title": "My Block",
    "category": "widgets",
    "icon": "smiley",
    "description": "Example block scaffolded with Create Block tool.",
    "example": {},
    "supports": {
        "html": false
    },
    "textdomain": "my-block",
    "editorScript": "file:./index.js",
    "editorStyle": "file:./index.css",
    "style": "file:./style-index.css"
}

ثبت بلاک در PHP

ثبت بلاک در PHP تنها به یک خط کد نیاز دارد:

register_block_type( __DIR__ . '/build' );

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

قالب‌های خارجی و اسکافولد سازمانی

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

ساخت قالب خارجی

یک قالب خارجی می‌تواند یک مخزن Git، یک فایل ZIP یا یک پوشه محلی باشد. با آرگومان --template می‌توان آن را مشخص کرد:

npx @wordpress/create-block my-block --template=./my-company-template

کاربردهای اسکافولد سازمانی

تعریف ساختار پوشه‌های اختصاصی سازمان
افزودن فایل‌های پیکربندی داخلی مانند README و CONTRIBUTING
تنظیم کتابخانه‌های داخلی به عنوان وابستگی پیش‌فرض
اعمال قواعد linting اختصاصی سازمان

این قابلیت create-block را از یک ابزار فردی به یک ابزار سازمانی تبدیل می‌کند. در تیم‌هایی که چندین بلاک موازی توسعه می‌دهند، قالب خارجی تضمین می‌کند که همه بلاک‌ها از ابتدا با استانداردهای سازمان هماهنگ باشند.

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

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

تغییر فایل‌های قالب

فایل‌های قالب create-block در پوشه templates/ داخل پکیج قرار دارند. با کپی این پوشه و تغییر فایل‌های آن، می‌توان قالب سفارشی ایجاد کرد. متغیرهای قالب با فرمت دسترسی به خصوصیات آبجکت تعریف می‌شوند و در زمان رندر جایگزین می‌گردند.

افزودن فایل جدید به قالب

می‌توان فایل‌های جدیدی به قالب اضافه کرد که در ساختار پیش‌فرض وجود ندارند. برای مثال، افزودن فایل tests/ با تست‌های اولیه، یا افزودن فایل storybook/ برای مستندسازی بصری کامپوننت‌ها. برای مطالعه درباره استانداردهای کد، مقاله استانداردهای کدنویسی وردپرس چیست را ببینید.

ادغام با wp-scripts و wp-env

create-block به‌طور طبیعی با دو ابزار کلیدی اکوسیستم وردپرس ادغام می‌شود: wp-scripts و wp-env.

ادغام با wp-scripts

create-block به‌طور خودکار @wordpress/scripts را به عنوان وابستگی توسعه نصب می‌کند و اسکریپت‌های لازم را در package.json تعریف می‌نماید. این بدان معناست که توسعه‌دهنده بلافاصله پس از اسکافولد، به دستوراتی مانند npm start، npm run build، npm run lint:js و npm run test:unit دسترسی دارد.

ادغام با wp-env

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

مثال پیکربندی ترکیبی

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

افزودن بلاک دوم به پروژه موجود

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

npx @wordpress/create-block my-second-block --no-plugin

اجرای این دستور در پوشه پروژه فعلی، فایل‌های بلاک جدید را در پوشه src/ ایجاد می‌کند. سپس باید در فایل package.json، نقطه ورود دوم را به Webpack معرفی کنید. wp-scripts به‌طور خودکار هر فایل index.js در پوشه src/ را به عنوان نقطه ورود می‌شناسد، بنابراین نیازی به پیکربندی اضافی نیست.

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

جایگزین‌های create-block و سناریوهای مناسب آن‌ها

create-block تنها راه ساخت بلاک نیست. در برخی سناریوها، رویکردهای جایگزین منطقی‌تر هستند.

۱. بلاک‌های بسیار ساده

اگر بلاکی فقط یک یا دو اتریبیوت دارد و از Inner Blocks استفاده نمی‌کند، ممکن است ساخت دستی سریع‌تر باشد. create-block فایل‌های متعددی تولید می‌کند که در چنین بلاکی غیرضروری هستند.

۲. معماری‌های غیرمعمول

در پروژه‌هایی که ساختار فایل‌ها با قرارداد create-block هماهنگ نیست — برای مثال، پروژه‌هایی که از monorepo استفاده می‌کنند — ساخت دستی انعطاف بیشتری می‌دهد.

۳. استفاده از Vite یا esbuild

create-block بر پایه Webpack ساخته شده است. اگر تیم تصمیم گرفته باشد از Vite یا esbuild استفاده کند، باید پیکربندی سفارشی بنویسد یا از قالب‌های خارجی بهره ببرد.

۴. بلاک‌های مبتنی بر Block Bindings

اگر بلاک بیشتر به عنوان یک نمایش‌دهنده داده عمل می‌کند، ممکن است نیازی به بلاک سفارشی نباشد. Block Bindings API می‌تواند بلاک‌های هسته را به داده‌های خارجی متصل کند. برای مطالعه درباره آن، مقاله Block Bindings API در وردپرس چیست و چطور داده‌ها را به بلاک متصل می‌کند؟ را ببینید.

۵. تغییرات جزئی بلاک‌های موجود

اگر هدف ایجاد یک نسخه از پیش پیکربندی‌شده از یک بلاک موجود است، Block Variations راه‌حل سبک‌تری است. برای مطالعه درباره آن، مقاله Block Variations در وردپرس چطور بلاک‌ها را بدون کدنویسی تغییر می‌دهد؟ را ببینید.

محدودیت‌ها و چالش‌های پنهان

با وجود مزایای فراوان، create-block محدودیت‌هایی دارد که در ارزیابی نهایی باید در نظر گرفته شوند.

وابستگی به Webpack

create-block به‌طور ذاتی به Webpack وابسته است. این وابستگی در پروژه‌های بزرگ که زمان Build اهمیت دارد، می‌تواند محدودکننده باشد. ابزارهای مدرن مانند Vite زمان ساخت را به‌طور محسوسی کاهش می‌دهند.

حجم فایل‌های تولیدشده

پروژه create-block شامل فایل‌های متعددی است که در پروژه‌های کوچک اضافی به نظر می‌رسند. برای بلاک‌های بسیار ساده، این حجم می‌تواند آزاردهنده باشد.

الزامات Node.js

create-block نیازمند Node.js نسخه ۱۸ یا بالاتر است. در محیط‌هایی که این نسخه در دسترس نیست، ابزار کار نمی‌کند. این محدودیت در سرورهای قدیمی می‌تواند مسئله‌ساز شود.

منحنی یادگیری React

بلاک‌های گوتنبرگ با React نوشته می‌شوند. اگرچه create-block ساختار را آماده می‌کند، توسعه‌دهنده همچنان باید React و مفاهیمی مانند State، Props و Hooks را بشناسد. برای مطالعه درباره TypeScript، مقاله تایپ اسکریپت از صفر: چرا جاوااسکریپت تنها کافی نیست؟ را ببینید.

پنهان کردن پیچیدگی‌های مفید

انتزاع create-block باعث می‌شود توسعه‌دهنده با مکانیزم‌های زیرین مانند Dependency Extraction، Code Splitting و Tree Shaking آشنا نشود. این ناآگاهی در پروژه‌های پیچیده می‌تواند به مشکلات عملکردی منجر شود.

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

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

در استفاده از create-block، برخی خطاها رایج هستند. در ادامه، مهم‌ترین آن‌ها بررسی می‌شود.

خطای «npx: command not found»

این خطا نشان می‌دهد npm و Node.js به درستی نصب نشده‌اند. با دستور node -v و npm -v نصب را بررسی کنید.

خطای «EACCES: permission denied»

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

sudo chown -R $(whoami) ~/.npm

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

اگر پس از اسکافولد، وابستگی‌ها به درستی نصب نشده باشند، این خطا رخ می‌دهد. راه‌حل:

rm -rf node_modules package-lock.json
npm install

خطای «Block validation failed»

این خطا زمانی رخ می‌دهد که HTML تولیدشده توسط تابع save با HTML ذخیره‌شده در دیتابیس مطابقت نداشته باشد. راه‌حل، بررسی دقیق تغییرات در save.js و استفاده از تابع useBlockProps.save است.

خطای Build پس از افزودن بلاک دوم

اگر بلاک دوم به درستی Build نشود، احتمالاً نقطه ورود در package.json تعریف نشده است. wp-scripts به‌طور خودکار فایل‌های src/**/index.js را شناسایی می‌کند، اما در ساختارهای پیچیده ممکن است نیاز به تعریف دستی داشته باشد. برای مطالعه درباره مدیریت پکیج، مقاله npm یا Yarn؛ کدام برای مدیریت پکیج سریع‌تر است؟ را ببینید.

پرسش‌های پرتکرار درباره create-block

create-block چیست و چه تفاوتی با ساخت دستی بلاک دارد؟

create-block یک ابزار خط فرمان رسمی است که ساختار استاندارد پروژه بلاک گوتنبرگ را ایجاد می‌کند. برخلاف ساخت دستی، این ابزار پیکربندی ساخت، فایل‌های ترجمه، و تنظیمات lint را به‌طور خودکار آماده می‌کند و زمان راه‌اندازی را از چند ساعت به چند دقیقه کاهش می‌دهد.

آیا create-block برای همه پروژه‌ها مناسب است؟

خیر، برای اکثر پروژه‌ها مناسب است اما در سه سناریو جایگزین‌ها بهتر هستند: بلاک‌های بسیار ساده، معماری‌های غیرمعمول، و پروژه‌هایی که از Vite یا esbuild استفاده می‌کنند.

چگونه بلاک دوم را به پروژه create-block اضافه کنم؟

با اجرای npx @wordpress/create-block my-second-block --no-plugin در پوشه پروژه، فایل‌های بلاک جدید در src/ ایجاد می‌شوند. wp-scripts به‌طور خودکار آن‌ها را به عنوان نقطه ورود دوم شناسایی می‌کند.

آیا می‌توانم قالب اسکافولد را سفارشی کنم؟

بله، از طریق آرگومان --template می‌توانید یک قالب خارجی (پوشه محلی، مخزن Git، یا فایل ZIP) تعیین کنید. این قابلیت برای استانداردسازی بلاک‌ها در سطح سازمان کاربرد دارد.

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

بله، با افزودن آرگومان --variant=dynamic یا استفاده از قالب‌های خارجی می‌توان پروژه‌های TypeScript ساخت. wp-scripts نیز از TypeScript به صورت بومی پشتیبانی می‌کند.

چرا پس از Build، بلاک در ویرایشگر کار نمی‌کند؟

دلایل متعددی می‌تواند داشته باشد: ثبت نشدن بلاک در PHP، نبود فایل block.json در پوشه build/، یا ناسازگاری نسخه apiVersion. با بررسی لاگ‌های مرورگر و فعال‌سازی SCRIPT_DEBUG می‌توان علت را پیدا کرد.

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

بله، اما معمولاً create-block فقط یک بار برای اسکافولد پروژه اجرا می‌شود. در CI/CD، دستورات wp-scripts مانند build، lint و test اجرا می‌شوند. برای مطالعه درباره آن، مقاله CI/CD برای پروژه‌های وردپرسی چگونه پیاده‌سازی می‌شود؟ را ببینید.

تفاوت create-block و Block Variations چیست؟

create-block برای ساخت بلاک جدید طراحی شده، در حالی که Block Variations برای ایجاد نسخه‌های از پیش پیکربندی‌شده از بلاک‌های موجود استفاده می‌شود. اگر هدف فقط تغییر تنظیمات اولیه یک بلاک هسته است، Variations راه‌حل سبک‌تری است.

نگاهی به لایه‌های زیرین

از منظر مهندسی نرم‌افزار، create-block یک پیاده‌سازی از الگوی Scaffolding است. این الگو در اکوسیستم‌های مختلف نرم‌افزاری رایج است و هدف آن، کاهش زمان راه‌اندازی پروژه‌های جدید با تولید ساختار استاندارد است.

در سطح معماری، create-block از الگوی Template Method استفاده می‌کند. ساختار کلی فرآیند اسکافولد ثابت است — پارس آرگومان‌ها، انتخاب قالب، رندر فایل‌ها، نصب وابستگی‌ها — اما جزئیات هر گام از طریق قالب‌ها و قلاب‌ها قابل تغییر است. این جداسازی، تعادل مناسبی بین یکسانی و انعطاف‌پذیری ایجاد می‌کند.

یکی از جنبه‌های پیشرفته، نحوه تعامل create-block با سیستم Dependency Extraction است. فایل‌های تولیدشده شامل importهایی از پکیج‌های @wordpress/* هستند. wp-scripts در زمان Build، این importها را به متغیرهای سراسری Map می‌کند و یک فایل .asset.php تولید می‌نماید که وابستگی‌ها را به وردپرس اعلام می‌کند. این مکانیزم از بارگذاری دوباره پکیج‌هایی که وردپرس از قبل بارگذاری کرده، جلوگیری می‌کند.

در سطح عمیق‌تر، create-block از یک سیستم قلاب داخلی (Internal Hook System) پشتیبانی می‌کند. این قلاب‌ها در مراحل مختلف اسکافولد اجرا می‌شوند و به توسعه‌دهندگان قالب‌های خارجی اجازه می‌دهند فرآیند را سفارشی کنند. برای مثال، می‌توان پس از رندر فایل‌ها، یک مرحله اضافی برای تولید مستندات یا اجرای اسکریپت‌های سفارشی تعریف کرد.

برای مهندسان ارشد، درک رابطه create-block با معماری FSE اهمیت دارد. بلاک‌های ساخته‌شده با create-block می‌توانند در قالب‌های بلاکی و ویرایشگر سایت استفاده شوند، اما رعایت استانداردهای FSE نیازمند آگاهی از theme.json و Global Styles است. برای مطالعه درباره آن، مقاله چرا Full Site Editing در وردپرس آن‌قدر که فکر می‌کنید ساده نیست؟ را ببینید.

در سطح عملکرد، بلاک‌های تولیدشده با create-block از تکنیک‌هایی مانند Code Splitting و Lazy Loading بهره می‌برند. با استفاده از import() داینامیک، می‌توان بخش‌های سنگین بلاک را فقط در زمان نیاز بارگذاری کرد. این تکنیک به‌ویژه در بلاک‌هایی که از کتابخانه‌های خارجی مانند نمودارها یا ویرایشگرهای متن غنی استفاده می‌کنند، حیاتی است. برای مطالعه درباره بهینه‌سازی، مقاله بهینه سازی جاوااسکریپت را ببینید.

در آینده، انتظار می‌رود که create-block با قابلیت‌هایی مانند پشتیبانی از Vite به عنوان Bundler جایگزین، ادغام عمیق‌تر با Interactivity API، و تولید خودکار تست‌های E2E گسترش یابد. روند حرکت اکوسیستم JavaScript به سمت ابزارهای سریع‌تر، احتمالاً بر انتخاب‌های پیش‌فرض create-block نیز تأثیر خواهد گذاشت.

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

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

اما پاسخ به پرسش اصلی این راهنما — آیا create-block بهترین راه است؟ — بستگی به زمینه دارد. برای اکثر پروژه‌ها، پاسخ مثبت است. برای بلاک‌های بسیار ساده، معماری‌های غیرمعمول، و پروژه‌هایی که ابزارهای بسته‌بندی جایگزین را ترجیح می‌دهند، رویکردهای دیگری ممکن است مناسب‌تر باشند.

نکته مهم این است که create-block یک ابزار است، نه یک دکترین. تسلط بر آن به معنای درک نقاط قوت و محدودیت‌هایش است، نه استفاده کورکورانه از آن در هر پروژه. توسعه‌دهندگانی که این تعادل را درک کنند، می‌توانند بهترین تصمیم را برای هر پروژه بگیرند. 🚀

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