واجهة Node

يوفر webpack واجهة Node.js API يمكن استخدامها مباشرة داخل بيئة تشغيل Node.js.

تفيد Node.js API عندما تحتاج إلى تخصيص عملية build أو عملية التطوير؛ لأن عرض النتائج ومعالجة الأخطاء يصبحان مسؤوليتك أنت، بينما يتولى webpack جزء compilation فقط. لهذا السبب، لن تؤثر خيارات إعداد stats عند استدعاء webpack().

التثبيت

لبدء استخدام webpack Node.js API، ثبّت webpack أولًا إذا لم يكن مثبتًا لديك:

npm install --save-dev webpack

ثم استورد module الخاص بـ webpack داخل سكربت Node.js:

import webpack from "webpack";

webpack()

تستقبل الدالة webpack المستوردة كائن إعدادات webpack، وتُشغّل webpack compiler إذا مررت لها callback:

import webpack from "webpack";

webpack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // انتهت المعالجة
});

نسخة Compiler

إذا لم تمرر callback إلى دالة تشغيل webpack، فسترجع instance من Compiler الخاص بـ webpack. يمكن استخدام هذه instance لتشغيل webpack يدويًا، أو لجعله يبني ويراقب التغييرات، بطريقة مشابهة لـ CLI. توفر instance الخاصة بـ Compiler الدوال التالية:

• .run(callback)
• .watch(watchOptions, handler)

عادةً يتم إنشاء instance رئيسية واحدة فقط من Compiler، لكن يمكن إنشاء child compilers لتفويض مهام محددة. في النهاية، Compiler هو دالة توفر الحد الأدنى اللازم لإبقاء دورة الحياة تعمل. أما عمليات loading وbundling والكتابة فتُفوّض إلى plugins المسجلة.

تُستخدم الخاصية hooks على instance الخاصة بـ Compiler لتسجيل plugin على أي hook event ضمن دورة حياة Compiler. ويستخدم webpack الأداتين WebpackOptionsDefaulter وWebpackOptionsApply لإعداد instance الخاصة بـ Compiler مع كل plugins المدمجة.

تُستخدم الدالة run لبدء كل عمل compilation. وبعد الانتهاء، تُنفّذ دالة callback التي مررتها. يجب أن يتم تسجيل stats والأخطاء النهائية داخل هذه الدالة.

Run

استدعاء الدالة run على instance الخاصة بـ Compiler يشبه طريقة التشغيل السريعة المذكورة أعلاه:

import webpack from "webpack";

const compiler = webpack({
  // ...
});

compiler.run((err, stats) => {
  // ...

  compiler.close((closeErr) => {
    // ...
  });
});

Watching

استدعاء الدالة watch يشغّل webpack runner، ثم يراقب التغييرات بطريقة مشابهة لـ CLI عند استخدام webpack --watch. بمجرد أن يكتشف webpack تغييرًا، يعيد التشغيل. وترجع الدالة instance من Watching.

watch(watchOptions, callback);

import webpack from "webpack";

const compiler = webpack({
  // ...
});

const watching = compiler.watch(
  {
    // مثال
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // اطبع نتيجة watch/build هنا...
    console.log(stats);
  },
);

خيارات Watching مشروحة بتفصيل هنا.

إغلاق Watching

ترجع الدالة watch instance من Watching توفر الدالة .close(callback). استدعاء هذه الدالة ينهي المراقبة:

watching.close((closeErr) => {
  console.log("Watching Ended.");
});

إبطال Watching

باستخدام watching.invalidate يمكنك إبطال جولة compilation الحالية يدويًا، بدون إيقاف عملية watch:

watching.invalidate();

كائن Stats

كائن stats الذي يُمرر كثاني argument إلى callback الخاصة بـ webpack()، مصدر جيد للمعلومات عن عملية compilation. يحتوي على:

• الأخطاء والتحذيرات إن وجدت.
• التوقيتات.
• معلومات Module وChunk.

تستخدم webpack CLI هذه المعلومات لعرض ناتج منسق بشكل جيد في console.

