{"id":13526912,"url":"https://github.com/webpack-contrib/webpack-serve","last_synced_at":"2025-09-28T21:31:04.090Z","repository":{"id":57097213,"uuid":"115440393","full_name":"webpack-contrib/webpack-serve","owner":"webpack-contrib","description":"Repository has moved:","archived":true,"fork":false,"pushed_at":"2018-09-18T09:57:09.000Z","size":678,"stargazers_count":1092,"open_issues_count":0,"forks_count":83,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-01-18T18:54:35.490Z","etag":null,"topics":["development","devserver","middleware","server","webpack"],"latest_commit_sha":null,"homepage":"https://github.com/shellscape/webpack-serve","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webpack-contrib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2017-12-26T17:06:30.000Z","updated_at":"2024-11-30T08:26:48.000Z","dependencies_parsed_at":"2022-08-20T18:10:21.296Z","dependency_job_id":null,"html_url":"https://github.com/webpack-contrib/webpack-serve","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fwebpack-serve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fwebpack-serve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fwebpack-serve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fwebpack-serve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webpack-contrib","download_url":"https://codeload.github.com/webpack-contrib/webpack-serve/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234563141,"owners_count":18853060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["development","devserver","middleware","server","webpack"],"created_at":"2024-08-01T06:01:37.298Z","updated_at":"2025-09-28T21:30:58.722Z","avatar_url":"https://github.com/webpack-contrib.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/webpack/webpack\"\u003e\n    \u003cimg width=\"200\" height=\"200\" src=\"https://webpack.js.org/assets/icon-square-big.svg\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n[![npm][npm]][npm-url]\n[![node][node]][node-url]\n[![deps][deps]][deps-url]\n[![tests][tests]][tests-url]\n[![coverage][cover]][cover-url]\n[![chat][chat]][chat-url]\n[![size][size]][size-url]\n\n# webpack-serve\n\nDEPRECATED. Please use `webpack-dev-server` (he is in support and update mode again). Feel free to create a issue if some features are not implemented in `webpack-dev-server`. \n\nWhy deprecated `webpack-serve` ?\n- The author stopped developing the package.\n- Two development servers are misleading for developers.\n- Hard to maintain two packages with same purpose.\n- Some `dependencies` are not available to fixes/implement new features/etc (https://www.npmjs.com/package/webpack-hot-client and https://github.com/shellscape/koa-static) and there's nothing we can do here.\n- `webpack-dev-server` is stable.\n\nThanks for using `webpack`! We apologize for the inconvenience. In the future, we will avoid such situations.\n\nUse `gitter` and/or `slack` if you have questions.\n\n-----\n\nA lean, modern, and flexible webpack development server\n\n## Requirements\n\nThis module requires a minimum of Node.js v6.9.0 and Webpack v4.0.0.\n\n## Browser Support\n\nBecause this module leverages _native_ `WebSockets` via `webpack-hot-client`,\nthe browser support for this module is limited to only those browsers which\nsupport native `WebSocket`. That typically means the last two major versions\nof a particular browser. You may view a table of\n[compatible browsers here](https://caniuse.com/#feat=websockets).\n\n_Note: We won't be accepting requests for changes to this facet of the module._\n\n## Getting Started\n\nTo begin, you'll need to install `webpack-serve`:\n\n```console\n$ npm install webpack-serve --save-dev\n```\n\n## CLI\n\n```console\n$ webpack-serve --help\n\nA lean, modern, and flexible webpack development server\n\nUsage\n  $ webpack-serve \u003cconfig\u003e [...options]\n\nOptions\n  --clipboard      Specify whether or not the server should copy the server URI to the clipboard (default: true)\n  --config         The webpack config to serve. Alias for \u003cconfig\u003e\n  --content        The path from which static content will be served (default: process.cwd)\n  --dev-ware       Set options for webpack-dev-middleware. e.g. --dev-ware.publicPath /\n  --help           Show usage information and the options listed here.\n  --host           The host the app should bind to\n  --hot-client     Set options for webpack-hot-client. e.g. --hot-client.host localhost\n                   Use --no-hot-client to disable webpack-hot-client\n  --http2          Instruct the server to use HTTP2\n  --https-cert     Specify a filesystem path of an SSL certificate. Must be paired with a key\n  --https-key      Specify a filesystem path of an SSL key. Must be paired with a cert\n  --https-pass     Specify a passphrase to enable https. Must be paired with a pfx file\n  --https-pfx      Specify a filesystem path of an SSL pfx file. Must be paired with a passphrase\n  --log-level      Limit all process console messages to a specific level and above\n                   Levels: trace, debug, info, warn, error, silent\n  --log-time       Instruct the logger for webpack-serve and dependencies to display a timestamp\n  --hmr            Specify whether or not the client should apply Hot Module Replacement patches (default: true)\n  --reload         Specify whether or not the middleware should reload the page for build errors (default: true)\n  --open           Instruct the app to open in the default browser\n  --open-app       The name of the app to open the app within, or an array\n                   containing the app name and arguments for the app\n  --open-path      The path with the app a browser should open to\n  --port           The port the app should listen on. Default: 8080\n  --require, -r    Preload one or more modules before loading the webpack configuration\n  --version        Display the webpack-serve version\n\nNote: Any boolean flag can be prefixed with 'no-' instead of specifying a value.\ne.g. --no-reload rather than --reload=false\n\nExamples\n  $ webpack-serve ./webpack.config.js --no-reload\n  $ webpack-serve --config ./webpack.config.js --port 1337\n  $ webpack-serve # config can be omitted for webpack v4+ only\n```\n\n_Note: The CLI will use your local install of webpack-serve when available,\neven when run globally._\n\n### Running the CLI\n\nThere are a few variations for using the base CLI command, and starting\n`webpack-serve`:\n\n```console\n$ webpack-serve ./webpack.config.js\n$ webpack-serve --config ./webpack.config.js\n```\n\nThose two commands are synonymous. Both instruct `webpack-serve` to load the\nconfig from the specified path. We left the flag in there because some folks\nlike to be verbose, so why not.\n\n```console\n$ webpack-serve\n```\n\nYou may also instruct `webpack-serve` to kick off a webpack build without\nspecifying a config. This will apply the zero-config defaults within webpack,\nand your project must conform to that for a successful build to happen.\n\n## `webpack-serve` Config\n\nYou can store and define configuration / options for `webpack-serve` in a number\nof different ways. This module leverages\n[cosmiconfig](https://github.com/davidtheclark/cosmiconfig), which allows you to\ndefine `webpack-serve` options in the following ways:\n\n- in your package.json file in a `serve` property\n- in a `.serverc` or `.serverc.json` file, in either JSON or YML.\n- in a `serve.config.js` file which exports a CommonJS module (just like webpack).\n\nIt's most common to keep `serve` options in your `webpack.config.js` (see below),\nhowever, you can utilize any of the options above _in tandem_ with\n`webpack.config.js`, and the options from the two sources will be merged. This\ncan be useful for setups with multiple configs that share common options for\n`webpack-serve`, but require subtle differences.\n\n### `webpack.config.js` Example\n\n```js\nconst path = require('path');\n\nmodule.exports = {\n  context: __dirname,\n  devtool: 'source-map',\n  entry: ['./app.js'],\n  output: {\n    filename: './output.js',\n    path: path.resolve(__dirname),\n  },\n  serve: {},\n};\n```\n\n### Webpack Config `serve` Property\n\n`webpack-serve` supports the `serve` property in your webpack config file, which\nmay contain any of the supported [options](#options).\n\n### Setting the Config `mode`\n\nShould you find that the `mode` property of your webpack config file needs to be\nset dynamically the following pattern can be used:\n\n```json\nmode: process.env.WEBPACK_SERVE ? 'development' : 'production',\n```\n\n## API\n\nWhen using the API directly, the main entry point  is the `serve` function, which\nis the default export of the module.\n\n```js\nconst serve = require('webpack-serve');\nconst argv = {};\nconst config = require('./webpack.config.js');\n\nserve(argv, { config }).then((result) =\u003e {\n  // ...\n});\n```\n\n## `serve(argv, options)`\n\nReturns: `Promise`  \nResolves: `\u003cObject\u003e result`\n\n### `result.app`\n\nType: `Koa`\n\nAn instance of a `Koa` application, extended with a `server` property, and\n`stop` method, which is used to programatically stop the server.\n\n### `result.on`\n\nType: `Function`\n\nA function which binds a serve event-name to a function. See [Events](#events).\n\n### `result.options`\n\nType: `Object`\n\nAccess to a frozen copy of the internal `options` object used by the module.\n\n### `argv`\n\nType: `Object`  \n_Required_\n\nAn object containing the parsed result from either\n[`minimist`](https://github.com/substack/minimist) or\n[`yargs-parser`](https://github.com/yargs/yargs-parser).\n\n### `options`\n\nType: `Object`  \n_Required_\n\nAn object specifying options used to configure the server.\n\n### `options.add`\n\nPlease see [Add-On Features](#add-on-features).\n\n### `options.compiler`\n\nType: `webpack`  \nDefault: `null`\n\nAn instance of a `webpack` compiler. A passed compiler's config will take\nprecedence over `config` passed in options.\n\n_Note: Any `serve` configuration must be removed from the webpack config used\nto create the compiler instance, before you attempt to create it, as it's not\na valid webpack config property._\n\n### `options.config`\n\nType: `Object`  \nDefault: `{}`\n\nAn object containing the configuration for creating a new `webpack` compiler\ninstance.\n\n### `options.content`\n\nType: `String|[String]`  \nDefault: `process.cwd()`\n\nThe path, or array of paths, from which content will be served. Paths specified\nhere should be absolute, or fully-qualified and resolvable by the filesystem.\n\n_Note: By default the files generated by webpack take precedence\nover static files served from `content` paths._\n \nTo instruct the server to give static files precedence, use the `add`\noption, and call `middleware.content()` before `middleware.webpack()`:\n\n```js\nadd: (app, middleware, options) =\u003e {\n  middleware.content();\n  middleware.webpack();\n};\n```\n \n Read more about the add option in [Add-On Features](#add-on-features).\n\n\u003c!-- intentionally out of alphabetic order --\u003e\n### `options.clipboard`\n\nType: `Boolean`  \nDefault: `true`\n\nIf true, the server will copy the server URI to the clipboard when the server is\nstarted.\n\n### `options.devMiddleware`\n\nType: `Object`  \nDefault: `{ publicPath: '/' }`\n\nAn object containing options for [webpack-dev-middleware][dev-ware].\n\n### `options.host`\n\nType: `String`  \nDefault: `'localhost'`\n\nSets the host that the server will listen on. eg. `'10.10.10.1'`\n\n_Note: This value must match any value specified for `hot.host` or\n`hot.host.server`, otherwise `webpack-serve` will throw an error. This\nrequirement ensures that the `koa` server and `WebSocket` server play nice\ntogether._\n\n### `options.hotClient`\n\nType: `Object|Boolean`  \nDefault: `{}`\n\nAn object containing options for [webpack-hot-client][hot-client].\nSetting this to `false` will completely disable `webpack-hot-client`\nand all automatic Hot Module Replacement functionality.\n\n### `options.http2`\n\nType: `Boolean`  \nDefault: `false`\n\nIf using Node v9 or greater, setting this option to `true` will enable HTTP2\nsupport.\n\n### `options.https`\n\nType: `Object`  \nDefault: `null`\n\nPassing this option will instruct `webpack-serve` to create and serve the webpack\nbundle and accompanying content through a secure server. The object should\ncontain properties matching:\n\n```js\n{\n  key: fs.readFileSync('...key'),   // Private keys in PEM format.\n  cert: fs.readFileSync('...cert'), // Cert chains in PEM format.\n  pfx: \u003cString\u003e,                    // PFX or PKCS12 encoded private key and certificate chain.\n  passphrase: \u003cString\u003e              // A shared passphrase used for a single private key and/or a PFX.\n}\n```\n\nSee the [Node documentation][https-opts] for more information. For SSL\nCertificate generation, please read the\n[SSL Certificates for HTTPS](#ssl-certificates-for-https) section.\n\n### `options.logLevel`\n\nType: `String`  \nDefault: `info`\n\nInstructs `webpack-serve` to output information to the console/terminal at levels\nhigher than the specified level. Valid levels:\n\n```js\n[\n  'trace',\n  'debug',\n  'info',\n  'warn',\n  'error',\n  'silent'\n]\n```\n\n### `options.logTime`\n\nType: `Boolean`  \nDefault: `false`\n\nInstruct `webpack-serve` to prepend each line of log output with a `[HH:mm:ss]`\ntimestamp.\n\n### `options.on`\n\nType: `Object`  \nDefault: `null`\n\nWhile running `webpack-serve` from the command line, it can sometimes be useful\nto subscribe to events from the module's event bus _within your config_. This\noption can be used for that purpose. The option's value must be an `Object`\nmatching a `key:handler`, `String: Function` pattern. eg:\n\n```js\non: {\n  'build-started': () =\u003e { console.log('build started!'); }\n}\n```\n\n### `open`\n\nType: `Boolean|Object`  \nDefault: `false`\n\nInstruct the module to open the served bundle in a browser. Accepts an `Object`\nthat matches:\n\n```js\n{\n  app: \u003cString\u003e, // The proper name of the browser app to open.\n  path: \u003cString\u003e // The url path on the server to open.\n}\n```\n\n_Note: Using the `open` option will disable the `clipboard` option._\n\n### `port`\n\nType: `Number`  \nDefault: `8080`\n\nThe port the server should listen on.\n\n## Events\n\nThe server created by `webpack-serve` emits select events which can be\nsubscribed to. All events are emitted with a single `Object` parameter,\ncontaining named properties for relevant data.\n\nFor example:\n\n```js\nconst serve = require('webpack-serve');\nconst argv = {};\nconst config = require('./webpack.config.js');\n\nserve(argv, { config }).then((server) =\u003e {\n  server.on('listening', ({ server, options }) =\u003e {\n    console.log('happy fun time');\n  });\n});\n```\n\n#### build-started\n\n\u003c!-- spaces before Arguments are a unicode em-space \" \" --\u003e\n\nArguments:  \n [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_\n\nEmitted when a compiler has started a build.\n\n#### build-finished\n\nArguments:  \n [`Stats`](https://webpack.js.org/api/node/#stats-object) _stats_  \n [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_\n\nEmitted when a compiler has finished a build.\n\n#### compiler-error\n\nArguments:  \n [`Stats`](https://webpack.js.org/api/node/#stats-tojson-options-) _json_  \n [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_\n\nEmitted when a compiler has encountered and error, or a build has errors.\n\n#### compiler-warning\n\nArguments:  \n [`Stats`](https://webpack.js.org/api/node/#stats-tojson-options-) _json_  \n [`Compiler`](https://webpack.js.org/api/node/#compiler-instance) _compiler_\n\nEmitted when a compiler has encountered a warning, or a build has warnings.\n\n#### listening\n\nArguments:  \n [`net.Server`](https://nodejs.org/api/net.html#net_class_net_server)  \n `Object` options\n\nEmitted when the server begins listening for connections.\n\n## SSL Certificates for HTTPS\n\nUnlike webpack-dev-server, `webpack-serve` does not ship with SSL Certificate\ngeneration, nor does it ship with a built-in certificate for use with HTTPS\nconfigurations. This is due largely in part to past security concerns and the\ncomplexity of use-cases in the webpack ecosystem.\n\nWe do however, recommend a path for users to generate their own SSL Certificates\nsafely and efficiently. That path resides in\n[`devcert-cli`](https://github.com/davewasmer/devcert-cli); an excellent project\nthat automates the creation of trusted SSL certificates that will work\nwonderfully with `webpack-serve`.\n\n## Add-on Features\n\nA core tenet of `webpack-serve` is to stay lean in terms of feature set, and to\nempower users with familiar and easily portable patterns to implement the same\nfeatures that those familiar with `webpack-dev-server` have come to rely on. This\nmakes the module far easier to maintain, which ultimately benefits the user.\n\nLuckily, flexibility baked into `webpack-serve` makes it a snap to add-on features.\nYou can leverage this by using the `add` option. The value of the option should\nbe a `Function` matching the following signature:\n\n```js\nadd: (app, middleware, options) =\u003e {\n  // ...\n}\n```\n\n### `add` Function Parameters\n\n- `app` The underlying Koa app\n- `middleware` An object containing accessor functions to call both\n`webpack-dev-middleware` and the `koa-static` middleware.\n- `options` - The internal options object used by `webpack-serve`\n\nSome add-on patterns may require changing the order of middleware used in the\n`app`. For instance, if adding routes or using a separate router with the `app`\nwhere routes must be added last, you'll need to call the `middleware` functions\nearly on. `webpack-serve` recognizes these calls and will not execute them again.\nIf these calls were omitted, `webpack-serve` would execute both in the default,\nlast in line, order.\n\n```js\nadd: (app, middleware, options) =\u003e {\n  // since we're manipulating the order of middleware added, we need to handle\n  // adding these two internal middleware functions.\n  middleware.webpack();\n  middleware.content();\n\n  // router *must* be the last middleware added\n  app.use(router.routes());\n}\n```\n\nListed below are some of the add-on patterns and recipes that can be found in\n[docs/addons](docs/addons):\n\n- [bonjour](docs/addons/bonjour.config.js)\n- [compress](docs/addons/compress)\n- [historyApiFallback](docs/addons/history-fallback.config.js)\n- [proxy + history fallback](docs/addons/proxy-history-fallback.config.js)\n- [proxy + router](docs/addons/proxy-router.config.js)\n- [reuse Chrome tab](docs/addons/reuse-chrome-tab)\n- [staticOptions](docs/addons/static-content-options.config.js)\n- [useLocalIp](docs/addons/local-ip.config.js)\n- [watch content](docs/addons/watch-content.config.js)\n\n### Community Add-ons\n\n_Note: The list below contains `webpack-serve` add-ons created by the community.\nInclusion in the list does not imply a module is preferred or recommended\nover others._\n\n- [webpack-serve-waitpage](https://github.com/elisherer/webpack-serve-waitpage):\nProvides build progress in the client during complilation.\n- [webpack-serve-overlay](https://github.com/G-Rath/webpack-serve-overlay):\nProvides an error and warning information overlay in the client.\n\n## Contributing\n\nWe welcome your contributions! Please take a moment to read our contributing\nguidelines if you haven't yet done so.\n\n#### [CONTRIBUTING](./.github/CONTRIBUTING.md)\n\n## License\n\n#### [MIT](./LICENSE)\n\n[npm]: https://img.shields.io/npm/v/webpack-serve.svg\n[npm-url]: https://npmjs.com/package/webpack-serve\n\n[node]: https://img.shields.io/node/v/webpack-serve.svg\n[node-url]: https://nodejs.org\n\n[deps]: https://david-dm.org/webpack-contrib/webpack-serve.svg\n[deps-url]: https://david-dm.org/webpack-contrib/webpack-serve\n\n[tests]: \thttps://img.shields.io/circleci/project/github/webpack-contrib/webpack-serve.svg\n[tests-url]: https://circleci.com/gh/webpack-contrib/webpack-serve\n\n[cover]: https://codecov.io/gh/webpack-contrib/webpack-serve/branch/master/graph/badge.svg\n[cover-url]: https://codecov.io/gh/webpack-contrib/webpack-serve\n\n[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg\n[chat-url]: https://gitter.im/webpack/webpack\n\n[size]: https://packagephobia.now.sh/badge?p=webpack-serve\n[size-url]: https://packagephobia.now.sh/result?p=webpack-serve\n\n[dev-ware]: https://github.com/webpack/webpack-dev-middleware#options\n[hot-client]: https://github.com/webpack-contrib/webpack-hot-client#options\n[https-opts]: https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fwebpack-serve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebpack-contrib%2Fwebpack-serve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fwebpack-serve/lists"}