شرح حزمة @wordpress/scripts: التطوير والبناء وفحص ملفات الإصدار

أهلاً بيك يا صديقي المطور في الأداة السحرية التي حولت حياة مطوري ووردبريس من جحيم إعدادات الـ Webpack وتضارب إصدارات Babel، إلى راحة البال المطلقة وزر واحد ينهي كل شيء: حزمة @wordpress/scripts الرسمية.

لو كنت بتشتغل في تطوير الواجهات قبل 2018، فأنت أكيد فاكر المعاناة الأزلية لما كنت تحب تبدأ مشروع جديد: تقضي يومين كاملين تنزل في حزم webpack، و webpack-cli، و babel-loader، و eslint، و prettier، وتكتب ملف webpack.config.js فيه 300 سطر، وأول ما تعمل npm update تلاقي حزمة ضربت وكل التكوينات انهارت في وشك!

فريق نواة ووردبريس أدرك المعضلة دي وقال: “المطور المفروض يركز في برمجة البلوك وتجربة المستخدم، مش في صيانة أدوات البناء!”. ومن هنا اتولدت حزمة @wordpress/scripts كمنظومة أدوات متكاملة بتعتمد على فلسفة “Zero-Configuration Tooling” (أدوات بدون إعدادات يدوية). بضغطة زر واحدة وأمر بسيط في Terminal، الحزمة دي بتوفر لك: وضع التطوير والمراقبة الحية (Watch Mode)، التجميع والضغط للإنتاج (Build)، الفحص اللغوي وتنسيق الكود (Linting & Formatting)، تشغيل اختبارات الوحدة الآلية (Jest Unit Testing)، وحتى تجهيز ملف الـ ZIP النهائي المضغوط الصالح للنشر على متجر ووردبريس الرسمي بـ plugin-zip! في الدليل الشامل ده، هنفكك كل أوامر الحزمة، إزاي تخصصها بأمان، ودراسة حالة حقيقية لمصانع أثاث بدمياط بالعامية المصرية التقنية الأصيلة.

الترسانة الكاملة: الأوامر الرسمية لحزمة @wordpress/scripts

حزمة @wordpress/scripts توفر مجموعة من الأوامر الثورية التي يمكنك استدعاؤها عبر قسم scripts في ملف package.json:

1. أوامر التطوير والبناء (Core Lifecycle Commands):

• wp-scripts start:

  يشغل خادم التطوير ووضع المراقبة الحية (Watch Mode). مع كل حفظ لأي ملف في مجلد src، يقوم بإعادة البناء في أجزاء من الثانية مع توليد Source Maps لتسهيل التنقيح.

• wp-scripts build:

  أمر الإنتاج النهائي؛ يقوم بضغط وتصغير كود الـ JS والـ CSS، وإزالة تعليقات المطورين، وحذف خرائط المصدر الحساسة، وتوليد ملفات .asset.php برقم تجزئة (Hash) مشفر.

2. أوامر جودة الكود وتنسيقه (Code Quality & Formatting):

• wp-scripts lint-js & wp-scripts lint-style:

  فحص ملفات الجافاسكريبت والـ CSS وفق معايير الكود الرسمية المعتمدة لمجتمع ووردبريس العالمي، ورصد الأخطاء الشائعة وحقول الـ a11y المفقودة.

• wp-scripts format:

  الأمر السحري الذي يصلح كافة المسافات والأسطر تلقائياً عبر Prettier المجهز بأسلوب ووردبريس المعتمد.

3. أوامر الاختبارات الآلية (Automated Testing Commands):

• wp-scripts test-unit-js:

  تشغيل اختبارات الوحدة باستخدام محرك Jest المجهز ببيئة محاكاة ووردبريس الرسمية (@wordpress/jest-preset-default).

• wp-scripts test-e2e:

  تشغيل اختبارات التكامل الشاملة (End-to-End Tests) باستخدام متصفح Playwright أو Puppeteer لمحاكاة ضغطات المحرر في لوحة التحكم الحقيقية.

4. أمر التجهيز والنشر النهائي (Packaging):

