webpack-file-list-plugin

A WebPack2 plugin to emit a JSON file with a map of chunk names and files.

Why

When using Webpack's Common Chunk Plugin, your chunk files can be given a hash string in the name to differentiate one build from another. Example webpack output:

                                       Asset       Size  Chunks                    Chunk Names
              vendor.ba256fb84f94184bd7c4.js     713 kB    0, 2  [emitted]  [big]  vendor
                 app.cc61dcf6afc98dd4bb94.js    7.32 kB    1, 2  [emitted]         app
            manifest.cb05244398323e0b0117.js    1.49 kB       2  [emitted]         manifest
    app.a06c4e5121fe25514b84acb9671c0faf.css  206 bytes    1, 2  [emitted]         app
          vendor.ba256fb84f94184bd7c4.js.map    5.45 MB    0, 2  [emitted]         vendor
             app.cc61dcf6afc98dd4bb94.js.map    34.2 kB    1, 2  [emitted]         app
app.a06c4e5121fe25514b84acb9671c0faf.css.map  117 bytes    1, 2  [emitted]         app
        manifest.cb05244398323e0b0117.js.map    14.1 kB       2  [emitted]         manifest

The hash is generated based on the code that ends up in the bundle. This is a best practice to maximize caching as application code changes. Separating 3rd party components from internal components has several benefits:

• updating dependencies can happen at a different cadence from application code releases
• from the client, 3rd party components can remain cached while application code changes

This approach is fine if the web server is implicitly aware of the webpack output (using Express and the webpack middleware, for example). This is typical for a small web application server by node. However, there are application designs where this is not practical. A complex application may develop modules in different projects, or the hosting application may not be a node application at all.

In this case, the host application may need to know about what files relate to a particular bundle.

Output

This plugin will generate a JSON file with the chunks & file names, so that a web server can serve the exact file without relying on pattern matching or other clumsy methods.

Example output:

{
  "vendor": {
    "source": "vendor.ba256fb84f94184bd7c4.js",
    "sourceMap": "vendor.ba256fb84f94184bd7c4.js.map",
    "priority": 1
  },
  "app": {
    "source": "app.cc61dcf6afc98dd4bb94.js",
    "css": "app.a06c4e5121fe25514b84acb9671c0faf.css",
    "sourceMap": "app.cc61dcf6afc98dd4bb94.js.map",
    "cssMap": "app.a06c4e5121fe25514b84acb9671c0faf.css.map",
    "priority": 2
  },
  "manifest": {
    "source": "manifest.cb05244398323e0b0117.js",
    "sourceMap": "manifest.cb05244398323e0b0117.js.map",
    "priority": 0
  }
}

Options

• filename string, required - The name of the generated JSON file.

• includeMap boolean - Include names for JS .map files, if they are generated by the webpack configuration.

• path string, required - The absolute path where to write the JSON file to.

• priorities [string] - The sorted list of chunks to assign priority properties to in the output. See More on priorities, below.

Example configuration

Example usage in webpack.conf.js:

module.exports = {
  entry: {
    app: path.resolve(__dirname, 'js', 'app.js'),
  },
  // ...
  plugins: [
    new webpack.optimize.CommonsChunkPlugin({
      name: 'vendor',
      minChunks: function (module) {
        return module.context && module.context.indexOf('node_modules') !== -1;
      },
    }),
    new webpack.optimize.CommonsChunkPlugin({
      name: 'manifest',
      minChunks: Infinity,
    }),
    new WebpackFileList({
      filename: 'foo.json',
      path: path.resolve(__dirname, 'bin'),
      priorities: ['manifest', 'vendor', 'app'],
    }),
  ],
}

More on priorities

The priorities option allows the user to specify (by chunk name) certain chunks that have a priority number in the output JSON. If a chunk is created which is not in this array, then no priority will be included. The priority can be used by a hosting website to order JS chunks which must be loaded first, and in which order. If the webpack is generating a manifest chunk, for example, is it required to load first, as this handles bootstrapping functions.