Projekt

Obecné

Profil

Stáhnout (14.1 KB) Statistiky
| Větev: | Revize:
1 3a515b92 cagy
<div align="center">
2
  <a href="https://github.com/webpack/webpack">
3
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
4
  </a>
5
</div>
6
7
[![npm][npm]][npm-url]
8
[![node][node]][node-url]
9
[![deps][deps]][deps-url]
10
[![tests][tests]][tests-url]
11
[![coverage][cover]][cover-url]
12
[![chat][chat]][chat-url]
13
[![size][size]][size-url]
14
15
# webpack-dev-middleware
16
17
An express-style development middleware for use with [webpack](https://webpack.js.org)
18
bundles and allows for serving of the files emitted from webpack.
19
This should be used for **development only**.
20
21
Some of the benefits of using this middleware include:
22
23
- No files are written to disk, rather it handles files in memory
24
- If files changed in watch mode, the middleware delays requests until compiling
25
  has completed.
26
- Supports hot module reload (HMR).
27
28
## Requirements
29
30
This module requires a minimum of Node v6.9.0 and Webpack v4.0.0, and must be used with a
31
server that accepts express-style middleware.
32
33
## Getting Started
34
35
First thing's first, install the module:
36
37
```console
38
npm install webpack-dev-middleware --save-dev
39
```
40
41
_Note: We do not recommend installing this module globally._
42
43
## Usage
44
45
```js
46
const webpack = require('webpack');
47
const middleware = require('webpack-dev-middleware');
48
const compiler = webpack({
49
  // webpack options
50
});
51
const express = require('express');
52
const app = express();
53
54
app.use(
55
  middleware(compiler, {
56
    // webpack-dev-middleware options
57
  })
58
);
59
60
app.listen(3000, () => console.log('Example app listening on port 3000!'));
61
```
62
63
## Options
64
65
The middleware accepts an `options` Object. The following is a property reference
66
for the Object.
67
68
_Note: The `publicPath` property is required, whereas all other options are optional_
69
70
### methods
71
72
Type: `Array`  
73
Default: `[ 'GET', 'HEAD' ]`
74
75
This property allows a user to pass the list of HTTP request methods accepted by the server.
76
77
### headers
78
79
Type: `Object`  
80
Default: `undefined`
81
82
This property allows a user to pass custom HTTP headers on each request. eg.
83
`{ "X-Custom-Header": "yes" }`
84
85
### index
86
87
Type: `String`  
88
Default: `undefined`
89
90
"index.html",
91
// The index path for web server, defaults to "index.html".
92
// If falsy (but not undefined), the server will not respond to requests to the root URL.
93
94
### lazy
95
96
Type: `Boolean`  
97
Default: `undefined`
98
99
This option instructs the module to operate in 'lazy' mode, meaning that it won't
100
recompile when files change, but rather on each request.
101
102
### logger
103
104
Type: `Object`  
105
Default: [`webpack-log`](https://github.com/webpack-contrib/webpack-log/blob/master/index.js)
106
107
In the rare event that a user would like to provide a custom logging interface,
108
this property allows the user to assign one. The module leverages
109
[`webpack-log`](https://github.com/webpack-contrib/webpack-log#readme)
110
for creating the [`loglevelnext`](https://github.com/shellscape/loglevelnext#readme)
111
logging management by default. Any custom logger must adhere to the same
112
exports for compatibility. Specifically, all custom loggers must have the
113
following exported methods at a minimum:
114
115
- `log.trace`
116
- `log.debug`
117
- `log.info`
118
- `log.warn`
119
- `log.error`
120
121
Please see the documentation for `loglevel` for more information.
122
123
### logLevel
124
125
Type: `String`  
126
Default: `'info'`
127
128
This property defines the level of messages that the module will log. Valid levels
129
include:
130
131
- `trace`
132
- `debug`
133
- `info`
134
- `warn`
135
- `error`
136
- `silent`
137
138
Setting a log level means that all other levels below it will be visible in the
139
console. Setting `logLevel: 'silent'` will hide all console output. The module
140
leverages [`webpack-log`](https://github.com/webpack-contrib/webpack-log#readme)
141
for logging management, and more information can be found on its page.
142
143
### logTime
144
145
Type: `Boolean`  
146
Default: `false`
147
148
If `true` the log output of the module will be prefixed by a timestamp in the
149
`HH:mm:ss` format.
150
151
### mimeTypes
152
153
Type: `Object`  
154
Default: `null`
155
156
This property allows a user to register custom mime types or extension mappings.
157
eg. `mimeTypes: { 'text/html': [ 'phtml' ] }`.
158
159
By default node-mime will throw an error if you try to map a type to an extension
160
that is already assigned to another type. Passing `force: true` will suppress this behavior
161
(overriding any previous mapping).
162
eg. `mimeTypes: { typeMap: { 'text/html': [ 'phtml' ] } }, force: true }`.
163
164
Please see the documentation for
165
[`node-mime`](https://github.com/broofa/node-mime#mimedefinetypemap-force--false) for more information.
166
167
### publicPath
168
169
Type: `String`  
170
_Required_
171
172
The public path that the middleware is bound to. _Best Practice: use the same
173
`publicPath` defined in your webpack config. For more information about
174
`publicPath`, please see
175
[the webpack documentation](https://webpack.js.org/guides/public-path)._
176
177
### reporter
178
179
Type: `Object`  
180
Default: `undefined`
181
182
Allows users to provide a custom reporter to handle logging within the module.
183
Please see the [default reporter](/lib/reporter.js)
184
for an example.
185
186
### serverSideRender
187
188
Type: `Boolean`  
189
Default: `undefined`
190
191
Instructs the module to enable or disable the server-side rendering mode. Please
192
see [Server-Side Rendering](#server-side-rendering) for more information.
193
194
### stats
195
196
Type: `Object`  
197
Default: `{ context: process.cwd() }`
198
199
Options for formatting statistics displayed during and after compile. For more
200
information and property details, please see the
201
[webpack documentation](https://webpack.js.org/configuration/stats/#stats).
202
203
### watchOptions
204
205
Type: `Object`  
206
Default: `{ aggregateTimeout: 200 }`
207
208
The module accepts an `Object` containing options for file watching, which is
209
passed directly to the compiler provided. For more information on watch options
210
please see the [webpack documentation](https://webpack.js.org/configuration/watch/#watchoptions)
211
212
### writeToDisk
213
214
Type: `Boolean|Function`  
215
Default: `false`
216
217
If `true`, the option will instruct the module to write files to the configured
218
location on disk as specified in your `webpack` config file. _Setting
219
`writeToDisk: true` won't change the behavior of the `webpack-dev-middleware`,
220
and bundle files accessed through the browser will still be served from memory._
221
This option provides the same capabilities as the
222
[`WriteFilePlugin`](https://github.com/gajus/write-file-webpack-plugin/pulls).
223
224
This option also accepts a `Function` value, which can be used to filter which
225
files are written to disk. The function follows the same premise as
226
[`Array#filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter)
227
in which a return value of `false` _will not_ write the file, and a return value
228
of `true` _will_ write the file to disk. eg.
229
230
```js
231
{
232
  writeToDisk: (filePath) => {
233
    return /superman\.css$/.test(filePath);
234
  };
235
}
236
```
237
238
### fs
239
240
Type: `Object`  
241
Default: `MemoryFileSystem`
242
243
Set the default file system which will be used by webpack as primary destination of generated files. Default is set to webpack's default file system: [memory-fs](https://github.com/webpack/memory-fs). This option isn't affected by the [writeToDisk](#writeToDisk) option.
244
245
**Note:** As of 3.5.x version of the middleware you have to provide `.join()` method to the `fs` instance manually. This can be done simply by using `path.join`:
246
247
```js
248
fs.join = path.join; // no need to bind
249
```
250
251
## API
252
253
`webpack-dev-middleware` also provides convenience methods that can be use to
254
interact with the middleware at runtime:
255
256
### `close(callback)`
257
258
Instructs a webpack-dev-middleware instance to stop watching for file changes.
259
260
### Parameters
261
262
#### callback
263
264
Type: `Function`
265
266
A function executed once the middleware has stopped watching.
267
268
### `invalidate()`
269
270
Instructs a webpack-dev-middleware instance to recompile the bundle.
271
e.g. after a change to the configuration.
272
273
```js
274
const webpack = require('webpack');
275
const compiler = webpack({ ... });
276
const middleware = require('webpack-dev-middleware');
277
const instance = middleware(compiler);
278
279
app.use(instance);
280
281
setTimeout(() => {
282
  // After a short delay the configuration is changed and a banner plugin is added
283
  // to the config
284
  compiler.apply(new webpack.BannerPlugin('A new banner'));
285
286
  // Recompile the bundle with the banner plugin:
287
  instance.invalidate();
288
}, 1000);
289
```
290
291
### `waitUntilValid(callback)`
292
293
Executes a callback function when the compiler bundle is valid, typically after
294
compilation.
295
296
### Parameters
297
298
#### callback
299
300
Type: `Function`
301
302
A function executed when the bundle becomes valid. If the bundle is
303
valid at the time of calling, the callback is executed immediately.
304
305
```js
306
const webpack = require('webpack');
307
const compiler = webpack({ ... });
308
const middleware = require('webpack-dev-middleware');
309
const instance = middleware(compiler);
310
311
app.use(instance);
312
313
instance.waitUntilValid(() => {
314
  console.log('Package is in a valid state');
315
});
316
```
317
318
## Known Issues
319
320
### Multiple Successive Builds
321
322
Watching (by means of `lazy: false`) will frequently cause multiple compilations
323
as the bundle changes during compilation. This is due in part to cross-platform
324
differences in file watchers, so that webpack doesn't loose file changes when
325
watched files change rapidly. If you run into this situation, please make use of
326
the [`TimeFixPlugin`](https://github.com/egoist/time-fix-plugin).
327
328
## Server-Side Rendering
329
330
_Note: this feature is experimental and may be removed or changed completely in the future._
331
332
In order to develop an app using server-side rendering, we need access to the
333
[`stats`](https://github.com/webpack/docs/wiki/node.js-api#stats), which is
334
generated with each build.
335
336
With server-side rendering enabled, `webpack-dev-middleware` sets the `stat` to
337
`res.locals.webpackStats` and the memory filesystem to `res.locals.fs` before invoking the next middleware, allowing a
338
developer to render the page body and manage the response to clients.
339
340
_Note: Requests for bundle files will still be handled by
341
`webpack-dev-middleware` and all requests will be pending until the build
342
process is finished with server-side rendering enabled._
343
344
Example Implementation:
345
346
```js
347
const webpack = require('webpack');
348
const compiler = webpack({
349
  // webpack options
350
});
351
const isObject = require('is-object');
352
const middleware = require('webpack-dev-middleware');
353
354
// This function makes server rendering of asset references consistent with different webpack chunk/entry configurations
355
function normalizeAssets(assets) {
356
  if (isObject(assets)) {
357
    return Object.values(assets);
358
  }
359
360
  return Array.isArray(assets) ? assets : [assets];
361
}
362
363
app.use(middleware(compiler, { serverSideRender: true }));
364
365
// The following middleware would not be invoked until the latest build is finished.
366
app.use((req, res) => {
367
  const assetsByChunkName = res.locals.webpackStats.toJson().assetsByChunkName;
368
  const fs = res.locals.fs;
369
  const outputPath = res.locals.webpackStats.toJson().outputPath;
370
371
  // then use `assetsByChunkName` for server-sider rendering
372
  // For example, if you have only one main chunk:
373
  res.send(`
374
<html>
375
  <head>
376
    <title>My App</title>
377
    <style>
378
    ${normalizeAssets(assetsByChunkName.main)
379
      .filter((path) => path.endsWith('.css'))
380
      .map((path) => fs.readFileSync(outputPath + '/' + path))
381
      .join('\n')}
382
    </style>
383
  </head>
384
  <body>
385
    <div id="root"></div>
386
    ${normalizeAssets(assetsByChunkName.main)
387
      .filter((path) => path.endsWith('.js'))
388
      .map((path) => `<script src="${path}"></script>`)
389
      .join('\n')}
390
  </body>
391
</html>
392
  `);
393
});
394
```
395
396
## Support
397
398
We do our best to keep Issues in the repository focused on bugs, features, and
399
needed modifications to the code for the module. Because of that, we ask users
400
with general support, "how-to", or "why isn't this working" questions to try one
401
of the other support channels that are available.
402
403
Your first-stop-shop for support for webpack-dev-server should by the excellent
404
[documentation][docs-url] for the module. If you see an opportunity for improvement
405
of those docs, please head over to the [webpack.js.org repo][wjo-url] and open a
406
pull request.
407
408
From there, we encourage users to visit the [webpack Gitter chat][chat-url] and
409
talk to the fine folks there. If your quest for answers comes up dry in chat,
410
head over to [StackOverflow][stack-url] and do a quick search or open a new
411
question. Remember; It's always much easier to answer questions that include your
412
`webpack.config.js` and relevant files!
413
414
If you're twitter-savvy you can tweet [#webpack][hash-url] with your question
415
and someone should be able to reach out and lend a hand.
416
417
If you have discovered a :bug:, have a feature suggestion, or would like to see
418
a modification, please feel free to create an issue on Github. _Note: The issue
419
template isn't optional, so please be sure not to remove it, and please fill it
420
out completely._
421
422
## Contributing
423
424
Please take a moment to read our contributing guidelines if you haven't yet done so.
425
426
[CONTRIBUTING](./.github/CONTRIBUTING.md)
427
428
## License
429
430
[MIT](./LICENSE)
431
432
[npm]: https://img.shields.io/npm/v/webpack-dev-middleware.svg
433
[npm-url]: https://npmjs.com/package/webpack-dev-middleware
434
[node]: https://img.shields.io/node/v/webpack-dev-middleware.svg
435
[node-url]: https://nodejs.org
436
[deps]: https://david-dm.org/webpack/webpack-dev-middleware.svg
437
[deps-url]: https://david-dm.org/webpack/webpack-dev-middleware
438
[tests]: https://dev.azure.com/webpack/webpack-dev-middleware/_apis/build/status/webpack.webpack-dev-middleware?branchName=master
439
[tests-url]: https://dev.azure.com/webpack/webpack-dev-middleware/_build/latest?definitionId=8&branchName=master
440
[cover]: https://codecov.io/gh/webpack/webpack-dev-middleware/branch/master/graph/badge.svg
441
[cover-url]: https://codecov.io/gh/webpack/webpack-dev-middleware
442
[chat]: https://badges.gitter.im/webpack/webpack.svg
443
[chat-url]: https://gitter.im/webpack/webpack
444
[size]: https://packagephobia.now.sh/badge?p=webpack-dev-middleware
445
[size-url]: https://packagephobia.now.sh/result?p=webpack-dev-middleware
446
[docs-url]: https://webpack.js.org/guides/development/#using-webpack-dev-middleware
447
[hash-url]: https://twitter.com/search?q=webpack
448
[middleware-url]: https://github.com/webpack/webpack-dev-middleware
449
[stack-url]: https://stackoverflow.com/questions/tagged/webpack-dev-middleware
450
[uglify-url]: https://github.com/webpack-contrib/uglifyjs-webpack-plugin
451
[wjo-url]: https://github.com/webpack/webpack.js.org