path: root/node_modules/webpack-serve/README.md

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]

# webpack-serve

A lean, modern, and flexible webpack development server

## Browser Support

Because this module leverages _native_ `WebSockets` via `webpack-hot-client`,
the browser support for this module is limited to only those browsers which
support native `WebSocket`. That typically means the last two major versions
of a particular browser. You may view a table of
[compatible browsers here](https://caniuse.com/#feat=websockets).

_Note: We won't be accepting requests for changes to this facet of the module._

## Getting Started

To begin, you'll need to install `webpack-serve`:

```console
$ npm install webpack-serve --save-dev
```

## CLI

```console
$ webpack-serve --help

  Options
    --config            The webpack config to serve. Alias for <config>.
    --content           The path from which content will be served
                        Default: process.cwd()
    --dev               A JSON object containing options for webpack-dev-middleware
    --help              Show usage information and the options listed here.
    --host              The host the app should bind to
    --hot               A JSON object containing options for webpack-hot-client
    --http2             Instruct the server to use HTTP2
    --https-cert        Specify a cert to enable https. Must be paired with a key
    --https-key         Specify a key to enable https. Must be paired with a cert
    --https-pass        Specify a passphrase to enable https. Must be paired with a pfx file
    --https-pfx         Specify a pfx file to enable https. Must be paired with a passphrase
    --log-level         Limit all process console messages to a specific level and above
                        Levels: trace, debug, info, warn, error, silent
    --log-time          Instruct the logger for webpack-serve and dependencies to display a timestamp
    --no-clipboard      Instructs the server not to copy the server URI to the clipboard when starting
    --no-hot            Instruct the client not to apply Hot Module Replacement patches
    --no-reload         Instruct middleware {italic not} to reload the page for build errors
    --open              Instruct the app to open in the default browser
    --open-app          The name of the app to open the app within, or an array
                        containing the app name and arguments for the app
    --open-path         The path with the app a browser should open to
    --port              The port the app should listen on
    --require, -r       Preload one or more modules before loading the webpack configuration
    --version           Display the webpack-serve version

  Examples
    $ webpack-serve ./webpack.config.js --no-reload
    $ webpack-serve --config ./webpack.config.js --port 1337
    $ webpack-serve --port 1337  # config can be omitted for webpack v4+ only
```

_Note: The CLI will use your local install of webpack-serve when available,
even when run globally._

### Running the CLI

There are a few variations for using the base CLI command, and starting
`webpack-serve`:

```console
  $ webpack-serve ./webpack.config.js
  $ webpack-serve --config ./webpack.config.js
```

Those two commands are synonymous. Both instruct `webpack-serve` to load the
config from the specified path. We left the flag in there because some folks
like to be verbose, so why not.

```console
  $ webpack-serve
```

And for the folks using webpack v4 or higher, you can instruct `webpack-serve` to
kick off a webpack build without specifying a config. Keep in mind that this will
apply the default config within webpack, and your project must conform to that
for a successful build to happen.

When running `$ webpack-serve` without arguments in webpack v3 and lower, the CLI
will display help and usage information. In order to accommodate the zero-config
changes in webpack v4, users of webpack v4 will need to use the `--help` flag to
display the same information.

## `webpack-serve` Config

You can store and define configuration / options for `webpack-serve` in a number
of different ways. This module leverages [cosmiconfig](https://github.com/davidtheclark/cosmiconfig),
which allows you to define `webpack-serve` options in the following ways:

- in your package.json file in a `serve` property
- in a `.serverc` or `.serverc.json` file, in either JSON or YML.
- in a `serve.config.js` file which exports a CommonJS module (just like webpack).

It's most common to keep `serve` options in your `webpack.config.js` (see below),
however, you can utilize any of the options above _in tandem_ with
`webpack.config.js`, and the options from the two sources will be merged. This
can be useful for setups with multiple configs that share common options for
`webpack-serve`, but require subtle differences.

### Webpack Config `serve` Property

`webpack-serve` supports the `serve` property in your webpack config file, which
may contain any of the supported [options](#options).

### Setting the Config `mode`

Should you find that the `mode` property of your webpack config file needs to be
set dynamically the following pattern can be used:

```json
  mode: process.env.WEBPACK_SERVE ? 'development' : 'production',
```

## API

When using the API directly, the main entry point  is the `serve` function, which
is the default export of the module.

```js
const serve = require('webpack-serve');
const config = require('./webpack.config.js');

serve({ config });
```

### serve([options])

Returns [a `Promise` which resolves] an `Object` containing:

- `close()` *(Function)* - Closes the server and its dependencies.
- `on(eventName, fn)` *(Function)* - Binds a serve event to a function. See
[Events](#events).

#### options

Type: `Object`

Options for initializing and controlling the server provided.

##### add

Please see [Add-On Features](#add-on-features).

##### compiler

Type: `webpack`  
Default: `null`

An instance of a `webpack` compiler. A passed compiler's config will take
precedence over `config` passed in options.

_Note: Any `serve` configuration must be removed from the webpack config used
to create the compiler instance, before you attempt to create it, as it's not
a valid webpack config property._

##### config

Type: `Object`  
Default: `{}`

An object containing the configuration for creating a new `webpack` compiler
instance.

##### content

Type: `String|[String]`  
Default: `process.cwd()`

The path, or array of paths, from which content will be served.

<!-- intentionally out of alphabetic order -->
##### clipboard

Type: `Boolean`  
Default: `true`

If true, the server will copy the server URI to the clipboard when the server is
started.

##### dev

Type: `Object`  
Default: `{ publicPath: '/' }`

An object containing options for [webpack-dev-middleware][dev-ware].

##### host

Type: `String`  
Default: `'localhost'`

Sets the host that the server will listen on. eg. `'10.10.10.1'`

_Note: This value must match any value specified for `hot.host` or
`hot.host.server`, otherwise `webpack-serve` will throw an error. This
requirement ensures that the `koa` server and `WebSocket` server play nice
together._

##### hot

Type: `Object|Boolean`  
Default: `{}`

An object containing options for [webpack-hot-client][hot-client].  

As of `v0.2.1` setting this to `false` will completely disable `webpack-hot-client`
and all automatic Hot Module Replacement functionality. This is akin to the
`--no-hot-client` CLI flag.

##### http2

Type: `Boolean`  
Default: `false`

If using Node v9 or greater, setting this option to `true` will enable HTTP2
support.

##### https

Type: `Object`  
Default: `null`

Passing this option will instruct `webpack-serve` to create and serve the webpack
bundle and accompanying content through a secure server. The object should
contain properties matching:

```js
{
  key: fs.readFileSync('...key'),   // Private keys in PEM format.
  cert: fs.readFileSync('...cert'), // Cert chains in PEM format.
  pfx: <String>,                    // PFX or PKCS12 encoded private key and certificate chain.
  passphrase: <String>              // A shared passphrase used for a single private key and/or a PFX.
}
```

See the [Node documentation][https-opts] for more information. For SSL
Certificate generation, please read the
[SSL Certificates for HTTPS](#ssl-certificates-for-https) section.

##### logLevel

Type: `String`  
Default: `info`

Instructs `webpack-serve` to output information to the console/terminal at levels
higher than the specified level. Valid levels:

```js
[
  'trace',
  'debug',
  'info',
  'warn',
  'error'
]
```

##### logTime

Type: `Boolean`  
Default: `false`

Instruct `webpack-serve` to prepend each line of log output with a `[HH:mm:ss]`
timestamp.

##### on

Type: `Object`  
Default: `null`

While running `webpack-serve` from the command line, it can sometimes be useful
to subscribe to events from the module's event bus _within your config_. This
option can be used for that purpose. The option's value must be an `Object`
matching a `key:handler`, `String: Function` pattern. eg:

```js
on: {
  'listening': () => { console.log('listening'); }
}
```

##### open

Type: `Boolean|Object`  
Default: `false`

Instruct the module to open the served bundle in a browser. Accepts an `Object`
that matches:

```js
{
  app: <String>, // The proper name of the browser app to open.
  path: <String> // The url path on the server to open.
}
```

_Note: Using the `open` option will disable the `clipboard` option._

##### port

Type: `Number`  
Default: `8080`

The port the server should listen on.

## Events

The server created by `webpack-serve` emits select events which can be
subscribed to. All events are emitted with a single `Object` parameter,
containing named properties for relevant data.

For example:

```js
const serve = require('webpack-serve');
const config = require('./webpack.config.js');

serve({ config }).then((server) => {
  server.on('listening', ({ server, options }) => {
    console.log('happy fun time');
  });
});
```

#### build-started

Arguments:  
  [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_

Emitted when a compiler has started a build.

#### build-finished

Arguments:  
  [`Stats`](https://webpack.js.org/api/node/#stats-object) _stats_  
  [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_

Emitted when a compiler has finished a build.

#### compiler-error

Arguments:  
  [`Stats`](https://webpack.js.org/api/node/#stats-tojson-options-) _json_
  [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_

Emitted when a compiler has encountered and error, or a build has errors.

#### compiler-warning

Arguments:  
  [`Stats`](https://webpack.js.org/api/node/#stats-tojson-options-) _json_
  [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_

Emitted when a compiler has encountered a warning, or a build has warnings.

#### listening

Arguments:  
  `Koa` _server_  
  `Object` _options_

Emitted when the server begins listening for connections.

## SSL Certificates for HTTPS

Unlike webpack-dev-server, `webpack-serve` does not ship with SSL Certificate
generation, nor does it ship with a built-in certificate for use with HTTPS
configurations. This is due largely in part to past security concerns and the
complexity of use-cases in the webpack ecosystem.

We do however, recommend a path for users to generate their own SSL Certificates
safely and efficiently. That path resides in
[`devcert-cli`](https://github.com/davewasmer/devcert-cli); an excellent project
that automates the creation of trusted SSL certificates that will work
wonderfully with `webpack-serve`.

## Add-on Features

A core tenant of `webpack-serve` is to stay lean in terms of feature set, and to
empower users with familiar and easily portable patterns to implement the same
features that those familiar with `webpack-dev-server` have come to rely on. This
makes the module far easier to maintain, which ultimately benefits the user.

Luckily, flexibility baked into `webpack-serve` makes it a snap to add-on features.
You can leverage this by using the `add` option. The value of the option should
be a `Function` matching the following signature:

```js
add: (app, middleware, options) => {
  // ...
}
```

### `add` Function Parameters

- `app` The underlying Koa app
- `middleware` An object containing accessor functions to call both
`webpack-dev-middleware` and the `koa-static` middleware.
- `options` - The internal options object used by `webpack-serve`

Some add-on patterns may require changing the order of middleware used in the
`app`. For instance, if adding routes or using a separate router with the `app`
where routes must be added last, you'll need to call the `middleware` functions
early on. `webpack-serve` recognizes these calls and will not execute them again.
If these calls were omitted, `webpack-serve` would execute both in the default,
last in line, order.

```js
add: (app, middleware, options) => {
  // since we're manipulating the order of middleware added, we need to handle
  // adding these two internal middleware functions.
  middleware.webpack();
  middleware.content();

  // router *must* be the last middleware added
  app.use(router.routes());
}
```

Listed below are some of the add-on patterns and recipes that can be found in
[docs/addons](docs/addons):

- [bonjour](docs/addons/bonjour.config.js)
- [compress](docs/addons/compress)
- [historyApiFallback](docs/addons/history-fallback.config.js)
- [proxy + history fallback](docs/addons/proxy-history-fallback.config.js)
- [proxy + router](docs/addons/proxy-router.config.js)
- [reuse Chrome tab](docs/addons/reuse-chrome-tab)
- [staticOptions](docs/addons/static-content-options.config.js)
- [useLocalIp](docs/addons/local-ip.config.js)
- [watch content](docs/addons/watch-content.config.js)

### Community Add-ons

_Note: The list below contains `webpack-serve` add-ons created by the community.
Inclusion in the list does not imply a module is preferred or recommended
over others._

- [webpack-serve-waitpage](https://github.com/elisherer/webpack-serve-waitpage):
Displays build progress in the client during complilation.

## Contributing

We welcome your contributions! Please have a read of
[CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to get involved.

## License

#### [MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/webpack-serve.svg
[npm-url]: https://npmjs.com/package/webpack-serve

[node]: https://img.shields.io/node/v/webpack-serve.svg
[node-url]: https://nodejs.org

[deps]: https://david-dm.org/webpack-contrib/webpack-serve.svg
[deps-url]: https://david-dm.org/webpack-contrib/webpack-serve

[tests]: 	https://img.shields.io/circleci/project/github/webpack-contrib/webpack-serve.svg
[tests-url]: https://circleci.com/gh/webpack-contrib/webpack-serve/tree/master

[cover]: https://codecov.io/gh/webpack-contrib/webpack-serve/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/webpack-serve

[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack

[dev-ware]: https://github.com/webpack/webpack-dev-middleware#options
[hot-client]: https://github.com/webpack-contrib/webpack-hot-client#options
[https-opts]: https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options