واجهة سطر الأوامر

لاستخدام أسهل وتوزيع أوضح للإعدادات، يمكن ضبط webpack عبر ملف webpack.config.js. أي parameters ترسلها إلى CLI سيتم ربطها بالـ parameter المقابل داخل ملف الإعدادات.

اقرأ دليل التثبيت إذا لم يكن webpack وCLI مثبتين لديك.

Commands

يوفر webpack-cli مجموعة أوامر تجعل العمل مع webpack أسهل. افتراضيًا، يأتي webpack مع الأوامر التالية:

Build

يشغّل webpack، وهو الأمر الافتراضي ويمكن حذفه.

npx webpack build [options]

مثال

npx webpack build --config ./webpack.config.js --stats verbose

Init

يُستخدم لتهيئة مشروع webpack جديد باستخدام create-webpack-app.

npx create-webpack-app [generation-path] [options]

مثال

npx create-webpack-app ./my-app --force --template=default

اختصار لـ:

npx create-webpack-app init ./my-app --force --template=default

Generation Path

المكان الذي سيتم توليد الإعدادات فيه. القيمة الافتراضية هي process.cwd().

Options

-t, --template

string = 'default'

اسم القالب المراد توليده.

-f, --force

boolean

يولّد مشروعًا بدون أسئلة. عند تفعيله، سيتم استخدام الإجابة الافتراضية لكل سؤال.

القوالب المدعومة

• --template=default - القالب الافتراضي مع إعدادات أساسية.
• --template=react - قالب بإعدادات React.
• --template=vue - قالب بإعدادات Vue.
• --template=svelte - قالب بإعدادات Svelte.

Loader

ينشئ هيكل loader.

npx create-webpack-app loader [output-path] [options]

مثال

npx create-webpack-app loader ./my-loader --template=default

Output Path

المسار إلى مجلد output، مثل ./loader-name.

Options

-t, --template

string = 'default'

نوع القالب.

Plugin

ينشئ هيكل plugin.

npx create-webpack-app plugin [output-path] [options]

مثال

npx create-webpack-app plugin ./my-plugin --template=default

Output Path

المسار إلى مجلد output، مثل ./plugin-name.

Options

-t, --template

string = 'default'

نوع القالب.

Info

يطبع معلومات عن نظامك.

npx webpack info [options]

مثال

npx webpack info --output json --addition-package postcss

خيارات info

-a, --additional-package

string

يضيف حزمًا إضافية إلى output.

مثال

npx webpack info --additional-package postcss

-o, --output

string : 'json' | 'markdown'

للحصول على output بتنسيق محدد.

مثال

npx webpack info --output markdown

Configtest

يتحقق من إعدادات webpack.

npx webpack configtest [config-path]

مثال

npx webpack configtest ./webpack.config.js

Config Path

المسار إلى ملف إعدادات webpack. القيمة الافتراضية هي ./webpack.config.js.

Serve

يشغّل webpack dev server.

npx webpack serve [options]

مثال

npx webpack serve --static --open

Watch

يشغّل webpack ويراقب تغييرات الملفات.

npx webpack watch [options]

مثال

npx webpack watch --mode development

Flags

افتراضيًا، يأتي webpack مع flags التالية:

Negated Flags

Core Flags

ابتداءً من CLI v4 وwebpack v5، تستورد CLI كامل configuration schema من webpack core، حتى تتيح ضبط معظم خيارات الإعداد تقريبًا من سطر الأوامر.

هذه قائمة بكل core flags المدعومة في webpack v5 مع CLI v4 - الرابط

مثلًا، إذا أردت تفعيل performance hints في مشروعك، يمكنك استخدام هذا الخيار في الإعدادات. ومع core flags يمكنك فعل ذلك بهذا الشكل:

npx webpack --performance-hints warning

Usage

مع ملف إعدادات

npx webpack [--config webpack.config.js]

راجع configuration لمعرفة الخيارات داخل ملف الإعدادات.

بدون ملف إعدادات

npx webpack --entry <entry> --output-path <output-path>

مثال

npx webpack --entry ./first.js --entry ./second.js --output-path /build

entry

اسم ملف أو مجموعة أسماء ملفات تعمل كـ entry point لبناء مشروعك. يمكنك تمرير أكثر من entry، حيث يتم تحميل كل entry عند بدء التشغيل. توجد عدة طرق لتحديد ملف أو ملفات entry عبر CLI:

npx webpack --entry-reset ./first-entry.js

