@superhuman/assets-webpack-plugin

assets-webpack-plugin

Webpack plugin that emits a json file with assets paths.

Table of Contents

• Why Is This Useful?

• Install

• Configuration

• Test

• Change Log

• Contributing Guidelines

Why Is This Useful?

When working with Webpack you might want to generate your bundles with a generated hash in them (for cache busting).

This plug-in outputs a json file with the paths of the generated assets so you can find them from somewhere else.

Example output:

The output is a JSON object in the form:

{
    "entries": {
      "bundle_name": {
          "asset_kind": "/public/path/to/asset"
      }
    },
    "assets": [{
        "name": "hello.svg",
        "path": "/public/path/to/asset/hello.svg"
      }
    ]
}

Where:

• entries is an object that contains all entry points listed in your webpack config
  • "bundle_name" is the name of the bundle (the key of the entry object in your webpack config, or "main" if your entry is an array).
  • "asset_kind" is the camel-cased file extension of the asset
• assets is an array containing all assets processed by webpack
  • name is the name of the image (path used in require or import)
  • path is the webpack generated public path to the image

For example, given the following webpack config:

{
    entry: {
        one: ['src/one.js'],
        two: ['src/two.js']
    },
    output: {
        path: path.join(__dirname, "public", "js"),
        publicPath: "/js/",
        filename: '[name]_[hash].bundle.js'
    }
}

and import of an image somewhere in application code using

import user from '../../assets/images/user.svg';

The plugin will output the following json file:

{
    "one": {
        "js": "/js/one_2bb80372ebe8047a68d4.bundle.js"
    },
    "two": {
        "js": "/js/two_2bb80372ebe8047a68d4.bundle.js"
    },
    "assets":[{
      "name":"assets/images/user.svg",
      "path":"/js/assets/images/user.svg"
    }]
}

Install

npm install assets-webpack-plugin --save-dev

Configuration

In your webpack config include the plug-in. And add it to your config:

var path = require('path')
var AssetsPlugin = require('assets-webpack-plugin')
var assetsPluginInstance = new AssetsPlugin()

module.exports = {
    // ...
    output: {
        path: path.join(__dirname, "public", "js"),
        filename: "[name]-bundle-[hash].js",
        publicPath: "/js/"
    },
    // ....
    plugins: [assetsPluginInstance]
}

Options

You can pass the following options:

filename: Name for the created json file. Defaults to webpack-assets.json

new AssetsPlugin({filename: 'assets.json'})

fullPath: True by default. If false the output will not include the full path of the generated file.

new AssetsPlugin({fullPath: false})

e.g.

/public/path/bundle.js vs bundle.js

path: Path where to save the created json file. Defaults to the current directory.

new AssetsPlugin({path: path.join(__dirname, 'app', 'views')})

prettyPrint: Whether to format the json output for readability. Defaults to false.

new AssetsPlugin({prettyPrint: true})

processOutput: Formats the assets output. Defaults is JSON stringify function.

new AssetsPlugin({
    processOutput: function (assets) {
        return 'window.staticMap = ' + JSON.stringify(assets)
    }
})

update: When set to true, the output json file will be updated instead of overwritten. Defaults to false.

new AssetsPlugin({update: true})

metadata: Inject metadata into the output file. All values will be injected into the key "metadata".

new AssetsPlugin({metadata: {version: 123}})

// Manifest will now contain:
// {
//   metadata: {version: 123}
// }

assetsRegex: Regex for assets that should be extracted from Webpack stats. Defaults to /\.(jpe?g|png|gif|svg)$/

new AssetsPlugin({assetsRegex: /\.(svg)$/})

Using in multi-compiler mode

If you use webpack multi-compiler mode and want your assets written to a single file, you must use the same instance of the plugin in the different configurations.

For example:

var webpack = require('webpack')
var AssetsPlugin = require('assets-webpack-plugin')
var assetsPluginInstance = new AssetsPlugin()

webpack([
    {
        entry: {one: 'src/one.js'},
        output: {path: 'build', filename: 'one-bundle.js'},
        plugins: [assetsPluginInstance]
    },
    {
        entry: {two:'src/two.js'},
        output: {path: 'build', filename: 'two-bundle.js'},
        plugins: [assetsPluginInstance]
    }
])

Using this with Rails

You can use this with Rails to find the bundled Webpack assets via sprockets. In ApplicationController you might have:

def script_for(bundle)
  path = Rails.root.join('app', 'views', 'webpack-assets.json') # This is the file generated by the plug-in
  file = File.read(path)
  json = JSON.parse(file)
  json['entries'][bundle]['js']
end

Then in the actions:

def show
  @script = script_for('clients') # this will retrieve the bundle named 'clients'
end

And finally in the views:

<div id="app">
  <script src="<%= @script %>"></script>
</div>

Test

npm test