132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
Webpack Stats Plugin
|
|
====================
|
|
|
|
[![Build Status][trav_img]][trav_site]
|
|
|
|
This plugin will ingest the webpack
|
|
[stats](https://github.com/webpack/docs/wiki/node.js-api#stats) object,
|
|
process / transform the object and write out to a file for further consumption.
|
|
|
|
The most common use case is building a hashed bundle and wanting to
|
|
programmatically refer to the correct bundle path in your Node.js server.
|
|
|
|
## Installation
|
|
|
|
The plugin is available via [npm](https://www.npmjs.com/package/webpack-stats-plugin):
|
|
|
|
```
|
|
$ npm install --save webpack-stats-plugin
|
|
```
|
|
|
|
## Examples
|
|
|
|
You can see lots of examples at
|
|
[`demo/webpack.config.js`](demo/webpack.config.js).
|
|
|
|
### Basic
|
|
|
|
```js
|
|
var StatsWriterPlugin = require("webpack-stats-plugin").StatsWriterPlugin;
|
|
|
|
module.exports = {
|
|
plugins: [
|
|
// Everything else **first**.
|
|
|
|
// Write out stats file to build directory.
|
|
new StatsWriterPlugin({
|
|
filename: "stats.json" // Default
|
|
})
|
|
]
|
|
}
|
|
```
|
|
|
|
### Custom Transform Function
|
|
|
|
The transform function has a signature of:
|
|
|
|
```js
|
|
/**
|
|
* Transform skeleton.
|
|
*
|
|
* @param {Object} data Stats object
|
|
* @param {Object} opts Options
|
|
* @param {Object} opts.compiler Current compiler instance
|
|
* @returns {String} String to emit to file
|
|
*/
|
|
function (data, opts) {}
|
|
```
|
|
|
|
which you can use like:
|
|
|
|
```js
|
|
var StatsWriterPlugin = require("webpack-stats-plugin").StatsWriterPlugin;
|
|
|
|
module.exports = {
|
|
plugins: [
|
|
new StatsWriterPlugin({
|
|
transform: function (data, opts) {
|
|
return JSON.stringify({
|
|
main: data.assetsByChunkName.main[0],
|
|
css: data.assetsByChunkName.main[1]
|
|
}, null, 2);
|
|
}
|
|
})
|
|
]
|
|
}
|
|
```
|
|
|
|
## Plugins
|
|
|
|
* [`StatsWriterPlugin(opts)`](#statswriterplugin-opts-)
|
|
|
|
### `StatsWriterPlugin(opts)`
|
|
* **opts** (`Object`) options
|
|
* **opts.filename** (`String`) output file name (Default: "stat.json")
|
|
* **opts.fields** (`Array`) fields of stats obj to keep (Default: \["assetsByChunkName"\])
|
|
* **opts.transform** (`Function`) transform stats obj (Default: `JSON.stringify()`)
|
|
|
|
Stats writer module.
|
|
|
|
Stats can be a string or array (we"ll have array from using source maps):
|
|
|
|
```js
|
|
"assetsByChunkName": {
|
|
"main": [
|
|
"cd6371d4131fbfbefaa7.bundle.js",
|
|
"../js-map/cd6371d4131fbfbefaa7.bundle.js.map"
|
|
]
|
|
},
|
|
```
|
|
|
|
**Note**: The stats object is **big**. It includes the entire source included
|
|
in a bundle. Thus, we default `opts.fields` to `["assetsByChunkName"]` to
|
|
only include those. However, if you want the _whole thing_ (maybe doing an
|
|
`opts.transform` function), then you can set `fields: null` in options to
|
|
get **all** of the stats object.
|
|
|
|
See:
|
|
- http://webpack.github.io/docs/long-term-caching.html#get-filenames-from-stats
|
|
- https://github.com/webpack/docs/wiki/node.js-api#stats
|
|
|
|
**`filename`**: The `opts.filename` option can be a file name or path relative to
|
|
`output.path` in webpack configuration. It should not be absolute.
|
|
|
|
**`transform`**: By default, the retrieved stats object is `JSON.stringify`'ed
|
|
but by supplying an alternate transform you can target _any_ output format.
|
|
See [`demo/webpack.config.js`](demo/webpack.config.js) for various examples
|
|
including Markdown output.
|
|
|
|
- **Warning**: The output of `transform` should be a `String`, not an object.
|
|
On Node `v4.x` if you return a real object in `transform`, then webpack
|
|
will break with a `TypeError` (See [#8](https://github.com/FormidableLabs/webpack-stats-plugin/issues/8)). Just adding a simple
|
|
`JSON.stringify()` around your object is usually what you need to solve
|
|
any problems.
|
|
|
|
## Contributions
|
|
|
|
Contributions welcome! Make sure to pass `$ gulp check`.
|
|
|
|
[trav]: https://travis-ci.org/
|
|
[trav_img]: https://api.travis-ci.org/FormidableLabs/webpack-stats-plugin.svg
|
|
[trav_site]: https://travis-ci.org/FormidableLabs/webpack-stats-plugin
|