npx webpack --entry-reset --entry ./first-entry.js

npx webpack --entry-reset ./first-entry.js ./other-entry.js

npx webpack --entry-reset --entry ./first-entry.js ./other-entry.js

output-path

مسار حفظ الملف المحزم. يتم ربطه بخيار الإعداد output.path.

مثال

إذا كانت بنية مشروعك كالتالي:

.
├── dist
├── index.html
└── src
    ├── index.js
    ├── index2.js
    └── others.js

npx webpack ./src/index.js --output-path dist

سيتم تحزيم كود المصدر باستخدام index.js كـ entry، وسيكون مسار ملف output bundle هو dist.

asset main.js 142 bytes [compared for emit] [minimized] (name: main)
./src/index.js 30 bytes [built] [code generated]
./src/others.js 1 bytes [built] [code generated]
webpack 5.1.0 compiled successfully in 187 ms

npx webpack ./src/index.js ./src/others2.js --output-path dist/

سيؤدي هذا إلى إنشاء bundle باستخدام الملفين كـ entry points منفصلة.

asset main.js 142 bytes [compared for emit] [minimized] (name: main)
./src/index.js 30 bytes [built] [code generated]
./src/others2.js 1 bytes [built] [code generated]
./src/others.js 1 bytes [built] [code generated]
webpack 5.1.0 compiled successfully in 198 ms

Default Configurations

تبحث CLI عن بعض ملفات الإعدادات الافتراضية داخل مسار مشروعك. هذه هي ملفات الإعداد التي تلتقطها CLI.

ترتيب البحث يكون حسب الأولوية التالية:

مثال: سيكون ترتيب البحث عن ملف الإعداد هكذا webpack.config.js > .webpack/webpack.config.js > .webpack/webpackfile.js

'webpack.config',
'.webpack/webpack.config',
'.webpack/webpackfile',

Common Options

help

عرض الأوامر والـ flags الأساسية المتاحة في cli

كل من webpack help [command] [option] وwebpack [command] --help صالح للحصول على المساعدة:

npx webpack --help

# أو

npx webpack help

عرض كل الأوامر والـ flags المدعومة من cli

npx webpack --help=verbose

عرض المساعدة لأمر أو خيار محدد

npx webpack help --mode

version

يطبع رقم إصدار webpack وwebpack-cli وwebpack-dev-server وحزم أخرى

لفحص إصدار webpack وwebpack-cli الذي تستخدمه، شغّل:

npx webpack --version

# أو

npx webpack version

سيطبع نتيجة مثل:

webpack 5.31.2
webpack-cli 4.6.0

وسيظهر إصدار webpack-dev-server أيضًا إذا كان مثبتًا لديك:

webpack 5.31.2
webpack-cli 4.6.0
webpack-dev-server 3.11.2

config

يبني source باستخدام ملف إعدادات

حدد ملف configuration مختلفًا عن webpack.config.js، وهو أحد الملفات الافتراضية.

npx webpack --config example.config.js

config-name

إذا كان ملف الإعدادات يصدّر عدة إعدادات، يمكنك استخدام --config-name لتحديد الإعداد الذي تريد تشغيله.

تخيل ملف webpack.config.js التالي:

export default [
  {
    output: {
      filename: "./dist-first.js",
    },
    name: "first",
    entry: "./src/first.js",
    mode: "development",
  },
  {
    output: {
      filename: "./dist-second.js",
    },
    name: "second",
    entry: "./src/second.js",
    mode: "development",
  },
  {
    output: {
      filename: "./dist-third.js",
    },
    name: "third",
    entry: "./src/third.js",
    mode: "none",
    stats: "verbose",
  },
];

لتشغيل إعداد second فقط:

npx webpack --config-name second

يمكنك أيضًا تمرير عدة قيم:

npx webpack --config-name first --config-name second

merge

يمكنك دمج إعدادين أو أكثر من إعدادات webpack باستخدام --merge:

npx webpack --config ./first.js --config ./second.js --merge

extends

يمكنك تمديد إعدادات webpack موجودة باستخدام --extends:

npx webpack --extends ./base.webpack.config.js

اقرأ المزيد في تمديد الإعدادات.

json

يطبع نتيجة webpack كـ JSON

npx webpack --json

إذا أردت حفظ stats كـ json بدل طباعتها، يمكنك استخدام:

npx webpack --json stats.json

