armano2/webpack-serve

A lean, modern, and flexible webpack development server

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.

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:

$ npm install webpack-serve --save-dev

CLI

$ 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:

  $ 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.

  $ 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, 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.

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:

  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.

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.

options

Type: Object

Options for initializing and controlling the server provided.

add

Please see 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.

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.

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.

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:

{
  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 for more information. For SSL Certificate generation, please read the 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:

[
  '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:

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:

{
  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:

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 compiler

Emitted when a compiler has started a build.

build-finished

Arguments:
Stats stats
Compiler compiler

Emitted when a compiler has finished a build.

compiler-error

Arguments:
Stats json Compiler compiler

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

compiler-warning

Arguments:
Stats json Compiler 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; 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:

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.

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:

• bonjour
• compress
• historyApiFallback
• proxy + history fallback
• proxy + router
• reuse Chrome tab
• staticOptions
• useLocalIp
• watch content

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: Displays build progress in the client during complilation.

Contributing

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

License

MIT