حزم JavaScript في ووردبريس: اختيار الأدوات وإعلان الاعتماديات بـ @wordpress/scripts

أهلاً بيك يا صديقي المطور في حجر الأساس لمعمارية الفرونت إند في ووردبريس الحديث: حزم JavaScript الرسمية (@wordpress/*) ومنظومة إعلان الاعتماديات (Dependency Extraction Architecture).

لما تبدأ تبني بلوكات أو إضافات معقدة في Gutenberg، أول حاجة بتعملها إنك بتفتح الـ Terminal وتكتب npm install. بتلاقي نفسك بتنزل حزم زي @wordpress/blocks، @wordpress/element، و @wordpress/components. لكن، هل سألت نفسك السؤال الجوهري ده: هو الكود ده لما بيتبنى بـ Webpack، هل React ومكتبات ووردبريس دي بتتحزم كلها جوة ملف الـ JS بتاع إضافتك؟ ولا ووردبريس بيتعامل معاها بطريقة تانية أذكى بمليار مرة؟

المأساة إن لو المطور مش فاهم الفلسفة دي، بيعمل كارثة معمارية اسمها “Bundle Bloat”؛ تلاقيه محزم 3 نسخ مختلفة من React و Redux جوة الإضافة بتاعته، وتفاجأ بظهور رسالة الخطأ المرعبة “Invalid hook call: Hooks can only be called inside the body of a function component” بسبب وجود نسختين من React في نفس الصفحة! الحل السحري اللي بنته ووردبريس هو حزمة @wordpress/scripts وإضافة استخراج الاعتماديات Dependency Extraction Webpack Plugin اللي بتولد ملفات .asset.php تلقائياً. في الدليل الشامل ده، هنفكك منظومة الحزم الرسمية، إزاي تبني بيئة تطوير بدون وجع دماغ، وإزاي تضمن إن ملفاتك حجمها لا يتعدى بضع كيلوبايتات مع دراسة حالة مصرية حقيقية بالعامية المصرية التقنية الأصيلة.

كيف يعمل سحر استخراج الاعتماديات (Dependency Extraction)؟

عشان تفهم النقلة المعمارية دي، تعال نتتبع إيه اللي بيحصل لما تكتب في كودك:

import { useState } from '@wordpress/element';
import { Button } from '@wordpress/components';
import { useSelect } from '@wordpress/data';

1. في مرحلة البناء (Webpack Build Step):

إضافة @wordpress/dependency-extraction-webpack-plugin (المدمجة تلقائياً داخل @wordpress/scripts) بتبص على كودك وتعمل حركتين عبقريتين:

1. استبدال الـ Imports بالمتغيرات العالمية (Externalization):

   بدلاً من أن تقوم بوضع كود حزمة @wordpress/element داخل الملف المجمع، تقوم باستبدالها بالمتغير العالمي المتاح في المتصفح window.wp.element! ونفس الشيء مع window.wp.components و window.wp.data.

2. توليد ملف الأصول التلقائي (index.asset.php):

   تقوم الإضافة بفحص كل الحزم التي استخدمتها، وتنشئ ملف PHP صغير بجوار ملف الجافاسكريبت يحتوي على مصفوفة الاعتماديات الرسمية وتجزئة الـ MD5 كـ رقم إصدار:

   <?php
   return array(
       'dependencies' => array( 'wp-components', 'wp-data', 'wp-element' ),
       'version'      => 'a4b8c9d0e1f234567890'
   );

2. في مرحلة التشغيل على السيرفر (PHP Enqueue Step):

في كود الـ PHP بتاع إضافتك، كل اللي بتعمله هو استدعاء السطر السحري ده:

<?php
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php' );

wp_register_script(
    'my-custom-block-editor',
    plugins_url( 'build/index.js', __FILE__ ),
    $asset_file['dependencies'], // تمرير الاعتماديات آلياً بدون أي كتابة يدوية!
    $asset_file['version']
);
?>

ووردبريس هيقرأ المصفوفة دي، ويتأكد إن سكربتات wp-element و wp-components تم تحميلها في الصفحة قبل السكربت بتاعك، وبدون ما تضطر تحفظ أسماء المقابض (Handles) يدوياً!

خريطة أهم حزم ووردبريس الرسمية (@wordpress/* Ecosystem)

نواة Gutenberg مقسمة لأكثر من 100 حزمة مستقلة منشورة على npm. إليك أهم الحزم التي يجب أن تكون في حقيبتك البرمجية:

1. حزم واجهة المستخدم والبلوكات (Block Development):

• @wordpress/blocks: تسجيل وإدارة البلوكات (registerBlockType, createBlock).
• @wordpress/block-editor: المكونات الحصرية لمحرر المقالات (useBlockProps, RichText, InnerBlocks, InspectorControls).
• @wordpress/components: مكتبة مكونات الواجهة العامة (Button, Modal, PanelBody).
• @wordpress/element: طبقة التوافق مع React (توفر useState, useEffect, createElement).

2. حزم إدارة البيانات والاتصال بالشبكة (Data & Networking):

• @wordpress/data: مخزن البيانات المركزي (useSelect, useDispatch, createReduxStore).
• @wordpress/core-data: إدارة كيانات ووردبريس ومقالاته ومستخدميه.
• @wordpress/api-fetch: بديل fetch الرسمي المدمج؛ يدير الـ Nonces والـ Headers تلقائياً لمخاطبة الـ REST API بأمان.

3. حزم الأدوات والترجمة (Utilities & i18n):

• @wordpress/i18n: دوال التدويل والترجمة (__, _x, _n, sprintf).
• @wordpress/url: معالجة الروابط وإضافة البارامترات (addQueryArgs, getQueryArg).
• @wordpress/hooks: نظام الـ Actions والـ Filters الشهير لووردبريس ولكن في بيئة الجافاسكريبت!

تطبيق عملي كامل: إعداد بيئة التطوير الإنتاجية بـ @wordpress/scripts

1. إعداد ملف package.json القياسي

{
  "name": "enterprise-podcast-player",
  "version": "1.0.0",
  "description": "إضافة مشغل البودكاست المتقدم المبنية بحزم ووردبريس الرسمية.",
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start",
    "lint:js": "wp-scripts lint-js",
    "lint:css": "wp-scripts lint-style",
    "format": "wp-scripts format",
    "test": "wp-scripts test-unit-js"
  },
  "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",
    "@wordpress/api-fetch": "^6.0.0"
  }
}

شرح إعدادات package.json:

• لاحظ أنك لا تحتاج لتثبيت webpack أو babel أو eslint يدوياً! حزمة @wordpress/scripts تأتي مجهزة بجميع أدوات البناء وتكوينات Webpack المثالية المعدة خصيصاً لووردبريس.
• أمر npm start يشغل وضع المراقبة الحية (Watch Mode) مع الـ Source Maps لسرعة التنقيح أثناء التطوير.
• أمر npm run build يقوم بضغط وتصغير الكود (Minification) وتوليد ملفات .asset.php الجاهزة للإنتاج.

2. ملف Webpack المخصص عند الحاجة: webpack.config.js

في 95% من المشاريع، لن تحتاج لإنشاء ملف webpack.config.js؛ لأن الإعدادات الافتراضية تكفي. ولكن إذا أردت إضافة مسارات مخصصة، يمكنك تمديد التكوين الافتراضي بأسلوب هندسي نظيف:

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

module.exports = {
    ...defaultConfig,
    entry: {
        'index': './src/index.js',
        'frontend': './src/frontend.js', // ملف جافاسكريبت مستقل للواجهة الأمامية
    },
};

3. كود تسجيل السكربتات في PHP: plugin-loader.php

<?php
/**
 * التسجيل المعماري الآمن للسكربتات بالاعتماد على ملفات .asset.php
 */
function az_register_podcast_block_assets() {
    $dir = plugin_dir_path( __FILE__ );
    $url = plugin_dir_url( __FILE__ );

    // المسار لملف الأصول المولد آلياً من Webpack
    $asset_path = $dir . 'build/index.asset.php';

    if ( ! file_exists( $asset_path ) ) {
        return; // تجنب الأخطاء في بيئة التطوير قبل أول عملية Build
    }

    $asset_file = include( $asset_path );

    // تسجيل سكربت المحرر مع تمرير الاعتماديات المستخرجة تلقائياً
    wp_register_script(
        'az-podcast-editor-script',
        $url . 'build/index.js',
        $asset_file['dependencies'],
        $asset_file['version']
    );

    // تسجيل ملف التنسيقات
    wp_register_style(
        'az-podcast-editor-style',
        $url . 'build/index.css',
        [ 'wp-components' ],
        $asset_file['version']
    );

    // ربط ملفات الترجمة القياسية
    wp_set_script_translations( 'az-podcast-editor-script', 'az-podcast' );
}
add_action( 'init', 'az_register_podcast_block_assets' );
?>

دراسة حالة واقعية: كارثة منصة البودكاست والبث الصوتي في المعادي والتجمع

الوصايا العشر لإدارة حزم JavaScript والاعتماديات في ووردبريس

1. اعتمد على @wordpress/scripts كأداتك الرسمية: لا تضيع وقتك في ضبط Webpack و Babel من الصفر؛ الأداة الرسمية توفر كل ما تحتاجه بأعلى معايير الأمان.
2. إياك وتحزيم React داخل ملفات الإضافة: دع React تأتي من نواة ووردبريس عبر wp-element لتفادي خطأ Multiple React Instances.
3. استخدم ملفات .asset.php دائماً في الـ PHP: لا تكتب مصفوفة الاعتماديات يدوياً في wp_register_script؛ اعتمد على الملف المولد تلقائياً.
4. استخدم @wordpress/api-fetch بدلاً من fetch أو axios: هي الأداة الوحيدة التي تدير Nonces الأمان و Root URL تلقائياً في ووردبريس.
5. التزم بـ @wordpress/i18n للترجمة: استخدم دوال __() و _x() دائماً لتمكين تعريب واجهات البلوك بسهولة.
6. فعل ESLint و Prettier المدمجين: شغل أمر npm run lint:js قبل رفع الكود للتأكد من خلوه من الأخطاء القياسية.
7. استخدم Source Maps أثناء التطوير فقط: تأكد من تشغيل npm run build قبل نشر الإضافة للإنتاج لضغط الملفات وإزالة الـ Source Maps الثقيلة.
8. لا تعتمد على مكتبات NPM تكرر وظائف النواة: لا تنزل مكتبة أزرار أو نوافذ منبثقة خارجية؛ استخدم @wordpress/components المدمجة.
9. احرص على تطابق إصدارات الحزم: عند تثبيت حزم @wordpress/*، احرص على استخدام إصدارات متوافقة تصدر عن نفس الدورة التحديثية.
10. وثق اعتمادات إضافتك في ملف readme.txt: اذكر إصدار ووردبريس الأدنى المطلوب لضمان توفر كافة الحزم المستخدمة في موقع العميل.

معمارية الأتمتة في خطوط الإنتاج المستمر (CI/CD Pipeline with @wordpress/scripts)

يا صديقي المطور، في البيئات المؤسسية وفرق العمل التي تضم أكثر من مطور، لا يجوز الاعتماد على قيام المطور بتشغيل npm run build على جهازه الشخصي ثم رفع الملفات المضغوطة يدوياً إلى Git! هذا السلوك يسبب ما يسمى بـ “Merge Conflicts” في ملفات الـ JS المبنية، ويؤدي إلى رفع كود غير مختبر قد يكسر بيئة الإنتاج.

الممارسة الهندسية المعتمدة هي بناء خط إنتاج مستمر عبر GitHub Actions يتولى فحص الكود، تشغيل اختبارات Jest، وتجميع الأصول آلياً عند كل Pull Request:

كود عملي: ملف سير عمل GitHub Actions لبناء أصول ووردبريس

# .github/workflows/build-and-test.yml
name: WordPress JS Quality & Build Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  validate-and-build:
    runs-on: ubuntu-latest

    steps:
      - name: فحص واسترجاع كود المستودع
        uses: actions/checkout@v4

      - name: إعداد بيئة Node.js الحديثة
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: تثبيت الاعتماديات بدقة
        run: npm ci

      - name: فحص جودة وتنسيق الكود (Linting)
        run: npm run lint:js

      - name: تشغيل اختبارات الوحدة الآلية (Jest Unit Tests)
        run: npm run test

      - name: بناء حزمة الإنتاج وتوليد ملفات asset.php
        run: npm run build

      - name: التحقق من وجود ملف الأصول index.asset.php
        run: test -f build/index.asset.php || exit 1

هذا الملف يضمن أن أي كود غير متوافق مع معايير ووردبريس، أو يفشل في اختبارات الـ Unit Tests، سيتم رفضه آلياً ولن يُسمح بدمجه في الفرع الرئيسي للمشروع إطلاقاً!

مستقبل الحزم: وحدات الجافاسكريبت الأصلية (ES Modules & Script Modules)

في الإصدارات الحديثة من ووردبريس (ووردبريس 6.5 فما فوق)، بدأت النواة في تبني ثورة جديدة تسمى Script Modules API بالاعتماد على ميزة الـ Import Maps القياسية في المتصفحات الحديثة.

ما هو الفارق بين النظام الكلاسيكي ونظام Script Modules؟

1. النظام الكلاسيكي (Scripts & window.wp.*):

   يتم تحميل الملفات كـ وسوم <script src="..."> عادية، وتقوم كل حزمة بتسجيل نفسها ككائن عالمي داخل window.wp، ثم يقرأ سكربت إضافتك هذه المتغيرات العامة.

2. النظام الثوري الجديد (Script Modules & @wordpress/interactivity):

   يتم تسجيل السكربت كـ type="module" في الـ HTML. ولا يحتاج المتصفح لمتغيرات عالمية، بل يقوم باستيراد الحزم مباشرة عبر متصفح الويب باستخدام عبارات import { store } from "@wordpress/interactivity"; أصلية وسريعة جداً في التحميل غير المتزامن (Asynchronous Module Loading)!

استخدامك لـ @wordpress/scripts يجعلك جاهزاً لهذا المستقبل؛ لأن الحزمة تدعم بناء كل من السكربتات التقليدية للوحة التحكم، ووحدات الـ Script Modules التفاعلية الحديثة للواجهة الأمامية بأمر بناء موحد دون الحاجة لإعادة كتابة بنيتك التحتية.

معمارية تنسيقات الـ SCSS والتصغير التلقائي (PostCSS Pipeline)

ميزة كبرى في @wordpress/scripts يتجاهلها الكثيرون هي دعمها الكامل لـ Sass / SCSS وضغط ملفات الـ CSS آلياً دون الحاجة لأي إضافة خارجية. بمجرد إنشاء ملف style.scss واستيراده داخل index.js:

import './editor.scss';
import './style.scss';

يقوم المحرك بما يلي:

• ترجمة لغة SCSS إلى CSS قياسي.
• تطبيق إضافة Autoprefixer لإضافة بادئات المتصفحات (Vendor Prefixes) لضمان عمل التصميم على متصفحات سفاري وكروم القديمة.
• استخراج ملف index.css الخاص بالمحرر وملف style-index.css الخاص بالواجهة الأمامية في مجلد build بشكل منفصل ومصغر (Minified) تماماً.

تشريح معمارية Babel وملف .browserslistrc في بيئة ووردبريس

يا صديقي المطور، عندما تقوم بكتابة كود JavaScript حديث يحتوي على أحدث صيغ ECMAScript (مثل: Optional Chaining user?.profile?.name، Nullish Coalescing a ?? b، أو مشغلات الـ Async/Await)، كيف تضمن أن هذا الكود سيعمل بكفاءة على متصفحات الشركات والمؤسسات دون أن ينكسر؟

الحل يكمن في حزمة @wordpress/babel-preset-default المدمجة داخل أدوات البناء الرسمية:

1. دور ملف .browserslistrc في ترشيد حجم الكود:

بشكل افتراضي، ترث حزمة @wordpress/scripts قائمة المتصفحات المعتمدة رسمياً لنواة ووردبريس (تغطي أكثر من 95% من المتصفحات النشطة عالمياً). إذا كنت تطور تطبيق إنترانت لشركة حكومية تستخدم إصداراً محدداً من متصفح Edge أو Chrome، يمكنك إضافة ملف .browserslistrc في جذر المشروع:

# .browserslistrc
last 2 Chrome versions
last 2 Firefox versions
last 2 Safari versions
> 1%
not dead

يقوم Babel بقراءة هذا الملف أثناء عملية البناء ويقوم فقط بتحويل الصيغ التي لا تدعمها تلك المتصفحات، مما يوفر تضمين الـ Polyfills الثقيلة غير الضرورية ويقلص حجم ملف الـ JS النهائي بنسبة تصل إلى 25% إضافية.

2. التحويل الدلالي لعناصر الـ JSX:

في بيئة React الكلاسيكية، يترجم Babel كود الـ JSX إلى React.createElement(...). لكن في بيئة ووردبريس، يقوم الإعداد المسبق لـ Babel بتحويل الـ JSX تلقائياً إلى wp.element.createElement(...)! هذا التحويل الذكي هو الجسر الذي يعفي المطور من كتابة استيراد React في كل ملف، ويضمن أن كل عنصر JSX في إضافتك يتم التعامل معه كعنصر ووردبريس أصيل متكامل مع بيئة النواة دون أدنى تضارب.

مراقبة ميزانية الأداء وحجم الحزم البرمجية (Performance Budgeting)

في الشركات الكبرى، يتم ضبط معايير ميزانية الأداء (Performance Budgets) بحيث يُحظر تجاوز حجم ملف الجافاسكريبت النهائي للـ Block حاجز 60 كيلوبايت. إذا تخطت الحزمة هذا الحد، يطلق الـ CI/CD تحذيراً فورياً للمطور لفحص ما إذا كان قد قام باستيراد مكتبة خارجية ضخمة دون داعٍ، مما يضمن بقاء الموقع سريعاً وخفيفاً ويحافظ على تصنيفات Core Web Vitals في أعلى مراتب محركات البحث.