في الحالات الأخرى، يطبع webpack مجموعة stats تعرض تفاصيل bundle وchunk والتوقيتات. باستخدام هذا الخيار، يمكن أن يكون output كائن JSON. تقبل هذه الاستجابة أداة analyse الخاصة بـ webpack، أو webpack-visualizer من chrisbateman، أو webpack-bundle-analyzer من th0r. تأخذ أداة analyse ملف JSON وتعرض كل تفاصيل build بشكل رسومي.

Environment Options

عندما تصدّر إعدادات webpack دالة، يمكن تمرير "environment" إليها.

env

npx webpack --env production    # env.production = true

يقبل argument المسمى --env عدة قيم:

إضافة إلى env المخصص الموضح أعلاه، توجد بعض القيم المدمجة تحت env لاستخدامها داخل إعدادات webpack:

لاحظ أنك لا تستطيع الوصول إلى environment variables المدمجة هذه داخل الكود المحزم.

export default (env, argv) => ({
  mode: env.WEBPACK_SERVE ? "development" : "production",
});

config-node-env

يضبط process.env.NODE_ENV داخل إعداداتك:

npx webpack --config-node-env production   # process.env.NODE_ENV = 'production' in `webpack.config.js`

عندما لا يكون خيار mode محددًا داخل الإعدادات، يمكنك استخدام خيار --config-node-env لضبط mode. مثلًا، استخدام --config-node-env production سيضبط كلًا من process.env.NODE_ENV وmode على 'production'.

إذا كانت إعداداتك تصدّر دالة، يتم تعيين قيمة --config-node-env إلى mode بعد أن ترجع الدالة. هذا يعني أن mode لن يكون متاحًا داخل arguments الخاصة بالدالة، أي env وargv. لكن قيمة --config-node-env يمكن الوصول إليها عبر argv.nodeEnv داخل الدالة واستخدامها حسب الحاجة.

export default (env, argv) => {
  console.log(argv.defineProcessEnvNodeEnv); // 'production' إذا استُخدم --config-node-env production
  return {
    // إعداداتك
  };
};

Configuration Options

Analyzing Bundle

يمكنك أيضًا استخدام webpack-bundle-analyzer لتحليل output bundles التي يصدرها webpack. يمكنك استخدام flag --analyze لتشغيله عبر CLI.

npx webpack --analyze

Progress

لفحص تقدم أي webpack compilation، يمكنك استخدام flag --progress.

npx webpack --progress

لجمع profile data الخاصة بخطوات التقدم، يمكنك تمرير القيمة profile إلى flag --progress.

npx webpack --progress=profile

تمرير CLI arguments إلى Node.js

لتمرير arguments مباشرة إلى عملية Node.js، يمكنك استخدام خيار NODE_OPTIONS.

مثلًا، لزيادة حد ذاكرة عملية Node.js إلى 4 GB:

NODE_OPTIONS="--max-old-space-size=4096" webpack

ويمكنك أيضًا تمرير عدة خيارات إلى عملية Node.js:

NODE_OPTIONS="--max-old-space-size=4096 -r /path/to/preload/file.js" webpack

أكواد الخروج ومعانيها

CLI Environment Variables

WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG=true npx webpack --config ./webpack.config.esm

WEBPACK_PACKAGE

يستخدم إصدارًا مخصصًا من webpack داخل CLI. بافتراض وجود المحتوى التالي في package.json:

{
  "webpack": "^4.0.0",
  "webpack-5": "npm:webpack@^5.32.0",
  "webpack-cli": "^4.5.0"
}

لاستخدام webpack v4.0.0:

npx webpack

لاستخدام webpack v5.32.0:

WEBPACK_PACKAGE=webpack-5 npx webpack

Troubleshooting

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for ./webpack.config.ts

قد تواجه هذا الخطأ عند استخدام ESM الأصلي في TypeScript، أي وجود type: "module" داخل package.json.

يدعم webpack-cli الإعدادات بصيغتي CommonJS وESM. في البداية يحاول تحميل الإعداد باستخدام import()، وإذا فشل يحاول تحميله باستخدام require(). لكن طريقة import() لن تعمل مع ts-node بدون تفعيل loader hooks، كما هو موضح في TypeStrong/ts-node#1007.

لإصلاح الخطأ السابق، استخدم الأمر التالي:

NODE_OPTIONS="--import=data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));" npx webpack --entry ./src/index.js --mode production

لمزيد من المعلومات، راجع توثيقنا عن كتابة إعدادات webpack باستخدام TypeScript.