fix: improve help for some flags

webpack · May 18, 2023 · f468614 · f468614
1 parent 2b66643
commit f468614
Show file tree

Hide file tree

Showing 8 changed files with 532 additions and 482 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -17,22 +17,25 @@
     "configjs",
     "configtest",
     "CRLs",
+    "dbaeumer",
     "deserialization",
     "discoveryjs",
     "dotfolder",
     "entrypoint",
     "entrypoints",
     "envinfo",
     "Eren",
+    "esbenp",
+    "eslintcache",
     "execa",
     "Fira",
     "gitter",
     "Gojou",
     "Hisoka",
     "Hoshiumi",
     "Ichigo",
-    "IIFE's",
     "iife",
+    "IIFE's",
     "Itadori",
     "Iwaizumi",
     "Jotaro",
@@ -45,13 +48,19 @@
     "loglevel",
     "Luffy",
     "mergeable",
+    "mfirst",
     "Miyuki",
     "Mizuhara",
+    "msecond",
+    "msuccessfully",
     "multicompiler",
     "multipleq",
+    "myvar",
+    "myval",
     "Naruto",
     "Neue",
     "Nishinoya",
+    "Nitin",
     "nwjs",
     "Oikawa",
     "pathinfo",
@@ -67,9 +76,11 @@
     "Satoru",
     "Segoe",
     "Shoyo",
+    "smoketest",
     "smoketests",
     "sockjs",
     "somefile",
+    "sourcemaps",
     "SPDY",
     "splitted",
     "Statsv",
@@ -82,23 +93,14 @@
     "Tobio",
     "tsbuildinfo",
     "typeahead",
+    "wagoid",
     "webassembly",
     "webpackfile",
     "Yukihira",
     "Yukii",
     "Yuuji",
     "Zangetsu",
