From 4f5bab1896cce95db71539125b439e519da5d36e Mon Sep 17 00:00:00 2001 From: Nitin Kumar Date: Wed, 18 Aug 2021 19:39:34 +0530 Subject: [PATCH] docs: improve examples (#3672) --- examples/{cli => }/bonjour/README.md | 13 ++- examples/{cli => }/bonjour/app.js | 0 .../{cli/hmr => bonjour}/webpack.config.js | 2 +- examples/cli/https/README.md | 31 ------ examples/cli/https/webpack.config.js | 10 -- examples/cli/open-target/README.md | 34 ------- examples/cli/progress/webpack.config.js | 10 -- .../cli/web-socket-server/webpack.config.js | 10 -- examples/cli/web-socket-url-cli/README.md | 21 ---- examples/cli/web-socket-url-cli/app.js | 6 -- .../cli/web-socket-url-cli/webpack.config.js | 10 -- examples/{cli => }/compression/README.md | 30 +++++- examples/{cli => }/compression/app.js | 0 .../bonjour => compression}/webpack.config.js | 2 +- examples/{cli => }/default/README.md | 2 +- examples/{cli => }/default/app.js | 0 examples/{cli => }/default/pixels.png | Bin examples/{cli => }/default/style.less | 0 examples/{cli => }/default/svg.svg | 0 examples/{cli => }/default/webpack.config.js | 2 +- .../{cli => }/history-api-fallback/README.md | 17 +++- .../{cli => }/history-api-fallback/app.js | 0 .../{cli => }/history-api-fallback/file.txt | 0 .../history-api-fallback/webpack.config.js | 2 +- examples/{cli => }/hmr/README.md | 32 +++++- examples/{cli => }/hmr/app.js | 0 examples/{cli => }/hmr/example.js | 0 .../host-and-port => hmr}/webpack.config.js | 2 +- examples/{cli => }/host-and-port/README.md | 88 +++++++++++++++- examples/{cli => }/host-and-port/app.js | 0 .../webpack.config.js | 2 +- examples/https/README.md | 60 +++++++++++ examples/{cli => }/https/app.js | 0 examples/{cli => }/https/ssl/ca.pem | 0 examples/{cli => }/https/ssl/server.crt | 0 examples/{cli => }/https/ssl/server.key | 0 examples/{cli => }/https/ssl/server.pfx | Bin examples/https/webpack.config.js | 10 ++ examples/{cli => }/ipc/README.md | 2 +- examples/{cli => }/ipc/app.js | 0 examples/{cli => }/ipc/webpack.config.js | 2 +- examples/{cli => }/multi-compiler/README.md | 2 +- examples/{cli => }/multi-compiler/app.js | 0 .../multi-compiler/webpack.config.js | 2 +- examples/{cli => }/node-false/README.md | 4 +- examples/{cli => }/node-false/app.js | 0 .../{cli => }/node-false/webpack.config.js | 2 +- .../{cli => }/open-target-multiple/README.md | 17 +++- .../{cli => }/open-target-multiple/app1.js | 0 .../{cli => }/open-target-multiple/app2.js | 0 .../open-target-multiple/webpack.config.js | 2 +- examples/open-target/README.md | 95 ++++++++++++++++++ examples/{cli => }/open-target/app.js | 0 .../{cli => }/open-target/webpack.config.js | 2 +- examples/{cli => }/overlay/README.md | 17 +++- examples/{cli => }/overlay/app.js | 0 examples/{cli => }/overlay/webpack.config.js | 2 +- examples/{cli => }/progress/README.md | 17 +++- examples/{cli => }/progress/app.js | 0 examples/progress/webpack.config.js | 10 ++ examples/{cli => }/watch-static/README.md | 15 ++- examples/{cli => }/watch-static/app.js | 0 .../{cli => }/watch-static/assets/index.html | 0 .../{cli => }/watch-static/css/styles.css | 0 .../{cli => }/watch-static/webpack.config.js | 2 +- .../{cli => }/web-socket-server/README.md | 28 +++++- examples/{cli => }/web-socket-server/app.js | 0 examples/web-socket-server/webpack.config.js | 10 ++ examples/{cli => }/web-socket-url/README.md | 17 +++- examples/{cli => }/web-socket-url/app.js | 0 examples/{cli => }/web-socket-url/index.html | 0 .../web-socket-url/webpack.config.js | 2 +- test/cli/basic.test.js | 4 +- 73 files changed, 480 insertions(+), 170 deletions(-) rename examples/{cli => }/bonjour/README.md (86%) rename examples/{cli => }/bonjour/app.js (100%) rename examples/{cli/hmr => bonjour}/webpack.config.js (81%) delete mode 100644 examples/cli/https/README.md delete mode 100644 examples/cli/https/webpack.config.js delete mode 100644 examples/cli/open-target/README.md delete mode 100644 examples/cli/progress/webpack.config.js delete mode 100644 examples/cli/web-socket-server/webpack.config.js delete mode 100644 examples/cli/web-socket-url-cli/README.md delete mode 100644 examples/cli/web-socket-url-cli/app.js delete mode 100644 examples/cli/web-socket-url-cli/webpack.config.js rename examples/{cli => }/compression/README.md (83%) rename examples/{cli => }/compression/app.js (100%) rename examples/{cli/bonjour => compression}/webpack.config.js (81%) rename examples/{cli => }/default/README.md (97%) rename examples/{cli => }/default/app.js (100%) rename examples/{cli => }/default/pixels.png (100%) rename examples/{cli => }/default/style.less (100%) rename examples/{cli => }/default/svg.svg (100%) rename examples/{cli => }/default/webpack.config.js (91%) rename examples/{cli => }/history-api-fallback/README.md (82%) rename examples/{cli => }/history-api-fallback/app.js (100%) rename examples/{cli => }/history-api-fallback/file.txt (100%) rename examples/{cli => }/history-api-fallback/webpack.config.js (86%) rename examples/{cli => }/hmr/README.md (82%) rename examples/{cli => }/hmr/app.js (100%) rename examples/{cli => }/hmr/example.js (100%) rename examples/{cli/host-and-port => hmr}/webpack.config.js (81%) rename examples/{cli => }/host-and-port/README.md (71%) rename examples/{cli => }/host-and-port/app.js (100%) rename examples/{cli/compression => host-and-port}/webpack.config.js (81%) create mode 100644 examples/https/README.md rename examples/{cli => }/https/app.js (100%) rename examples/{cli => }/https/ssl/ca.pem (100%) rename examples/{cli => }/https/ssl/server.crt (100%) rename examples/{cli => }/https/ssl/server.key (100%) rename examples/{cli => }/https/ssl/server.pfx (100%) create mode 100644 examples/https/webpack.config.js rename examples/{cli => }/ipc/README.md (98%) rename examples/{cli => }/ipc/app.js (100%) rename examples/{cli => }/ipc/webpack.config.js (95%) rename examples/{cli => }/multi-compiler/README.md (95%) rename examples/{cli => }/multi-compiler/app.js (100%) rename examples/{cli => }/multi-compiler/webpack.config.js (82%) rename examples/{cli => }/node-false/README.md (84%) rename examples/{cli => }/node-false/app.js (100%) rename examples/{cli => }/node-false/webpack.config.js (82%) rename examples/{cli => }/open-target-multiple/README.md (72%) rename examples/{cli => }/open-target-multiple/app1.js (100%) rename examples/{cli => }/open-target-multiple/app2.js (100%) rename examples/{cli => }/open-target-multiple/webpack.config.js (95%) create mode 100644 examples/open-target/README.md rename examples/{cli => }/open-target/app.js (100%) rename examples/{cli => }/open-target/webpack.config.js (90%) rename examples/{cli => }/overlay/README.md (67%) rename examples/{cli => }/overlay/app.js (100%) rename examples/{cli => }/overlay/webpack.config.js (84%) rename examples/{cli => }/progress/README.md (66%) rename examples/{cli => }/progress/app.js (100%) create mode 100644 examples/progress/webpack.config.js rename examples/{cli => }/watch-static/README.md (88%) rename examples/{cli => }/watch-static/app.js (100%) rename examples/{cli => }/watch-static/assets/index.html (100%) rename examples/{cli => }/watch-static/css/styles.css (100%) rename examples/{cli => }/watch-static/webpack.config.js (85%) rename examples/{cli => }/web-socket-server/README.md (64%) rename examples/{cli => }/web-socket-server/app.js (100%) create mode 100644 examples/web-socket-server/webpack.config.js rename examples/{cli => }/web-socket-url/README.md (69%) rename examples/{cli => }/web-socket-url/app.js (100%) rename examples/{cli => }/web-socket-url/index.html (100%) rename examples/{cli => }/web-socket-url/webpack.config.js (88%) diff --git a/examples/cli/bonjour/README.md b/examples/bonjour/README.md similarity index 86% rename from examples/cli/bonjour/README.md rename to examples/bonjour/README.md index 95f9956d75..1d6099f8ff 100644 --- a/examples/cli/bonjour/README.md +++ b/examples/bonjour/README.md @@ -3,7 +3,18 @@ The Bonjour capability broadcasts server information via ZeroConf when the Server is started. -To run this example, run this command in your console or terminal: +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + bonjour: true, + }, +}; +``` + +Usage via CLI: ```console npx webpack serve --bonjour diff --git a/examples/cli/bonjour/app.js b/examples/bonjour/app.js similarity index 100% rename from examples/cli/bonjour/app.js rename to examples/bonjour/app.js diff --git a/examples/cli/hmr/webpack.config.js b/examples/bonjour/webpack.config.js similarity index 81% rename from examples/cli/hmr/webpack.config.js rename to examples/bonjour/webpack.config.js index 43b409e9d7..564acff99e 100644 --- a/examples/cli/hmr/webpack.config.js +++ b/examples/bonjour/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/https/README.md b/examples/cli/https/README.md deleted file mode 100644 index a8d6bd1680..0000000000 --- a/examples/cli/https/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# CLI: https - -You may choose to wish to run `webpack-dev-server` on `https`. - -## https - -Use HTTPS protocol. - -```console -npx webpack serve --open --https -``` - -## https options - -Customize `https` configuration with the following options: - -- `--https-key`: Path to an SSL key. -- `--https-pfx`: Path to an SSL pfx file. -- `--https-cert`: Path to an SSL certificate. -- `--https-cacert`: Path to an SSL CA certificate. -- `--https-passphrase`: Passphrase for a pfx file. -- `--https-request-cert`: Request for an SSL certificate. - -```console -npx webpack serve --open --https-key ./ssl/server.key --https-pfx ./ssl/server.pfx --https-cert ./ssl/server.crt --https-cacert ./ssl/ca.pem --https-passphrase webpack-dev-server --https-request-cert -``` - -## What Should Happen - -1. The script should open `https://localhost:8080/` in your default browser. -2. You should see the text on the page itself change to read `Success!`. diff --git a/examples/cli/https/webpack.config.js b/examples/cli/https/webpack.config.js deleted file mode 100644 index 43b409e9d7..0000000000 --- a/examples/cli/https/webpack.config.js +++ /dev/null @@ -1,10 +0,0 @@ -"use strict"; - -// our setup function adds behind-the-scenes bits to the config that all of our -// examples need -const { setup } = require("../../util"); - -module.exports = setup({ - context: __dirname, - entry: "./app.js", -}); diff --git a/examples/cli/open-target/README.md b/examples/cli/open-target/README.md deleted file mode 100644 index c343431456..0000000000 --- a/examples/cli/open-target/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# CLI: Open Target Option - -Open default generated URL in browser: - -``` -npx webpack serve --open-target -``` - -Open specific page in browser: - -``` -npx webpack serve --open-target /example.html#page1 -``` - -Open specific browser: - -``` -npx webpack serve --open-app firefox -``` - -Open specific page in specific browser: - -``` -npx webpack serve --open-target example.html#page1 --open-app firefox -``` - -Some applications may consist of multiple pages. During development it may -be useful to directly open a particular page. The page to open may be specified -as the argument to the `open-target` option. - -## What Should Happen - -The script should open `http://localhost:8080/example.html#page1` in your -default/specified browser. You should see the text on the page itself change to read `Success!`. diff --git a/examples/cli/progress/webpack.config.js b/examples/cli/progress/webpack.config.js deleted file mode 100644 index 43b409e9d7..0000000000 --- a/examples/cli/progress/webpack.config.js +++ /dev/null @@ -1,10 +0,0 @@ -"use strict"; - -// our setup function adds behind-the-scenes bits to the config that all of our -// examples need -const { setup } = require("../../util"); - -module.exports = setup({ - context: __dirname, - entry: "./app.js", -}); diff --git a/examples/cli/web-socket-server/webpack.config.js b/examples/cli/web-socket-server/webpack.config.js deleted file mode 100644 index 43b409e9d7..0000000000 --- a/examples/cli/web-socket-server/webpack.config.js +++ /dev/null @@ -1,10 +0,0 @@ -"use strict"; - -// our setup function adds behind-the-scenes bits to the config that all of our -// examples need -const { setup } = require("../../util"); - -module.exports = setup({ - context: __dirname, - entry: "./app.js", -}); diff --git a/examples/cli/web-socket-url-cli/README.md b/examples/cli/web-socket-url-cli/README.md deleted file mode 100644 index e8f2c25dd1..0000000000 --- a/examples/cli/web-socket-url-cli/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# CLI: Web Socket URL - -```console -npx webpack serve --open --host 0.0.0.0 --client-web-socket-url ws://:8080 -``` - -_NOTE: replace `` with your local IP Address._ - -In order to make the server publicly accessible the client needs to know with -what host to connect to the server. If `--host 0.0.0.0` is given, the client -would try to connect to `0.0.0.0`. With the `--client-web-socket-url` options it is possible to -override this. - -## What Should Happen - -1. The script should open `http://0.0.0.0:8080/` in your default browser. -2. You should see the text on the page itself change to read `Success!`. -3. Open the console in your browser's devtools. -4. Select the 'Network' tab. -5. Select the 'WS' or 'WebSockets' sub-tab. -6. Verify that the WebSocket is connecting to `:8080`. diff --git a/examples/cli/web-socket-url-cli/app.js b/examples/cli/web-socket-url-cli/app.js deleted file mode 100644 index 51cf4a396b..0000000000 --- a/examples/cli/web-socket-url-cli/app.js +++ /dev/null @@ -1,6 +0,0 @@ -"use strict"; - -const target = document.querySelector("#target"); - -target.classList.add("pass"); -target.innerHTML = "Success!"; diff --git a/examples/cli/web-socket-url-cli/webpack.config.js b/examples/cli/web-socket-url-cli/webpack.config.js deleted file mode 100644 index 43b409e9d7..0000000000 --- a/examples/cli/web-socket-url-cli/webpack.config.js +++ /dev/null @@ -1,10 +0,0 @@ -"use strict"; - -// our setup function adds behind-the-scenes bits to the config that all of our -// examples need -const { setup } = require("../../util"); - -module.exports = setup({ - context: __dirname, - entry: "./app.js", -}); diff --git a/examples/cli/compression/README.md b/examples/compression/README.md similarity index 83% rename from examples/cli/compression/README.md rename to examples/compression/README.md index 5d1e007f78..c1b4f668a5 100644 --- a/examples/cli/compression/README.md +++ b/examples/compression/README.md @@ -5,9 +5,20 @@ to roughly 30% of its original size before the files are sent to the browser. It is enabled by default. -## `--compress` +## true -To run this example, run this command in your console or terminal: +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + compress: true, + }, +}; +``` + +Usage via CLI: ```console npx webpack serve --open --compress @@ -20,9 +31,20 @@ npx webpack serve --open --compress 3. Open the console in your browser's devtools and select the _Network_ tab. 4. Find `bundle.js`. The response headers should contain `Content-Encoding: gzip`. -## `--no-compress` +## false + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + compress: false, + }, +}; +``` -To run this example, run this command in your console or terminal: +Usage via CLI: ```console npx webpack serve --open --no-compress diff --git a/examples/cli/compression/app.js b/examples/compression/app.js similarity index 100% rename from examples/cli/compression/app.js rename to examples/compression/app.js diff --git a/examples/cli/bonjour/webpack.config.js b/examples/compression/webpack.config.js similarity index 81% rename from examples/cli/bonjour/webpack.config.js rename to examples/compression/webpack.config.js index 43b409e9d7..564acff99e 100644 --- a/examples/cli/bonjour/webpack.config.js +++ b/examples/compression/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/default/README.md b/examples/default/README.md similarity index 97% rename from examples/cli/default/README.md rename to examples/default/README.md index 1eb1321fbe..8d6b77225f 100644 --- a/examples/cli/default/README.md +++ b/examples/default/README.md @@ -1,4 +1,4 @@ -# CLI: Default State +# Default State This example demonstrates how to use `webpack-dev-server`. diff --git a/examples/cli/default/app.js b/examples/default/app.js similarity index 100% rename from examples/cli/default/app.js rename to examples/default/app.js diff --git a/examples/cli/default/pixels.png b/examples/default/pixels.png similarity index 100% rename from examples/cli/default/pixels.png rename to examples/default/pixels.png diff --git a/examples/cli/default/style.less b/examples/default/style.less similarity index 100% rename from examples/cli/default/style.less rename to examples/default/style.less diff --git a/examples/cli/default/svg.svg b/examples/default/svg.svg similarity index 100% rename from examples/cli/default/svg.svg rename to examples/default/svg.svg diff --git a/examples/cli/default/webpack.config.js b/examples/default/webpack.config.js similarity index 91% rename from examples/cli/default/webpack.config.js rename to examples/default/webpack.config.js index f1481a31b4..0528cae748 100644 --- a/examples/cli/default/webpack.config.js +++ b/examples/default/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/history-api-fallback/README.md b/examples/history-api-fallback/README.md similarity index 82% rename from examples/cli/history-api-fallback/README.md rename to examples/history-api-fallback/README.md index 2a5eb39e7a..1b1b1a94d2 100644 --- a/examples/cli/history-api-fallback/README.md +++ b/examples/history-api-fallback/README.md @@ -1,10 +1,23 @@ -# CLI: History API Fallback Option +# historyApiFallback Option This option enables [History API Fallback](https://github.com/bripkens/connect-history-api-fallback) support in `webpack-dev-server`, effectively asking the server to fallback to `index.html` in the event that a requested resource cannot be found. -```shell +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + historyApiFallback: true, + }, +}; +``` + +Usage via CLI: + +```console npx webpack serve --open --history-api-fallback ``` diff --git a/examples/cli/history-api-fallback/app.js b/examples/history-api-fallback/app.js similarity index 100% rename from examples/cli/history-api-fallback/app.js rename to examples/history-api-fallback/app.js diff --git a/examples/cli/history-api-fallback/file.txt b/examples/history-api-fallback/file.txt similarity index 100% rename from examples/cli/history-api-fallback/file.txt rename to examples/history-api-fallback/file.txt diff --git a/examples/cli/history-api-fallback/webpack.config.js b/examples/history-api-fallback/webpack.config.js similarity index 86% rename from examples/cli/history-api-fallback/webpack.config.js rename to examples/history-api-fallback/webpack.config.js index 3f4336c9d9..2a625387a0 100644 --- a/examples/cli/history-api-fallback/webpack.config.js +++ b/examples/history-api-fallback/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/hmr/README.md b/examples/hmr/README.md similarity index 82% rename from examples/cli/hmr/README.md rename to examples/hmr/README.md index 566e7376c3..192f2a1fab 100644 --- a/examples/cli/hmr/README.md +++ b/examples/hmr/README.md @@ -3,9 +3,22 @@ Hot Module Replacement (HMR) exchanges, adds, or removes modules while an application is running, without a full reload of the page. -## --hot +## true -To run this example, run this command in your console or terminal: +Enable webpack's [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) feature: + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + hot: true, + }, +}; +``` + +Usage via CLI: ```console npx webpack serve --open --hot @@ -31,10 +44,23 @@ In the devtools console you should see: You should also see the text on the page itself change to match your edits in `example.js`. -## --hot only +## only Enables Hot Module Replacement without page refresh as a fallback in case of build failures. +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + hot: "only", + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --hot only ``` diff --git a/examples/cli/hmr/app.js b/examples/hmr/app.js similarity index 100% rename from examples/cli/hmr/app.js rename to examples/hmr/app.js diff --git a/examples/cli/hmr/example.js b/examples/hmr/example.js similarity index 100% rename from examples/cli/hmr/example.js rename to examples/hmr/example.js diff --git a/examples/cli/host-and-port/webpack.config.js b/examples/hmr/webpack.config.js similarity index 81% rename from examples/cli/host-and-port/webpack.config.js rename to examples/hmr/webpack.config.js index 43b409e9d7..564acff99e 100644 --- a/examples/cli/host-and-port/webpack.config.js +++ b/examples/hmr/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/host-and-port/README.md b/examples/host-and-port/README.md similarity index 71% rename from examples/cli/host-and-port/README.md rename to examples/host-and-port/README.md index a3fecfa5f8..2cc8280721 100644 --- a/examples/cli/host-and-port/README.md +++ b/examples/host-and-port/README.md @@ -1,4 +1,4 @@ -# CLI: Host and Port Options +# Host and Port Options You may choose to wish to change the host and port on which `webpack-dev-server` will run. The `host` and `port` options allow for that. @@ -7,6 +7,20 @@ will run. The `host` and `port` options allow for that. ### IPv4 +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + host: "0.0.0.0", + port: 5000, + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --port 5000 --host 0.0.0.0 ``` @@ -15,6 +29,20 @@ npx webpack serve --open --port 5000 --host 0.0.0.0 _This also works with IPv6_ +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + host: "::", + port: 5000, + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --port 5000 --host :: ``` @@ -23,6 +51,18 @@ npx webpack serve --open --port 5000 --host :: Specifying `local-ip` as `host` will try to resolve the `host` option as your local `IPv4` address if available, if `IPv4` is not available it will try to resolve your local `IPv6` address. +```js +module.exports = { + // ... + devServer: { + host: "local-ip", + port: 5000, + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --port 5000 --host local-ip ``` @@ -31,6 +71,18 @@ npx webpack serve --open --port 5000 --host local-ip Specifying `local-ipv4` as `host` will try to resolve the `host` option as your local `IPv4` address. +```js +module.exports = { + // ... + devServer: { + host: "local-ipv4", + port: 5000, + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --port 5000 --host local-ipv4 ``` @@ -39,6 +91,18 @@ npx webpack serve --open --port 5000 --host local-ipv4 Specifying `local-ipv6` as `host` will try to resolve the `host` option as your local `IPv6` address. +```js +module.exports = { + // ... + devServer: { + host: "local-ipv6", + port: 5000, + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --port 5000 --host local-ipv6 ``` @@ -55,6 +119,17 @@ npx webpack serve --open --port 5000 --host local-ipv6 Tell the server to connect to a specific port with the following: +```js +module.exports = { + // ... + devServer: { + port: 9000, + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --port 9000 ``` @@ -68,6 +143,17 @@ npx webpack serve --open --port 9000 Specifying `auto` as `port` will try to connect the server to the default port `8080` and if not available it will automatically search for another free port. +```js +module.exports = { + // ... + devServer: { + port: "auto", + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --open --port auto ``` diff --git a/examples/cli/host-and-port/app.js b/examples/host-and-port/app.js similarity index 100% rename from examples/cli/host-and-port/app.js rename to examples/host-and-port/app.js diff --git a/examples/cli/compression/webpack.config.js b/examples/host-and-port/webpack.config.js similarity index 81% rename from examples/cli/compression/webpack.config.js rename to examples/host-and-port/webpack.config.js index 43b409e9d7..564acff99e 100644 --- a/examples/cli/compression/webpack.config.js +++ b/examples/host-and-port/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/https/README.md b/examples/https/README.md new file mode 100644 index 0000000000..2a04e83158 --- /dev/null +++ b/examples/https/README.md @@ -0,0 +1,60 @@ +# https options + +You may choose to wish to run `webpack-dev-server` on `https`. + +## https + +Use HTTPS protocol. + +```js +module.exports = { + // ... + devServer: { + https: true, + }, +}; +``` + +Usage via CLI: + +```console +npx webpack serve --open --https +``` + +## https options + +Customize `https` configuration with the following options: + +- `key`: Path to an SSL key. +- `pfx`: Path to an SSL pfx file. +- `cert`: Path to an SSL certificate. +- `cacert`: Path to an SSL CA certificate. +- `passphrase`: Passphrase for a pfx file. +- `requestCert`: Request for an SSL certificate. + +```js +module.exports = { + // ... + devServer: { + https: { + key: "./ssl/server.key", + pfx: "./ssl/server.pfx", + cert: "./ssl/server.crt", + cacert: "./ssl/ca.pem", + passphrase: "webpack-dev-server", + requestCert: true, + }, + }, +}; +``` + +Usage via CLI: + +```console +npx webpack serve --open --https-key ./ssl/server.key --https-pfx ./ssl/server.pfx --https-cert ./ssl/server.crt --https-cacert ./ssl/ca.pem --https-passphrase webpack-dev-server --https-request-cert +``` + +## What Should Happen + +1. The script should open `https://localhost:8080/` in your default browser. +2. You should see the text on the page itself change to read `Success!`. diff --git a/examples/cli/https/app.js b/examples/https/app.js similarity index 100% rename from examples/cli/https/app.js rename to examples/https/app.js diff --git a/examples/cli/https/ssl/ca.pem b/examples/https/ssl/ca.pem similarity index 100% rename from examples/cli/https/ssl/ca.pem rename to examples/https/ssl/ca.pem diff --git a/examples/cli/https/ssl/server.crt b/examples/https/ssl/server.crt similarity index 100% rename from examples/cli/https/ssl/server.crt rename to examples/https/ssl/server.crt diff --git a/examples/cli/https/ssl/server.key b/examples/https/ssl/server.key similarity index 100% rename from examples/cli/https/ssl/server.key rename to examples/https/ssl/server.key diff --git a/examples/cli/https/ssl/server.pfx b/examples/https/ssl/server.pfx similarity index 100% rename from examples/cli/https/ssl/server.pfx rename to examples/https/ssl/server.pfx diff --git a/examples/https/webpack.config.js b/examples/https/webpack.config.js new file mode 100644 index 0000000000..564acff99e --- /dev/null +++ b/examples/https/webpack.config.js @@ -0,0 +1,10 @@ +"use strict"; + +// our setup function adds behind-the-scenes bits to the config that all of our +// examples need +const { setup } = require("../util"); + +module.exports = setup({ + context: __dirname, + entry: "./app.js", +}); diff --git a/examples/cli/ipc/README.md b/examples/ipc/README.md similarity index 98% rename from examples/cli/ipc/README.md rename to examples/ipc/README.md index 38f79ee6a8..6d99d80430 100644 --- a/examples/cli/ipc/README.md +++ b/examples/ipc/README.md @@ -1,4 +1,4 @@ -# CLI: IPC +# IPC The Unix socket to listen to (instead of a [host](../host-and-port/README.md)). diff --git a/examples/cli/ipc/app.js b/examples/ipc/app.js similarity index 100% rename from examples/cli/ipc/app.js rename to examples/ipc/app.js diff --git a/examples/cli/ipc/webpack.config.js b/examples/ipc/webpack.config.js similarity index 95% rename from examples/cli/ipc/webpack.config.js rename to examples/ipc/webpack.config.js index 9ac3d8bf59..e8543d97fe 100644 --- a/examples/cli/ipc/webpack.config.js +++ b/examples/ipc/webpack.config.js @@ -4,7 +4,7 @@ const http = require("http"); const httpProxy = require("http-proxy"); // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/multi-compiler/README.md b/examples/multi-compiler/README.md similarity index 95% rename from examples/cli/multi-compiler/README.md rename to examples/multi-compiler/README.md index b5755164f3..c072485720 100644 --- a/examples/cli/multi-compiler/README.md +++ b/examples/multi-compiler/README.md @@ -1,4 +1,4 @@ -# CLI: Multi Compiler +# Multi Compiler `webpack-dev-server` should be able to compile multiple webpack configs. diff --git a/examples/cli/multi-compiler/app.js b/examples/multi-compiler/app.js similarity index 100% rename from examples/cli/multi-compiler/app.js rename to examples/multi-compiler/app.js diff --git a/examples/cli/multi-compiler/webpack.config.js b/examples/multi-compiler/webpack.config.js similarity index 82% rename from examples/cli/multi-compiler/webpack.config.js rename to examples/multi-compiler/webpack.config.js index 5c29866c7b..6366f481c2 100644 --- a/examples/cli/multi-compiler/webpack.config.js +++ b/examples/multi-compiler/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = [ setup({ diff --git a/examples/cli/node-false/README.md b/examples/node-false/README.md similarity index 84% rename from examples/cli/node-false/README.md rename to examples/node-false/README.md index 04dc87781a..b462f863ad 100644 --- a/examples/cli/node-false/README.md +++ b/examples/node-false/README.md @@ -1,6 +1,6 @@ -# CLI: Webpack `node` Option +# Webpack `node` Option -```shell +```console npx webpack serve --open ``` diff --git a/examples/cli/node-false/app.js b/examples/node-false/app.js similarity index 100% rename from examples/cli/node-false/app.js rename to examples/node-false/app.js diff --git a/examples/cli/node-false/webpack.config.js b/examples/node-false/webpack.config.js similarity index 82% rename from examples/cli/node-false/webpack.config.js rename to examples/node-false/webpack.config.js index 69640a6933..0dd23f9c7c 100644 --- a/examples/cli/node-false/webpack.config.js +++ b/examples/node-false/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/open-target-multiple/README.md b/examples/open-target-multiple/README.md similarity index 72% rename from examples/cli/open-target-multiple/README.md rename to examples/open-target-multiple/README.md index 1945e17b0b..f089631968 100644 --- a/examples/cli/open-target-multiple/README.md +++ b/examples/open-target-multiple/README.md @@ -1,4 +1,19 @@ -# CLI: Open Target Option (Multiple) +# Open Target Option (Multiple) + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + open: { + target: ["/example1.html", "example2.html"], + }, + }, +}; +``` + +Usage via CLI: ```console npx webpack serve --open-target example1.html --open-target example2.html diff --git a/examples/cli/open-target-multiple/app1.js b/examples/open-target-multiple/app1.js similarity index 100% rename from examples/cli/open-target-multiple/app1.js rename to examples/open-target-multiple/app1.js diff --git a/examples/cli/open-target-multiple/app2.js b/examples/open-target-multiple/app2.js similarity index 100% rename from examples/cli/open-target-multiple/app2.js rename to examples/open-target-multiple/app2.js diff --git a/examples/cli/open-target-multiple/webpack.config.js b/examples/open-target-multiple/webpack.config.js similarity index 95% rename from examples/cli/open-target-multiple/webpack.config.js rename to examples/open-target-multiple/webpack.config.js index 56028d9d71..24513c2ff9 100644 --- a/examples/cli/open-target-multiple/webpack.config.js +++ b/examples/open-target-multiple/webpack.config.js @@ -3,7 +3,7 @@ const HtmlWebpackPlugin = require("html-webpack-plugin"); // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = [ setup({ diff --git a/examples/open-target/README.md b/examples/open-target/README.md new file mode 100644 index 0000000000..04b930e4c8 --- /dev/null +++ b/examples/open-target/README.md @@ -0,0 +1,95 @@ +# Open Target Option + +## Open default generated URL in browser: + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + open: { + target: "", + }, + }, +}; +``` + +Usage via CLI: + +``` +npx webpack serve --open-target +``` + +## Open specific page in browser: + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + open: { + target: "/example.html#page1", + }, + }, +}; +``` + +Usage via CLI: + +``` +npx webpack serve --open-target /example.html#page1 +``` + +## Open specific browser: + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + open: { + app: "firefox", + }, + }, +}; +``` + +Usage via CLI: + +``` +npx webpack serve --open-app firefox +``` + +## Open specific page in specific browser: + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + open: { + target: "/example.html#page1", + app: "firefox", + }, + }, +}; +``` + +Usage via CLI: + +``` +npx webpack serve --open-target example.html#page1 --open-app firefox +``` + +Some applications may consist of multiple pages. During development it may +be useful to directly open a particular page. The page to open may be specified +as the argument to the `open-target` option. + +## What Should Happen + +The script should open `http://localhost:8080/example.html#page1` in your +default/specified browser. You should see the text on the page itself change to read `Success!`. diff --git a/examples/cli/open-target/app.js b/examples/open-target/app.js similarity index 100% rename from examples/cli/open-target/app.js rename to examples/open-target/app.js diff --git a/examples/cli/open-target/webpack.config.js b/examples/open-target/webpack.config.js similarity index 90% rename from examples/cli/open-target/webpack.config.js rename to examples/open-target/webpack.config.js index 9023c59a2f..7fc07c6821 100644 --- a/examples/cli/open-target/webpack.config.js +++ b/examples/open-target/webpack.config.js @@ -3,7 +3,7 @@ const HtmlWebpackPlugin = require("html-webpack-plugin"); // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/overlay/README.md b/examples/overlay/README.md similarity index 67% rename from examples/cli/overlay/README.md rename to examples/overlay/README.md index d518ccd7f6..6644fa4929 100644 --- a/examples/cli/overlay/README.md +++ b/examples/overlay/README.md @@ -1,4 +1,19 @@ -# CLI: --client-overlay option +# client.overlay option + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + client: { + overlay: true, + }, + }, +}; +``` + +Usage via CLI: ```shell npx webpack serve --open --client-overlay diff --git a/examples/cli/overlay/app.js b/examples/overlay/app.js similarity index 100% rename from examples/cli/overlay/app.js rename to examples/overlay/app.js diff --git a/examples/cli/overlay/webpack.config.js b/examples/overlay/webpack.config.js similarity index 84% rename from examples/cli/overlay/webpack.config.js rename to examples/overlay/webpack.config.js index 20e126f66e..e9a5a77b2e 100644 --- a/examples/cli/overlay/webpack.config.js +++ b/examples/overlay/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/progress/README.md b/examples/progress/README.md similarity index 66% rename from examples/cli/progress/README.md rename to examples/progress/README.md index 43cb662cab..8d2d742172 100644 --- a/examples/cli/progress/README.md +++ b/examples/progress/README.md @@ -1,4 +1,19 @@ -# CLI: Progress Option +# client.progress Option + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + client: { + progress: true, + }, + }, +}; +``` + +Usage via CLI: ```shell npx webpack serve --open --client-progress diff --git a/examples/cli/progress/app.js b/examples/progress/app.js similarity index 100% rename from examples/cli/progress/app.js rename to examples/progress/app.js diff --git a/examples/progress/webpack.config.js b/examples/progress/webpack.config.js new file mode 100644 index 0000000000..564acff99e --- /dev/null +++ b/examples/progress/webpack.config.js @@ -0,0 +1,10 @@ +"use strict"; + +// our setup function adds behind-the-scenes bits to the config that all of our +// examples need +const { setup } = require("../util"); + +module.exports = setup({ + context: __dirname, + entry: "./app.js", +}); diff --git a/examples/cli/watch-static/README.md b/examples/watch-static/README.md similarity index 88% rename from examples/cli/watch-static/README.md rename to examples/watch-static/README.md index 28fa1932dd..6bd40d9f70 100644 --- a/examples/cli/watch-static/README.md +++ b/examples/watch-static/README.md @@ -1,7 +1,20 @@ -# CLI: Static +# Static ## Watching a single directory +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + static: ["assets"], + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --static assets --open ``` diff --git a/examples/cli/watch-static/app.js b/examples/watch-static/app.js similarity index 100% rename from examples/cli/watch-static/app.js rename to examples/watch-static/app.js diff --git a/examples/cli/watch-static/assets/index.html b/examples/watch-static/assets/index.html similarity index 100% rename from examples/cli/watch-static/assets/index.html rename to examples/watch-static/assets/index.html diff --git a/examples/cli/watch-static/css/styles.css b/examples/watch-static/css/styles.css similarity index 100% rename from examples/cli/watch-static/css/styles.css rename to examples/watch-static/css/styles.css diff --git a/examples/cli/watch-static/webpack.config.js b/examples/watch-static/webpack.config.js similarity index 85% rename from examples/cli/watch-static/webpack.config.js rename to examples/watch-static/webpack.config.js index 9f31452ce6..438cff8ada 100644 --- a/examples/cli/watch-static/webpack.config.js +++ b/examples/watch-static/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/examples/cli/web-socket-server/README.md b/examples/web-socket-server/README.md similarity index 64% rename from examples/cli/web-socket-server/README.md rename to examples/web-socket-server/README.md index bbd61dd78d..95478c8e92 100644 --- a/examples/cli/web-socket-server/README.md +++ b/examples/web-socket-server/README.md @@ -1,4 +1,4 @@ -# CLI: web-socket-server +# web-socket-server To create a custom server implementation. @@ -6,6 +6,19 @@ To create a custom server implementation. This mode uses [SockJS-node](https://github.com/sockjs/sockjs-node) as a server. +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + webSocketServer: "sockjs", + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --web-socket-server sockjs --open ``` @@ -14,6 +27,19 @@ npx webpack serve --web-socket-server sockjs --open This mode uses [ws](https://github.com/websockets/ws) as a server. +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + webSocketServer: "ws", + }, +}; +``` + +Usage via CLI: + ```console npx webpack serve --web-socket-server ws --open ``` diff --git a/examples/cli/web-socket-server/app.js b/examples/web-socket-server/app.js similarity index 100% rename from examples/cli/web-socket-server/app.js rename to examples/web-socket-server/app.js diff --git a/examples/web-socket-server/webpack.config.js b/examples/web-socket-server/webpack.config.js new file mode 100644 index 0000000000..564acff99e --- /dev/null +++ b/examples/web-socket-server/webpack.config.js @@ -0,0 +1,10 @@ +"use strict"; + +// our setup function adds behind-the-scenes bits to the config that all of our +// examples need +const { setup } = require("../util"); + +module.exports = setup({ + context: __dirname, + entry: "./app.js", +}); diff --git a/examples/cli/web-socket-url/README.md b/examples/web-socket-url/README.md similarity index 69% rename from examples/cli/web-socket-url/README.md rename to examples/web-socket-url/README.md index 58b01687ce..6bb3175b30 100644 --- a/examples/cli/web-socket-url/README.md +++ b/examples/web-socket-url/README.md @@ -1,4 +1,19 @@ -# CLI: Web Socket URL Option Protocol +# Web Socket URL Option Protocol + +**webpack.config.js** + +```js +module.exports = { + // ... + devServer: { + client: { + webSocketURL: "ws://localhost:8080", + }, + }, +}; +``` + +Usage via CLI: ```console npx webpack serve diff --git a/examples/cli/web-socket-url/app.js b/examples/web-socket-url/app.js similarity index 100% rename from examples/cli/web-socket-url/app.js rename to examples/web-socket-url/app.js diff --git a/examples/cli/web-socket-url/index.html b/examples/web-socket-url/index.html similarity index 100% rename from examples/cli/web-socket-url/index.html rename to examples/web-socket-url/index.html diff --git a/examples/cli/web-socket-url/webpack.config.js b/examples/web-socket-url/webpack.config.js similarity index 88% rename from examples/cli/web-socket-url/webpack.config.js rename to examples/web-socket-url/webpack.config.js index 8fe4b5d921..b27ba4572e 100644 --- a/examples/cli/web-socket-url/webpack.config.js +++ b/examples/web-socket-url/webpack.config.js @@ -2,7 +2,7 @@ // our setup function adds behind-the-scenes bits to the config that all of our // examples need -const { setup } = require("../../util"); +const { setup } = require("../util"); module.exports = setup({ context: __dirname, diff --git a/test/cli/basic.test.js b/test/cli/basic.test.js index c6c4c4ad3e..1ce1e6241b 100644 --- a/test/cli/basic.test.js +++ b/test/cli/basic.test.js @@ -102,7 +102,7 @@ describe("basic", () => { ); const examplePath = path.resolve( __dirname, - "../../examples/cli/web-socket-url" + "../../examples/web-socket-url" ); const cp = execa("node", ["--port", port, cliPath], { cwd: examplePath }); @@ -153,7 +153,7 @@ describe("basic", () => { ); const examplePath = path.resolve( __dirname, - "../../examples/cli/web-socket-url" + "../../examples/web-socket-url" ); const cp = execa( "node",