• wp-scripts plugin-zip:

  يقوم بإنشاء ملف أرشيف مضغوط جاهز للتثبيت .zip باسم إضافتك، مع استبعاد مجلد node_modules، ومجلد src، وملفات الاختبار، وملفات التكوين، وتضمين ملفات الإنتاج فقط!

تطبيق عملي كامل: إعداد ملف package.json الشامل والتكوينات المخصصة

1. ملف package.json المحترف لبيئة الإنتاج

{
  "name": "enterprise-furniture-catalog",
  "version": "1.0.0",
  "description": "إضافة كتالوج مصانع أثاث دمياط المعتمدة على محرر Gutenberg.",
  "author": "Mohamed Abozaid",
  "license": "GPL-2.0-or-later",
  "main": "build/index.js",
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:js": "wp-scripts lint-js",
    "lint:js:fix": "wp-scripts lint-js --fix",
    "lint:css": "wp-scripts lint-style",
    "format": "wp-scripts format",
    "test": "wp-scripts test-unit-js",
    "test:watch": "wp-scripts test-unit-js --watch",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip"
  },
  "devDependencies": {
    "@wordpress/scripts": "^27.0.0"
  },
  "dependencies": {
    "@wordpress/block-editor": "^12.0.0",
    "@wordpress/blocks": "^12.0.0",
    "@wordpress/components": "^25.0.0",
    "@wordpress/data": "^9.0.0",
    "@wordpress/element": "^5.0.0",
    "@wordpress/i18n": "^4.0.0"
  }
}

2. تمديد تكوين الـ Linter: ملف .eslintrc.js

إذا أردت تخصيص بعض القواعد الصارمة لفريقك (مثل حظر استخدام console.log في كود التطوير)، يمكنك إنشاء ملف .eslintrc.js خفيف يمدد إعدادات ووردبريس الرسمية:

/**
 * تخصيص قواعد ESLint مع الحفاظ على معايير ووردبريس
 * File: .eslintrc.js
 */
module.exports = {
    extends: [ 'plugin:@wordpress/eslint-plugin/recommended' ],
    rules: {
        'no-console': [ 'warn', { allow: [ 'warn', 'error' ] } ],
        'react-hooks/exhaustive-deps': 'error', // إلزام المطورين بتحديد مصفوفة الاعتماديات بدقة
    },
};

3. تخصيص قواعد التنسيق التلقائي: ملف .prettierrc.js

/**
 * تخصيص Prettier لتطابق أسلوب كتابة كود ووردبريس الرسمي
 * File: .prettierrc.js
 */
const defaultConfig = require( '@wordpress/prettier-config' );

module.exports = {
    ...defaultConfig,
    singleQuote: true,
    trailingComma: 'es5',
};

تشريح أمر wp-scripts plugin-zip: كيف تحمي إصداراتك من تسريب الملفات؟

من أكبر الأخطاء التي يقع فيها المطورون عندما ينتهون من برمجة إضافتهم هي الذهاب لمجلد الإضافة بالماوس، والضغط بالزر الأيمن واختيار: “Compress / ضغط إلى ZIP”!

لماذا يُعتبر الضغط اليدوي جريمة هندسية؟

• يقوم بضغط مجلد node_modules الذي يحتوي أحياناً على أكثر من 40,000 ملف و 400 ميجابايت من ملفات بيئة التطوير غير المفيدة للمستخدم!
• يرفع ملفات الكود المصدري غير المجمعة في مجلد src/، وملفات الـ .git السرية، ومفاتيح البيئة التجريبية.
• يتسبب في فشل تثبيت الإضافة على خوادم الاستضافة المشتركة بسبب تجاوز حدود الـ Upload Limit المسموحة في PHP.

الحل مع wp-scripts plugin-zip:

عند تشغيل npm run plugin-zip، تبحث الأداة تلقائياً عن ملف .filesignore أو تعتمد على قائمة الاستثناءات الافتراضية الذكية، وتقوم بنسخ:

1. الملف الرئيسي للإضافة (مثل my-plugin.php).
2. مجلد build/ الذي يحتوي على ملفات الإنتاج المجمعة وملفات .asset.php فقط.
3. ملف readme.txt وملفات التراخيص.

