\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\n# webpack-dev-middleware\n\nAn express-style development middleware for use with [webpack](https://webpack.js.org)\nbundles and allows for serving of the files emitted from webpack.\nThis should be used for **development only**.\n\nSome of the benefits of using this middleware include:\n\n- No files are written to disk, rather it handles files in memory\n- If files changed in watch mode, the middleware delays requests until compiling\nhas completed.\n- Supports hot module reload (HMR).\n\n## Getting Started\n\nFirst thing's first, install the module:\n\n```console\nnpm install webpack-dev-middleware --save-dev\n```\n\n_Note: We do not recommend installing this module globally._\n\n## Requirements\n\n`webpack-dev-middleware` requires Node v6 or higher, and must be used with a\nserver that accepts express-style middleware.\n\n## Usage\n\n```js\nconst webpack = require('webpack');\nconst middleware = require('webpack-dev-middleware');\nconst compiler = webpack({ .. webpack options .. });\nconst express = require('express');\nconst app = express();\n\napp.use(middleware(compiler, {\n // webpack-dev-middleware options\n}));\n\napp.listen(3000, () => console.log('Example app listening on port 3000!'))\n```\n\n## Options\n\nThe middleware accepts an `options` Object. The following is a property reference\nfor the Object.\n\n_Note: The `publicPath` property is required, whereas all other options are optional_\n\n### headers\n\nType: `Object` \nDefault: `undefined`\n\nThis property allows a user to pass custom HTTP headers on each request. eg.\n`{ \"X-Custom-Header\": \"yes\" }`\n\n### index\n\nType: `String` \nDefault: `undefined`\n\n\"index.html\",\n// The index path for web server, defaults to \"index.html\".\n// If falsy (but not undefined), the server will not respond to requests to the root URL.\n\n\n### lazy\n\nType: `Boolean` \nDefault: `undefined`\n\nThis option instructs the module to operate in 'lazy' mode, meaning that it won't\nrecompile when files change, but rather on each request.\n\n### logger\n\nType: `Object` \nDefault: [`webpack-log`](https://github.com/webpack-contrib/webpack-log/blob/master/index.js)\n\nIn the rare event that a user would like to provide a custom logging interface,\nthis property allows the user to assign one. The module leverages\n[`webpack-log`](https://github.com/webpack-contrib/webpack-log#readme)\nfor creating the [`loglevelnext`](https://github.com/shellscape/loglevelnext#readme)\nlogging management by default. Any custom logger must adhere to the same\nexports for compatibility. Specifically, all custom loggers must have the\nfollowing exported methods at a minimum:\n\n- `log.trace`\n- `log.debug`\n- `log.info`\n- `log.warn`\n- `log.error`\n\nPlease see the documentation for `loglevel` for more information.\n\n### logLevel\n\nType: `String` \nDefault: `'info'`\n\nThis property defines the level of messages that the module will log. Valid levels\ninclude:\n\n- `trace`\n- `debug`\n- `info`\n- `warn`\n- `error`\n- `silent`\n\nSetting a log level means that all other levels below it will be visible in the\nconsole. Setting `logLevel: 'silent'` will hide all console output. The module\nleverages [`webpack-log`](https://github.com/webpack-contrib/webpack-log#readme)\nfor logging management, and more information can be found on its page.\n\n### logTime\n\nType: `Boolean` \nDefault: `false`\n\nIf `true` the log output of the module will be prefixed by a timestamp in the\n`HH:mm:ss` format.\n\n### mimeTypes\n\nType: `Object` \nDefault: `null`\n\nThis property allows a user to register custom mime types or extension mappings.\neg. `{ 'text/html': [ 'phtml' ] }`. Please see the documentation for\n[`node-mime`](https://github.com/broofa/node-mime#mimedefine) for more information.\n\n### publicPath\n\nType: `String` \n_Required_\n\nThe public path that the middleware is bound to. _Best Practice: use the same\n`publicPath` defined in your webpack config._\n\n### reporter\n\nType: `Object` \nDefault: `undefined`\n\nAllows users to provide a custom reporter to handle logging within the module.\nPlease see the [default reporter](/lib/reporter.js)\nfor an example.\n\n### serverSideRender\n\nType: `Boolean` \nDefault: `undefined`\n\nInstructs the module to enable or disable the server-side rendering mode. Please\nsee [Server-Side Rendering](#server-side-rendering) for more information.\n\n### stats\n\nType: `Object` \nDefault: `{ context: process.cwd() }`\n\nOptions for formatting statistics displayed during and after compile. For more\ninformation and property details, please see the\n[webpack documentation](https://webpack.js.org/configuration/stats/#stats).\n\n### watchOffset\n\nType: `Number` \nDefault: `11000`\n\nWatching (by means of `lazy: false`) will frequently cause multiple compilations\nas the bundle changes during compilation. This is due in part to cross-platform\ndifferences in file watchers, so that webpack doesn't loose file changes when\nwatched files change rapidly. Since that scenario is more an edge case than not,\nthis option serves as a means to prevent multiple needless, identical compilations\nby advancing start-time of a watcher by a number of seconds, which keeps generated\nfiles from triggering the watch cycle.\n\n_To disable this prevention, set this option to a value of `0`._\n\n### watchOptions\n\nType: `Object` \nDefault: `{ aggregateTimeout: 200 }`\n\nThe module accepts an `Object` containing options for file watching, which is\npassed directly to the compiler provided. For more information on watch options\nplease see the [webpack documentation](https://webpack.js.org/configuration/watch/#watchoptions)\n\n## API\n\n`webpack-dev-middleware` also provides convenience methods that can be use to\ninteract with the middleware at runtime:\n\n### `close(callback)`\n\nInstructs a webpack-dev-middleware instance to stop watching for file changes.\n\n### Parameters\n\n#### callback\n\nType: `Function`\n\nA function executed once the middleware has stopped watching.\n\n### `invalidate()`\n\nInstructs a webpack-dev-middleware instance to recompile the bundle.\ne.g. after a change to the configuration.\n\n```js\nconst webpack = require('webpack');\nconst compiler = webpack({ ... });\nconst middleware = require('webpack-dev-middleware');\nconst instance = middleware(compiler);\n\napp.use(instance);\n\nsetTimeout(() => {\n // After a short delay the configuration is changed and a banner plugin is added\n // to the config\n compiler.apply(new webpack.BannerPlugin('A new banner'));\n\n // Recompile the bundle with the banner plugin:\n instance.invalidate();\n}, 1000);\n```\n\n### `waitUntilValid(callback)`\n\nExecutes a callback function when the compiler bundle is valid, typically after\ncompilation.\n\n### Parameters\n\n#### callback\n\nType: `Function`\n\nA function executed when the bundle becomes valid. If the bundle is\nvalid at the time of calling, the callback is executed immediately.\n\n```js\nconst webpack = require('webpack');\nconst compiler = webpack({ ... });\nconst middleware = require('webpack-dev-middleware');\nconst instance = middleware(compiler);\n\napp.use(instance);\n\ninstance.waitUntilValid(() => {\n console.log('Package is in a valid state');\n});\n```\n\n## Server-Side Rendering\n\n_Note: this feature is experimental and may be removed or changed completely in the future._\n\nIn order to develop an app using server-side rendering, we need access to the\n[`stats`](https://github.com/webpack/docs/wiki/node.js-api#stats), which is\ngenerated with each build.\n\nWith server-side rendering enabled, `webpack-dev-middleware` sets the `stat` to\n`res.locals.webpackStats` before invoking the next middleware, allowing a\ndeveloper to render the page body and manage the response to clients.\n\n_Note: Requests for bundle files will still be handled by\n`webpack-dev-middleware` and all requests will be pending until the build\nprocess is finished with server-side rendering enabled._\n\nExample Implementation:\n\n```js\nconst webpack = require('webpack');\nconst compiler = webpack({ ... });\nconst middleware = require('webpack-dev-middleware');\n\n// This function makes server rendering of asset references consistent with different webpack chunk/entry configurations\nfunction normalizeAssets(assets) {\n return Array.isArray(assets) ? assets : [assets]\n}\n\napp.use(middleware(compiler, { serverSideRender: true })\n\n// The following middleware would not be invoked until the latest build is finished.\napp.use((req, res) => {\n const assetsByChunkName = res.locals.webpackStats.toJson().assetsByChunkName\n\n // then use `assetsByChunkName` for server-sider rendering\n // For example, if you have only one main chunk:\n res.send(`\n\n \n My App\n\t\t${normalizeAssets(assetsByChunkName.main)\n\t\t\t .filter(path => path.endsWith('.css'))\n\t\t\t .map(path => ``)\n\t\t\t .join('\\n')}\n \n \n \n\t\t${normalizeAssets(assetsByChunkName.main)\n\t\t\t .filter(path => path.endsWith('.js'))\n\t\t\t .map(path => ``)\n\t\t\t .join('\\n')}\n \n\n `)\n\n})\n```\n\n## Support\n\nWe do our best to keep Issues in the repository focused on bugs, features, and\nneeded modifications to the code for the module. Because of that, we ask users\nwith general support, \"how-to\", or \"why isn't this working\" questions to try one\nof the other support channels that are available.\n\nYour first-stop-shop for support for webpack-dev-server should by the excellent\n[documentation][docs-url] for the module. If you see an opportunity for improvement\nof those docs, please head over to the [webpack.js.org repo][wjo-url] and open a\npull request.\n\nFrom there, we encourage users to visit the [webpack Gitter chat][chat-url] and\ntalk to the fine folks there. If your quest for answers comes up dry in chat,\nhead over to [StackOverflow][stack-url] and do a quick search or open a new\nquestion. Remember; It's always much easier to answer questions that include your\n`webpack.config.js` and relevant files!\n\nIf you're twitter-savvy you can tweet [#webpack][hash-url] with your question\nand someone should be able to reach out and lend a hand.\n\nIf you have discovered a :bug:, have a feature suggestion, of would like to see\na modification, please feel free to create an issue on Github. _Note: The issue\ntemplate isn't optional, so please be sure not to remove it, and please fill it\nout completely._\n\n## Contributing\n\nWe welcome your contributions! Please have a read of [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to get involved.\n\n## Maintainers\n\n
![](\"https://webpack.js.org/assets/icon-square-big.svg\"){kind=icon}
\n \n![](\"https://avatars.githubusercontent.com/SpaceK33z?v=4&s=150\")
\n ![](\"https://i.imgur.com/4v6pgxh.png\")
\n