[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]
# webpack-serve
A lean, modern, and flexible webpack development server
## Requirements
This module requires a minimum of Node.js v6.9.0 and Webpack v4.0.0.
## 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
A lean, modern, and flexible webpack development server
Usage
$ webpack-serve [...options]
Options
--clipboard Specify whether or not the server should copy the server URI to the clipboard (default: true)
--config The webpack config to serve. Alias for
--content The path from which static content will be served (default: process.cwd)
--dev-ware Set options for webpack-dev-middleware. e.g. --dev.publicPath /
--help Show usage information and the options listed here.
--host The host the app should bind to
--hot-client Set options for webpack-hot-client. e.g. --hot-client.host localhost
Use --no-hot-client to disable webpack-hot-client
--http2 Instruct the server to use HTTP2
--https-cert Specify a filesystem path of an SSL certificate. Must be paired with a key
--https-key Specify a filesystem path of an SSL key. 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 filesystem path of an SSL pfx file. 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
--hmr Specify whether or not the client should apply Hot Module Replacement patches (default: true)
--reload Specify whether or not the middleware should reload the page for build errors (default: true)
--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. Default: 8080
--require, -r Preload one or more modules before loading the webpack configuration
--version Display the webpack-command version
Note: Any boolean flag can be prefixed with 'no-' instead of specifying a value.
e.g. --no-reload rather than --reload=false
Examples
$ webpack-serve ./webpack.config.js --no-reload
$ webpack-serve --config ./webpack.config.js --port 1337
$ webpack-serve # 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
```
You may also instruct `webpack-serve` to kick off a webpack build without
specifying a config. This will apply the zero-config defaults within webpack,
and your project must conform to that for a successful build to happen.
## `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 argv = {};
const config = require('./webpack.config.js');
serve(argv, { config }).then((result) => {
// ...
});
```
## `serve(argv, options)`
Returns: `Promise`
Resolves: `