وتتجاهل تماماً كل ما دون ذلك، لينتج ملف ZIP نظيف ومحكم لا يتعدى حجمه بضع مئات من الكيلوبايتات!

دراسة حالة واقعية: أزمة بوابة مصانع أثاث دمياط وسقوط سيرفر الاستضافة المشتركة

الوصايا العشر للعمل بحزمة @wordpress/scripts

1. اعتمد على wp-scripts build دائماً في الإنتاج: لا ترفع كوداً تم بناؤه بـ start على السيرفر الحي أبداً.
2. استخدم wp-scripts plugin-zip لضغط الإصدارات: هو الضمان الوحيد لمنع تسريب ملفات node_modules والـ Git إلى ملف التوزيع.
3. فعل أوامر التدقيق (Linting) قبل كل Commit: اجعل تشغيل npm run lint:js طقساً يومياً للحفاظ على جودة الكود.
4. استفد من npm run format لإراحة فريقك: دع Prettier يتولى ضبط المسافات والفواصل بضغطة زر واحدة بدلاً من الجدال حول التنسيق.
5. حدث حزمك دورياً بـ packages-update: استخدم wp-scripts packages-update للتأكد من مواكبة أحدث إصلاحات ووردبريس الأمنية.
6. احفظ ملف package-lock.json في Git: لضمان أن كل المطورين وخوادم الـ CI/CD يقومون بتثبيت نفس الإصدارات الدقيقة للحزم.
7. لا تعدل ملفات مجلد build يدوياً: أي تعديل داخل build/ سيتم مسحه في عملية البناء التالية؛ التعديل مكانه src/ دائماً.
8. اكتب اختبارات وحدة للمكونات الحساسة: شغل npm test للتأكد من أن حساباتك المالية والمنطقية تعمل قبل إرسال الكود للعميل.
9. تأكد من وجود ملف .asset.php بعد البناء: احرص دائماً على التحقق من أن ملف الأصول قد تم توليده بنجاح قبل رفعه للسيرفر.
10. وثق أوامر الـ NPM في الـ Readme لفريقك: اشرح للمطورين الجدد في شركتك كيفية تشغيل npm start و npm run build للبدء فوراً دون عناء.

معمارية الاختبارات الشاملة (End-to-End Testing with Playwright)

يا صديقي المطور، اختبارات الوحدة (Unit Tests) ممتازة لفحص الدوال الحسابية والـ Reducers، لكنها لا تضمن أن البلوك يعمل بشكل حقيقي داخل متصفح ووردبريس الفعلي! هل زر الإدراج يفتح بنافذة منبثقة؟ هل السحب والإفلات يضع البلوك في مكانه الدقيق؟ هل الضغط على “نشر” يحفظ البيانات في قاعدة بيانات MySQL الحقيقية؟

هنا يأتي دور اختبارات الـ End-to-End (E2E Testing) المدمجة في @wordpress/scripts عبر أمر wp-scripts test-e2e بالاعتماد على محرك Playwright فائق التطور.

كود عملي متكامل: اختبار E2E لإدراج وتعديل البلوك في بيئة ووردبريس حقيقية

/**
 * فحص شامل لدورة حياة البلوك داخل متصفح حقيقي عبر Playwright
 * File: test/e2e/furniture-block.spec.js
 */
import { test, expect } from '@wordpress/e2e-test-utils-playwright';

