CSS الأصلي

يوضح هذا الدليل كيفية استخدام معالجة CSS الأصلية في webpack عبر experiments.css.

البدء

فعّل دعم CSS الأصلي في إعدادات webpack:

webpack.config.js

export default {
  experiments: {
    css: true,
  },
};

مع تفعيل هذا الخيار، يستطيع webpack معالجة CSS دون إضافة css-loader و mini-css-extract-plugin في المسار الأساسي.

استيراد CSS

بعد تفعيل التجربة، استورد ملفات .css مباشرة من JavaScript:

src/index.js

import "./styles.css";

const element = document.createElement("h1");
element.textContent = "Hello native CSS";
document.body.appendChild(element);

src/styles.css

h1 {
  color: #1f6feb;
}

سيعالج Webpack ملف CSS ويضمّنه في مخرجات البناء.

CSS Modules

يتضمن دعم CSS الأصلي أيضًا CSS Modules. الأسلوب الموصى به هو:

• الإبقاء على type: "css/auto" لمعالجة CSS المختلطة،
• استخدام تسمية .module.css (أو .modules.css) لملفات CSS Modules.

src/button.module.css

.button {
  background: #0d6efd;
  color: white;
  border: 0;
  border-radius: 4px;
  padding: 8px 12px;
}

src/index.js

import * as styles from "./button.module.css";

const button = document.createElement("button");
button.className = styles.button;
button.textContent = "Click me";
document.body.appendChild(button);

يمكنك تخصيص سلوك CSS Modules باستخدام خيارات parser و generator:

webpack.config.js

export default {
  experiments: {
    css: true,
  },
  module: {
    parser: {
      "css/module": {
        namedExports: true,
      },
    },
    generator: {
      "css/module": {
        exportsConvention: "camel-case-only",
        localIdentName: "[uniqueName]-[id]-[local]",
      },
    },
  },
};

بناء الإنتاج

مع experiments.css: true، يوفر webpack استخراج CSS أصليًا وتجزئة محتوى لملفات CSS في بناءات الإنتاج.

بالمقارنة مع الإعداد الكلاسيكي:

• الأسلوب التقليدي: css-loader + mini-css-extract-plugin
• الأسلوب الأصلي: experiments.css مع سلوك استخراج مضمّن

يقلل هذا من حجم الإعدادات ويبقي مسار معالجة CSS أقرب إلى ميزات webpack الأساسية.

الحالة التجريبية والقيود المعروفة

يُعد experiments.css تجريبيًا صراحةً، لذلك تعامل معه كميزة اختيارية واختبره بعناية قبل تعميمه على نطاق واسع.

نقاط معروفة يجب أخذها في الحسبان:

• قد تستمر واجهات API والسلوك في التطور قبل أن تصبح افتراضية في webpack v6.
• بعض الخيارات الخاصة بالـ loaders ليست جزءًا من سلوك CSS الأصلي (مثل المرشحات الخاصة بـ loader معين).
• إذا كان مشروعك يعتمد على سلاسل loaders متقدمة، فتحقق من كل جزء قبل الانتقال الكامل.

دليل الترحيل

إذا كنت تستخدم حاليًا css-loader و mini-css-extract-plugin و style-loader، فانتقل على خطوات صغيرة.

1) ابدأ من إعداد كلاسيكي

webpack.config.js

import MiniCssExtractPlugin from "mini-css-extract-plugin";

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
  plugins: [new MiniCssExtractPlugin()],
};

2) انتقل إلى CSS الأصلي

webpack.config.js

export default {
  experiments: {
    css: true,
  },
};

3) انقل خيارات css-loader أولًا

ينبغي نقل معظم الخيارات المرتبطة بـ CSS Modules إلى إعدادات parser/generator الأصلية.

webpack.config.js

export default {
  experiments: {
    css: true,
  },
  module: {
    parser: {
      css: {
        import: true,
        url: true,
      },
      "css/module": {
        namedExports: true,
      },
    },
    generator: {
      "css/module": {
        exportsConvention: "camel-case-only",
        localIdentName: "[local]-[hash:base64:6]",
      },
    },
  },
};

ملاحظات:

• import و url هما مفتاحا parser أصليان لمعالجة CSS.
• يتحكم namedExports في سلوك صادرات CSS Modules.
• يوفر exportsConvention و localIdentName تشكيلًا لتصدير الأصناف وأسمائها.
• يدعم localIdentName مواضع hash (مثل [hash:base64:6])؛ يمكنك ضبط التجزئة عالميًا باستخدام output.hashFunction و output.hashDigest و output.hashDigestLength و output.hashSalt.
• لا تتوفر خيارات css-loader الشبيهة بالمرشحات كمكافئات مباشرة؛ استخدم آليات webpack مثل IgnorePlugin عند الحاجة.

4) استبدل mini-css-extract-plugin

عند تفعيل experiments.css، يوفر webpack استخراج CSS أصليًا ومعالجة hash للمحتوى في ملفات CSS الناتجة، لذلك يمكنك إزالة كل من mini-css-extract-plugin و css-loader من هذا الإعداد الأساسي.

webpack.config.js

-import MiniCssExtractPlugin from "mini-css-extract-plugin";
-
 export default {
+  experiments: {
+    css: true,
+  },
-  plugins: [new MiniCssExtractPlugin()],
 };

يمكنك إزالة:

• سلسلة loaders الخاصة بـ CSS (بما في ذلك css-loader) من module.rules،
• نسخة الملحق new MiniCssExtractPlugin().

5) استبدل style-loader بـ exportType: "style"

إذا كنت تستخدم style-loader لحقن الأنماط أثناء وقت التشغيل، فأبقِ css/auto واستخدم تسمية الوحدات (.module.css أو .modules.css)، ثم عيّن exportType: "style":

webpack.config.js

export default {
  experiments: {
    css: true,
  },
  module: {
    rules: [
      {
        test: /\.css$/i,
        type: "css/auto",
        parser: {
          exportType: "style",
        },
      },
    ],
  },
};

يحقن هذا الوضع عنصر <style> من وقت تشغيل webpack ويغطي حالة الاستخدام المعتادة لـ style-loader.

إذا لم تستطع إعادة تسمية الملفات وفق اصطلاح تسمية CSS Modules، يمكنك استخدام type: "css/module" مباشرة للقاعدة المعنية.

6) أبقِ الاستيرادات دون تغيير

يمكن أن تبقى استيرادات JS كما هي:

import "./styles.css";
import * as styles from "./button.module.css";

7) تحقق من المخرجات في التطوير والإنتاج

تحقق مما يلي:

• يتم تطبيق الأنماط بشكل صحيح في التطوير،
• يتم إصدار ملفات CSS المولّدة للإنتاج،
• تتطابق صادرات CSS Modules مع استخدامك الحالي.