diff options
Diffstat (limited to 'node_modules/webpack-dev-middleware/README.md')
| -rw-r--r-- | node_modules/webpack-dev-middleware/README.md | 445 |
1 files changed, 445 insertions, 0 deletions
diff --git a/node_modules/webpack-dev-middleware/README.md b/node_modules/webpack-dev-middleware/README.md new file mode 100644 index 00000000..91a9cf06 --- /dev/null +++ b/node_modules/webpack-dev-middleware/README.md @@ -0,0 +1,445 @@ +<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-dev-middleware + +An express-style development middleware for use with [webpack](https://webpack.js.org) +bundles and allows for serving of the files emitted from webpack. +This should be used for **development only**. + +Some of the benefits of using this middleware include: + +- No files are written to disk, rather it handles files in memory +- If files changed in watch mode, the middleware delays requests until compiling +has completed. +- Supports hot module reload (HMR). + +## Requirements + +This module requires a minimum of Node v6.9.0 and Webpack v4.0.0, and must be used with a +server that accepts express-style middleware. + +## Getting Started + +First thing's first, install the module: + +```console +npm install webpack-dev-middleware --save-dev +``` + +_Note: We do not recommend installing this module globally._ + +## Usage + +```js +const webpack = require('webpack'); +const middleware = require('webpack-dev-middleware'); +const compiler = webpack({ .. webpack options .. }); +const express = require('express'); +const app = express(); + +app.use(middleware(compiler, { + // webpack-dev-middleware options +})); + +app.listen(3000, () => console.log('Example app listening on port 3000!')) +``` + +## Options + +The middleware accepts an `options` Object. The following is a property reference +for the Object. + +_Note: The `publicPath` property is required, whereas all other options are optional_ + +### methods + +Type: `Array` +Default: `[ 'GET' ]` + +This property allows a user to pass the list of HTTP request methods accepted by the server. + +### headers + +Type: `Object` +Default: `undefined` + +This property allows a user to pass custom HTTP headers on each request. eg. +`{ "X-Custom-Header": "yes" }` + +### index + +Type: `String` +Default: `undefined` + +"index.html", +// The index path for web server, defaults to "index.html". +// If falsy (but not undefined), the server will not respond to requests to the root URL. + + +### lazy + +Type: `Boolean` +Default: `undefined` + +This option instructs the module to operate in 'lazy' mode, meaning that it won't +recompile when files change, but rather on each request. + +### logger + +Type: `Object` +Default: [`webpack-log`](https://github.com/webpack-contrib/webpack-log/blob/master/index.js) + +In the rare event that a user would like to provide a custom logging interface, +this property allows the user to assign one. The module leverages +[`webpack-log`](https://github.com/webpack-contrib/webpack-log#readme) +for creating the [`loglevelnext`](https://github.com/shellscape/loglevelnext#readme) +logging management by default. Any custom logger must adhere to the same +exports for compatibility. Specifically, all custom loggers must have the +following exported methods at a minimum: + +- `log.trace` +- `log.debug` +- `log.info` +- `log.warn` +- `log.error` + +Please see the documentation for `loglevel` for more information. + +### logLevel + +Type: `String` +Default: `'info'` + +This property defines the level of messages that the module will log. Valid levels +include: + +- `trace` +- `debug` +- `info` +- `warn` +- `error` +- `silent` + +Setting a log level means that all other levels below it will be visible in the +console. Setting `logLevel: 'silent'` will hide all console output. The module +leverages [`webpack-log`](https://github.com/webpack-contrib/webpack-log#readme) +for logging management, and more information can be found on its page. + +### logTime + +Type: `Boolean` +Default: `false` + +If `true` the log output of the module will be prefixed by a timestamp in the +`HH:mm:ss` format. + +### mimeTypes + +Type: `Object` +Default: `null` + +This property allows a user to register custom mime types or extension mappings. +eg. `{ 'text/html': [ 'phtml' ] }`. Please see the documentation for +[`node-mime`](https://github.com/broofa/node-mime#mimedefine) for more information. + +### publicPath + +Type: `String` +_Required_ + +The public path that the middleware is bound to. _Best Practice: use the same +`publicPath` defined in your webpack config. For more information about +`publicPath`, please see +[the webpack documentation](https://webpack.js.org/guides/public-path)._ + +### reporter + +Type: `Object` +Default: `undefined` + +Allows users to provide a custom reporter to handle logging within the module. +Please see the [default reporter](/lib/reporter.js) +for an example. + +### serverSideRender + +Type: `Boolean` +Default: `undefined` + +Instructs the module to enable or disable the server-side rendering mode. Please +see [Server-Side Rendering](#server-side-rendering) for more information. + +### stats + +Type: `Object` +Default: `{ context: process.cwd() }` + +Options for formatting statistics displayed during and after compile. For more +information and property details, please see the +[webpack documentation](https://webpack.js.org/configuration/stats/#stats). + +### watchOptions + +Type: `Object` +Default: `{ aggregateTimeout: 200 }` + +The module accepts an `Object` containing options for file watching, which is +passed directly to the compiler provided. For more information on watch options +please see the [webpack documentation](https://webpack.js.org/configuration/watch/#watchoptions) + +### writeToDisk + +Type: `Boolean|Function` +Default: `false` + +If true, the option will instruct the module to write files to the configured +location on disk as specified in your `webpack` config file. _Setting +`writeToDisk: true` won't change the behavior of the `webpack-dev-middleware`, +and bundle files accessed through the browser will still be served from memory._ +This option provides the same capabilities as the +[`WriteFilePlugin`](https://github.com/gajus/write-file-webpack-plugin/pulls). + +This option also accepts a `Function` value, which can be used to filter which +files are written to disk. The function follows the same premise as +[`Array#filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) +in which a return value of `false` _will not_ write the file, and a return value +of `true` _will_ write the file to disk. eg. + +```js +{ + writeToDisk: (filePath) { + return /superman\.css$/.test(filePath); + } +} +``` + +## API + +`webpack-dev-middleware` also provides convenience methods that can be use to +interact with the middleware at runtime: + +### `close(callback)` + +Instructs a webpack-dev-middleware instance to stop watching for file changes. + +### Parameters + +#### callback + +Type: `Function` + +A function executed once the middleware has stopped watching. + +### `invalidate()` + +Instructs a webpack-dev-middleware instance to recompile the bundle. +e.g. after a change to the configuration. + +```js +const webpack = require('webpack'); +const compiler = webpack({ ... }); +const middleware = require('webpack-dev-middleware'); +const instance = middleware(compiler); + +app.use(instance); + +setTimeout(() => { + // After a short delay the configuration is changed and a banner plugin is added + // to the config + compiler.apply(new webpack.BannerPlugin('A new banner')); + + // Recompile the bundle with the banner plugin: + instance.invalidate(); +}, 1000); +``` + +### `waitUntilValid(callback)` + +Executes a callback function when the compiler bundle is valid, typically after +compilation. + +### Parameters + +#### callback + +Type: `Function` + +A function executed when the bundle becomes valid. If the bundle is +valid at the time of calling, the callback is executed immediately. + +```js +const webpack = require('webpack'); +const compiler = webpack({ ... }); +const middleware = require('webpack-dev-middleware'); +const instance = middleware(compiler); + +app.use(instance); + +instance.waitUntilValid(() => { + console.log('Package is in a valid state'); +}); +``` +## Known Issues + +### Multiple Successive Builds + +Watching (by means of `lazy: false`) will frequently cause multiple compilations +as the bundle changes during compilation. This is due in part to cross-platform +differences in file watchers, so that webpack doesn't loose file changes when +watched files change rapidly. If you run into this situation, please make use of +the [`TimeFixPlugin`](https://github.com/egoist/time-fix-plugin). + +## Server-Side Rendering + +_Note: this feature is experimental and may be removed or changed completely in the future._ + +In order to develop an app using server-side rendering, we need access to the +[`stats`](https://github.com/webpack/docs/wiki/node.js-api#stats), which is +generated with each build. + +With server-side rendering enabled, `webpack-dev-middleware` sets the `stat` to +`res.locals.webpackStats` and the memory filesystem to `res.locals.fs` before invoking the next middleware, allowing a +developer to render the page body and manage the response to clients. + +_Note: Requests for bundle files will still be handled by +`webpack-dev-middleware` and all requests will be pending until the build +process is finished with server-side rendering enabled._ + +Example Implementation: + +```js +const webpack = require('webpack'); +const compiler = webpack({ ... }); +const isObject = require('is-object'); +const middleware = require('webpack-dev-middleware'); + +// This function makes server rendering of asset references consistent with different webpack chunk/entry configurations +function normalizeAssets(assets) { + if (isObject(assets)) { + return Object.values(assets) + } + return Array.isArray(assets) ? assets : [assets] +} + +app.use(middleware(compiler, { serverSideRender: true })) + +// The following middleware would not be invoked until the latest build is finished. +app.use((req, res) => { + const assetsByChunkName = res.locals.webpackStats.toJson().assetsByChunkName + const fs = res.locals.fs + const outputPath = res.locals.webpackStats.toJson().outputPath + + // then use `assetsByChunkName` for server-sider rendering + // For example, if you have only one main chunk: + res.send(` +<html> + <head> + <title>My App</title> + <style> + ${normalizeAssets(assetsByChunkName.main) + .filter(path => path.endsWith('.css')) + .map(path => fs.readFileSync(outputPath + '/' + path)) + .join('\n')} + </style> + </head> + <body> + <div id="root"></div> + ${normalizeAssets(assetsByChunkName.main) + .filter(path => path.endsWith('.js')) + .map(path => `<script src="${path}"></script>`) + .join('\n')} + </body> +</html> + `) + +}) +``` + +## Support + +We do our best to keep Issues in the repository focused on bugs, features, and +needed modifications to the code for the module. Because of that, we ask users +with general support, "how-to", or "why isn't this working" questions to try one +of the other support channels that are available. + +Your first-stop-shop for support for webpack-dev-server should by the excellent +[documentation][docs-url] for the module. If you see an opportunity for improvement +of those docs, please head over to the [webpack.js.org repo][wjo-url] and open a +pull request. + +From there, we encourage users to visit the [webpack Gitter chat][chat-url] and +talk to the fine folks there. If your quest for answers comes up dry in chat, +head over to [StackOverflow][stack-url] and do a quick search or open a new +question. Remember; It's always much easier to answer questions that include your +`webpack.config.js` and relevant files! + +If you're twitter-savvy you can tweet [#webpack][hash-url] with your question +and someone should be able to reach out and lend a hand. + +If you have discovered a :bug:, have a feature suggestion, of would like to see +a modification, please feel free to create an issue on Github. _Note: The issue +template isn't optional, so please be sure not to remove it, and please fill it +out completely._ + +## Contributing + +We welcome your contributions! Please have a read of [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to get involved. + +## Maintainers + +<table> + <tbody> + <tr> + <td align="center"> + <img src="https://avatars.githubusercontent.com/SpaceK33z?v=4&s=150"> + <br /> + <a href="https://github.com/SpaceK33z">Kees Kluskens</a> + </td> + <td align="center"> + <img src="https://i.imgur.com/4v6pgxh.png"> + <br /> + <a href="https://github.com/shellscape">Andrew Powell</a> + </td> + </tr> + </tbody> +</table> + +## License + +#### [MIT](./LICENSE) + +[npm]: https://img.shields.io/npm/v/webpack-dev-middleware.svg +[npm-url]: https://npmjs.com/package/webpack-dev-middleware + +[node]: https://img.shields.io/node/v/webpack-dev-middleware.svg +[node-url]: https://nodejs.org + +[deps]: https://david-dm.org/webpack/webpack-dev-middleware.svg +[deps-url]: https://david-dm.org/webpack/webpack-dev-middleware + +[tests]: http://img.shields.io/travis/webpack/webpack-dev-middleware.svg +[tests-url]: https://travis-ci.org/webpack/webpack-dev-middleware + +[cover]: https://codecov.io/gh/webpack/webpack-dev-middleware/branch/master/graph/badge.svg +[cover-url]: https://codecov.io/gh/webpack/webpack-dev-middleware + +[chat]: https://badges.gitter.im/webpack/webpack.svg +[chat-url]: https://gitter.im/webpack/webpack + +[docs-url]: https://webpack.js.org/guides/development/#using-webpack-dev-middleware +[hash-url]: https://twitter.com/search?q=webpack +[middleware-url]: https://github.com/webpack/webpack-dev-middleware +[stack-url]: https://stackoverflow.com/questions/tagged/webpack-dev-middleware +[uglify-url]: https://github.com/webpack-contrib/uglifyjs-webpack-plugin +[wjo-url]: https://github.com/webpack/webpack.js.org |