test.describe( 'فحص سلامة بلوك كتالوج الأثاث (enterprise/furniture-catalog)', () => {
    test.beforeEach( async ( { admin } ) => {
        // إنشاء مقال جديد وتسجيل الدخول كمدير نظام تلقائياً
        await admin.createNewPost();
    } );

    test( 'يجب أن يدرج البلوك بنجاح ويسمح بتعديل مواصفات الخشب في الشريط الجانبي', async ( { editor, page } ) => {
        // 1. إدراج البلوك عبر محرك البحث في المحرر
        await editor.insertBlock( { name: 'enterprise/furniture-catalog' } );

        // 2. التحقق من ظهور البلوك على الشاشة
        const blockLocator = page.locator( '[data-type="enterprise/furniture-catalog"]' );
        await expect( blockLocator ).toBeVisible();

        // 3. كتابة عنوان الكتالوج داخل حقل RichText
        await editor.canvas.locator( '.az-furniture-title' ).fill( 'صالون كلاسيكي مذهب - خشب زان أحمر' );

        // 4. فتح شريط الإعدادات الجانبي وتعديل خيار نوع الخشب
        await page.click( 'button[aria-label="إعدادات البلوك"]' );
        await page.selectOption( 'select[label="نوع الخشب"]', 'beech_wood' );

        // 5. الضغط على زر نشر المقال الرسمي في ووردبريس
        await editor.publishPost();

        // 6. فتح المقال المنشور في الواجهة الأمامية والتأكد من مطابقة كود الـ HTML
        const publishedUrl = await editor.getPublishedPostUrl();
        await page.goto( publishedUrl );

        const frontendHeading = page.locator( '.az-furniture-card h3' );
        await expect( frontendHeading ).toHaveText( 'صالون كلاسيكي مذهب - خشب زان أحمر' );
    } );
} );

القوة الهندسية لاختبارات E2E:
هذا الاختبار يقوم بتشغيل متصفح Chromium في الخلفية، ويفتح لوحة تحكم ووردبريس، ويكتب المقال، وينشره، ويزور الموقع كزائر عادي ويتأكد من أن التصميم يعمل بنسبة 100%! هذا هو أعلى مستوى من الجودة البرمجية التي يمكن أن تقدمها لعملائك في المشاريع الكبرى.

فحص التراخيص والامتثال القانوني: أمر wp-scripts check-licenses

ووردبريس مبني على رخصة GPLv2 (أو أحدث) الحرة. عندما تقوم بتطوير إضافة تجارية أو إضافة ستنشرها على دليل ووردبريس الرسمي (WordPress.org Plugin Directory)، فأنت ملزم قانونياً بالتأكد من أن كافة الحزم والمكتبات التي قمت بتثبيتها عبر npm تتوافق مع ترخيص الـ GPL ولا تحتوي على رخص احتكارية مقيدة (Proprietary / Non-commercial Licenses).

توفر الحزمة أمراً رقابياً شديد الذكاء:

npm run wp-scripts check-licenses -- --gpl2

يقوم هذا الأمر بفحص شجرة التبعيات في مجلد node_modules بالكامل، ويطبع لك تقريراً تفصيلياً برخص كافة المكتبات الفرعية، ويطلق إنذاراً أحمر إذا كانت هناك أي مكتبة تنتهك ترخيص ووردبريس، مما يحميك ويحمي شركتك من أي نزاعات قضائية أو رفض لاعتماد إضافتك في المتجر العالمي.

معمارية الـ Monorepo وإدارة الحزم المتعددة (Workspaces Integration)

في الشركات الكبرى التي تمتلك حزمة تضم 10 إضافات مختلفة أو قوالب متعددة تعتمد على نفس نظام التصميم، فإن إنشاء مستودع منفصل لكل إضافة يسبب تكراراً شاقاً لملفات الـ package.json وأدوات البناء.

باستخدام ميزة npm Workspaces مع @wordpress/scripts، يمكنك إنشاء مستودع موحد (Monorepo):

my-enterprise-suite/
├── package.json (يحتوي على: "workspaces": ["packages/*", "plugins/*"])
├── node_modules/ (نسخة موحدة لكافة المشاريع)
├── plugins/
│   ├── furniture-core/
│   │   ├── package.json
│   │   └── src/
│   └── furniture-shipping/
│       ├── package.json
│       └── src/
└── packages/
    └── design-system/
        ├── package.json
        └── src/

بتشغيل أمر واحد في جذر المشروع: npm run build --workspaces، تتولى @wordpress/scripts تجميع كافة الإضافات والبلوكات بالتوازي في وقت قياسي وبأقل استهلاك لمساحة التخزين على القرص الصلب.

مراقبة أحجام الحزم برمجياً: دمج Webpack Bundle Analyzer في بيئات CI/CD