يعرض كائن stats الدوال التالية:

stats.hasErrors()

تُستخدم لمعرفة ما إذا حدثت أخطاء أثناء compilation. ترجع true أو false.

stats.hasWarnings()

تُستخدم لمعرفة ما إذا ظهرت تحذيرات أثناء compilation. ترجع true أو false.

stats.toJson(options)

ترجع معلومات compilation ككائن JSON. يمكن أن تكون options نصًا يمثل preset، أو object للتحكم بتفاصيل أكثر:

stats.toJson("minimal");

stats.toJson({
  assets: false,
  hash: true,
});

كل الخيارات والـ presets المتاحة موضحة في توثيق stats.

هذا مثال على ناتج هذه الدالة.

stats.toString(options)

ترجع نصًا منسقًا لمعلومات compilation، بشكل مشابه لناتج CLI.

الخيارات هي نفسها خيارات stats.toJson(options)، مع إضافة واحدة:

stats.toString({
  // أضف ألوان console
  colors: true,
});

هذا مثال على استخدام stats.toString():

import webpack from "webpack";

webpack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err);
      return;
    }

    console.log(
      stats.toString({
        chunks: false, // يجعل ناتج build أهدأ بكثير
        colors: true, // يعرض الألوان في console
      }),
    );
  },
);

MultiCompiler

يسمح module المسمى MultiCompiler لـ webpack بتشغيل عدة إعدادات داخل compilers منفصلة. إذا كان parameter المسمى options في NodeJS API الخاصة بـ webpack عبارة عن array من الخيارات، فسيطبّق webpack compilers منفصلة ويستدعي callback بعد تنفيذ كل compilers.

import webpack from "webpack";

webpack(
  [
    { entry: "./index1.js", output: { filename: "bundle1.js" } },
    { entry: "./index2.js", output: { filename: "bundle2.js" } },
  ],
  (err, stats) => {
    process.stdout.write(`${stats.toString()}`);
  },
);

معالجة الأخطاء

لمعالجة الأخطاء بشكل جيد، يجب أن تراعي ثلاثة أنواع:

• أخطاء webpack الحرجة، مثل إعدادات خاطئة.
• أخطاء compilation، مثل modules مفقودة أو أخطاء syntax.
• تحذيرات compilation.

هذا مثال يتعامل مع الأنواع كلها:

import webpack from "webpack";

webpack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err.stack || err);
      if (err.details) {
        console.error(err.details);
      }
      return;
    }

    const info = stats.toJson();

    if (stats.hasErrors()) {
      console.error(info.errors);
    }

    if (stats.hasWarnings()) {
      console.warn(info.warnings);
    }

    // سجّل النتيجة...
  },
);

أنظمة ملفات مخصصة

افتراضيًا، يقرأ webpack الملفات ويكتبها على القرص باستخدام نظام الملفات العادي. لكن يمكن تغيير سلوك الإدخال أو الإخراج باستخدام نوع مختلف من أنظمة الملفات، مثل memory أو webDAV وغيرها. لفعل ذلك، يمكن تغيير inputFileSystem أو outputFileSystem. مثلًا، يمكنك استبدال outputFileSystem الافتراضي بـ memfs لكتابة الملفات في الذاكرة بدل القرص:

import { Volume, createFsFromVolume } from "memfs";
import webpack from "webpack";

const fs = createFsFromVolume(new Volume());
const compiler = webpack({
  /* options */
});

compiler.outputFileSystem = fs;
compiler.run((err, stats) => {
  // اقرأ output لاحقًا:
  const content = fs.readFileSync("...");
  compiler.close((closeErr) => {
    // ...
  });
});

لاحظ أن هذا هو الأسلوب الذي يستخدمه webpack-dev-middleware، والذي يستخدمه webpack-dev-server وحزم أخرى كثيرة. لذلك قد تشعر أن ملفاتك "مختفية"، لكنها في الحقيقة تُقدّم للمتصفح من الذاكرة.