-    "Zenitsu",
-    "eslintcache",
-    "wagoid",
-    "Nitin",
-    "smoketest",
-    "dbaeumer",
-    "esbenp",
-    "msuccessfully",
-    "mfirst",
-    "msecond",
-    "sourcemaps"
+    "Zenitsu"
   ],
   "dictionaries": ["npm", "software-terms"],
   "ignorePaths": [

diff --git a/.gitattributes b/.gitattributes
@@ -1,2 +1 @@
-*.js text eol=lf
-*.ts text eol=lf
+* text eol=lf
diff --git a/OPTIONS.md b/OPTIONS.md
@@ -5,16 +5,16 @@ Alternative usage to run commands: webpack [command] [options]
 The build tool for modern web applications.
 
 Options:
-  -c, --config <value...>                                                            Provide path to a webpack configuration file e.g. ./webpack.config.js.
-  --config-name <value...>                                                           Name of the configuration to use.
+  -c, --config <pathToConfigFile...>                                                 Provide path to one or more webpack configuration files to process, e.g. "./webpack.config.js".
+  --config-name <name...>                                                            Name(s) of particular configuration(s) to use if configuration file exports an array of multiple configurations.
   -m, --merge                                                                        Merge two or more configurations using 'webpack-merge'.
   --disable-interpret                                                                Disable interpret for loading the config file.
-  --env <value...>                                                                   Environment passed to the configuration when it is a function.
+  --env <value...>                                                                   Environment variables passed to the configuration when it is a function, e.g. "myvar" or "myvar=myval".
   --node-env <value>                                                                 Sets process.env.NODE_ENV to the specified value.
   --define-process-env-node-env <value>                                              Sets process.env.NODE_ENV to the specified value. (Currently an alias for `--node-env`).
   --analyze                                                                          It invokes webpack-bundle-analyzer plugin to get bundle information.
   --progress [value]                                                                 Print compilation progress during build.
-  -j, --json [value]                                                                 Prints result as JSON or store it in a file.
+  -j, --json [pathToJsonFile]                                                        Prints result as JSON or store it in a file.
   --fail-on-warnings                                                                 Stop webpack-cli process with non-zero exit code on warnings from webpack.
   -e, --extends <value...>                                                           Path to the configuration to be extended (only works when using webpack-cli).
   --no-amd                                                                           Negative 'amd' option.
@@ -1015,7 +1015,7 @@ Commands:
   init|create|new|c|n [generation-path] [options]                                    Initialize a new webpack project.
   loader|l [output-path] [options]                                                   Scaffold a loader.
   plugin|p [output-path] [options]                                                   Scaffold a plugin.
-  serve|server|s [entries...] [options]                                              Run the webpack dev server.
+  serve|server|s [entries...] [options]                                              Run the webpack dev server and watch for source file changes while serving.
   version|v [options]                                                                Output the version number of 'webpack', 'webpack-cli' and 'webpack-dev-server' and commands.
   watch|w [entries...] [options]                                                     Run webpack and watch for files changes.
 

diff --git a/SERVE-OPTIONS-v4.md b/SERVE-OPTIONS-v4.md
@@ -1,18 +1,18 @@
 ```
 Usage: webpack serve|server|s [entries...] [options]
 
-Run the webpack dev server.
+Run the webpack dev server and watch for source file changes while serving.
 
 Options:
-  -c, --config <value...>                             Provide path to a webpack configuration file e.g. ./webpack.config.js.
-  --config-name <value...>                            Name of the configuration to use.
+  -c, --config <pathToConfigFile...>                  Provide path to one or more webpack configuration files to process, e.g. "./webpack.config.js".
+  --config-name <name...>                             Name(s) of particular configuration(s) to use if configuration file exports an array of multiple configurations.
   -m, --merge                                         Merge two or more configurations using 'webpack-merge'.
   --disable-interpret                                 Disable interpret for loading the config file.
-  --env <value...>                                    Environment passed to the configuration when it is a function.
+  --env <value...>                                    Environment variables passed to the configuration when it is a function, e.g. "myvar" or "myvar=myval".
   --node-env <value>                                  Sets process.env.NODE_ENV to the specified value.
   --analyze                                           It invokes webpack-bundle-analyzer plugin to get bundle information.
   --progress [value]                                  Print compilation progress during build.
-  -j, --json [value]                                  Prints result as JSON or store it in a file.
+  -j, --json [pathToJsonFile]                         Prints result as JSON or store it in a file.
   --fail-on-warnings                                  Stop webpack-cli process with non-zero exit code on warnings from webpack.
   -e, --extends <value...>                            Path to the configuration to be extended (only works when using webpack-cli).
   -d, --devtool <value>                               A developer tool to enhance debugging (false | eval | [inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map).
@@ -26,6 +26,8 @@ Options:
   --no-stats                                          Negative 'stats' option.
   -t, --target <value...>                             Environment to build for. Environment to build for. An array of environments to build for all of them when possible.
   --no-target                                         Negative 'target' option.
+  -w, --watch                                         Enter watch mode, which rebuilds on file change.
+  --no-watch                                          Negative 'watch' option.
   --watch-options-stdin                               Stop watching when stdin stream has ended.
   --no-watch-options-stdin                            Negative 'watch-options-stdin' option.
   --allowed-hosts <value...>                          Allows to enumerate the hosts from which access to the dev server are allowed (useful when you are proxying dev server, by default is 'auto').

diff --git a/packages/serve/src/index.ts b/packages/serve/src/index.ts
@@ -28,7 +28,7 @@ class ServeCommand {
       {
         name: "serve [entries...]",
         alias: ["server", "s"],
-        description: "Run the webpack dev server.",
+        description: "Run the webpack dev server and watch for source file changes while serving.",
         usage: "[entries...] [options]",
         pkg: "@webpack-cli/serve",
         dependencies: [WEBPACK_PACKAGE, WEBPACK_DEV_SERVER_PACKAGE],

diff --git a/packages/webpack-cli/src/types.ts b/packages/webpack-cli/src/types.ts
@@ -109,7 +109,7 @@ interface WebpackCLIStats extends Stats {
 
 type WebpackCLIMainOption = Pick<
   WebpackCLIBuiltInOption,
-  "description" | "defaultValue" | "multiple"
+  "valueName" | "description" | "defaultValue" | "multiple"
 > & {
   flags: string;
   type: Set<BooleanConstructor | StringConstructor | NumberConstructor>;
@@ -139,6 +139,7 @@ interface WebpackCLIBuiltInFlag {
   configs?: Partial<FlagConfig>[];
   negative?: boolean;
   multiple?: boolean;
+  valueName?: string;
   description: string;
   describe?: string;
   negatedDescription?: string;

diff --git a/packages/webpack-cli/src/webpack-cli.ts b/packages/webpack-cli/src/webpack-cli.ts
@@ -638,6 +638,7 @@ class WebpackCLI implements IWebpackCLI {
 
       mainOption = {
         flags: option.alias ? `-${option.alias}, --${option.name}` : `--${option.name}`,
+        valueName: option.valueName || "value",
         description: option.description || "",
         type: mainOptionType,
         multiple: option.multiple,
@@ -654,6 +655,7 @@ class WebpackCLI implements IWebpackCLI {
     } else {
       mainOption = {
         flags: option.alias ? `-${option.alias}, --${option.name}` : `--${option.name}`,
+        valueName: option.valueName || "value",
         description: option.description || "",
         type: option.type
           ? new Set(Array.isArray(option.type) ? option.type : [option.type])
@@ -673,9 +675,13 @@ class WebpackCLI implements IWebpackCLI {
     }
 
     if (mainOption.type.size > 1 && mainOption.type.has(Boolean)) {
-      mainOption.flags = `${mainOption.flags} [value${mainOption.multiple ? "..." : ""}]`;
+      mainOption.flags = `${mainOption.flags} [${mainOption.valueName || "value"}${
+        mainOption.multiple ? "..." : ""
+      }]`;
     } else if (mainOption.type.size > 0 && !mainOption.type.has(Boolean)) {
-      mainOption.flags = `${mainOption.flags} <value${mainOption.multiple ? "..." : ""}>`;
+      mainOption.flags = `${mainOption.flags} <${mainOption.valueName || "value"}${
+        mainOption.multiple ? "..." : ""
+      }>`;
     }
 
     if (mainOption.type.size === 1) {
@@ -808,7 +814,9 @@ class WebpackCLI implements IWebpackCLI {
           },
         ],
         multiple: true,
-        description: "Provide path to a webpack configuration file e.g. ./webpack.config.js.",
+        valueName: "pathToConfigFile",
+        description:
+          'Provide path to one or more webpack configuration files to process, e.g. "./webpack.config.js".',
         helpLevel: "minimum",
       },
       {
@@ -819,7 +827,9 @@ class WebpackCLI implements IWebpackCLI {
           },
         ],
         multiple: true,
-        description: "Name of the configuration to use.",
+        valueName: "name",
+        description:
+          "Name(s) of particular configuration(s) to use if configuration file exports an array of multiple configurations.",
         helpLevel: "minimum",
       },
       {
@@ -890,7 +900,8 @@ class WebpackCLI implements IWebpackCLI {
           return previous;
         },
         multiple: true,
-        description: "Environment passed to the configuration when it is a function.",
+        description:
+          'Environment variables passed to the configuration when it is a function, e.g. "myvar" or "myvar=myval".',
         helpLevel: "minimum",
       },
       {
@@ -958,6 +969,7 @@ class WebpackCLI implements IWebpackCLI {
           },
         ],
         alias: "j",
+        valueName: "pathToJsonFile",
         description: "Prints result as JSON or store it in a file.",
         helpLevel: "minimum",
       },