يا صديقي العزيز، أكبر مصيبة ممكن تواجهك في مشاريع ووردبريس الضخمة هي ما نسميه “تسلل التبعيات الصامت” (Silent Dependency Creep). المطور يكتب كود جميل وسريع، وفجأة يقرر يعمل npm install moment عشان ينسق تاريخ بسيط في بلوك واحد، أو يجلب مكتبة أيقونات كاملة حجمها 4 ميجابايت عشان يستخدم أيقونة سهم واحدة! لو ما عندكش رادار بيكتشف الكارثة دي في مسار الـ CI/CD (Continuous Integration)، هتلاقي حجم حزمة الجافا سكريبت الخاصة بالقالب أو الإضافة تضخم بشكل مرعب، والعميل في مصر يشتكي من بطء المتجر وتحميل الصفحة على شبكات الموبايل الضعيفة.

عشان نمنع الجريمة دي قبل ما توصل للإنتاج، بنستخدم حزمة webpack-bundle-analyzer مع دمج فحص تلقائي في GitHub Actions أو GitLab CI يتحقق من ميزانية الأداء (Performance Budget). إليك الكود الاحترافي لتفعيل المحلل في ملف webpack.config.js المخصص بدون ما يبطئ بيئة التطوير اليومية:

// webpack.config.js
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
const { BundleAnalyzerPlugin } = require( 'webpack-bundle-analyzer' );

module.exports = {
	...defaultConfig,
	plugins: [
		...defaultConfig.plugins,
		// بنشغل المحلل فقط لما نمرر متغير بيئة محدد ANALYZE=true في التيرمينال
		process.env.ANALYZE === 'true' &&
			new BundleAnalyzerPlugin( {
				analyzerMode: 'static',
				reportFilename: 'bundle-report.html',
				openAnalyzer: false, // مش عايزين نفتح المتصفح أوتوماتيك في سيرفر الـ CI
				generateStatsFile: true,
				statsFilename: 'bundle-stats.json',
			} ),
	].filter( Boolean ), // تنظيف القيم الزائفة (falsy values) بأمان تام
};

بمجرد ما تضيف الإعداد ده، تقدر تضيف سكريبت مخصص في package.json: "analyze": "ANALYZE=true wp-scripts build". لما تشغل الأمر ده، هيتولد ملف تقرير HTML تفاعلي يوريك شجرة الحزم بالمليمتر، مين المكتبة اللي واخدة أكبر مساحة، ومين الملفات المكررة اللي محتاجة معالجة عبر externals أو Dynamic Imports.

قواعد ذهبية لضمان عمل Tree-Shaking بكفاءة 100%

كتير من المطورين يعتقدوا إن Webpack بيعمل Tree-Shaking تلقائياً بمجرد تشغيل نمط الإنتاج (Production Mode)، لكن الواقع الصادم إنك لو استوردت دالة بطريقة خاطئة من مكتبة بتدعم الـ CommonJS فقط أو فيها Side Effects غير معلنة، المترجم هيحزم المكتبة كلها بالكامل! عشان تضمن إن الحزم تطلع رشيقة وخفيفة:

• تأكد من تفعيل “sideEffects”: false: في ملف package.json الخاص بمشروعك أو الإضافة، إعلان "sideEffects": false بيعطي Webpack الضوء الأخضر لإسقاط أي ملف أو دالة مش مستخدمة دون خوف. لو عندك ملفات CSS بيتم استيرادها، حددها في المصفوفة: "sideEffects": ["*.css", "*.scss"].
• الاعتماد الكامل على ES Modules: تجنب نهائياً استخدام require() داخل ملفات كود الواجهة الأمامية، واستخدم دائماً import { specificFunction } from 'package'. المترجم لا يستطيع تحليل الـ CommonJS استاتيكياً بنفس كفاءة الـ ESM.
• فصل كود لوحة التحكم عن كود الواجهة: لا تجمع كود الـ Edit الخاص ببلوكات جوتنبرج مع كود الـ Frontend Scripts في ملف إدخال واحد (Entry Point). كود التحرير بيحتاج مكتبات UI ضخمة مثل @wordpress/components مش مفروض الزائر العادي يحمل منها بايت واحد في المتصفح!