webpack-assets-manifest

What is webpack-assets-manifest?

The webpack-assets-manifest npm package is a Webpack plugin that generates a JSON file containing the mappings of all your output files. This is particularly useful for cache busting and managing asset paths in your application.

What are webpack-assets-manifest's main functionalities?

Generate Asset Manifest

This feature allows you to generate a JSON file (assets.json) that contains the mappings of your output files. This is useful for keeping track of your assets and their hashed versions.

const WebpackAssetsManifest = require('webpack-assets-manifest');

module.exports = {
  plugins: [
    new WebpackAssetsManifest({
      output: 'assets.json'
    })
  ]
};

Customize Manifest Content

This feature allows you to customize the content of the manifest file. For example, you can modify the paths of JavaScript files to include a specific directory.

const WebpackAssetsManifest = require('webpack-assets-manifest');

module.exports = {
  plugins: [
    new WebpackAssetsManifest({
      customize: (entry, original, manifest, asset) => {
        if (entry.key.endsWith('.js')) {
          entry.value = `/static/js/${entry.value}`;
        }
        return entry;
      }
    })
  ]
};

Integrate with Webpack Dev Server

This feature allows you to integrate the manifest with the Webpack Dev Server. You can serve the manifest file via an endpoint, making it accessible during development.

const WebpackAssetsManifest = require('webpack-assets-manifest');

module.exports = {
  devServer: {
    before: (app, server) => {
      const manifest = server.compiler.options.plugins.find(
        plugin => plugin instanceof WebpackAssetsManifest
      );
      app.get('/assets.json', (req, res) => {
        res.json(manifest.getRawManifest());
      });
    }
  },
  plugins: [
    new WebpackAssetsManifest()
  ]
};

Other packages similar to webpack-assets-manifest

webpack-manifest-plugin

The webpack-manifest-plugin is another Webpack plugin that generates a manifest file mapping the original filenames to their corresponding output filenames. It is similar to webpack-assets-manifest but offers different customization options and a slightly different API.

html-webpack-plugin

The html-webpack-plugin simplifies the creation of HTML files to serve your webpack bundles. While it is not a direct replacement for webpack-assets-manifest, it can be used to inject asset paths into HTML files, achieving similar goals in terms of asset management.

webpack-bundle-analyzer

The webpack-bundle-analyzer is a plugin and CLI utility that represents bundle content as a convenient interactive zoomable treemap. While its primary focus is on bundle analysis, it also provides insights into asset management and can be used alongside webpack-assets-manifest for a more comprehensive asset management strategy.

README

Webpack Assets Manifest

This webpack plugin will generate a JSON file that matches the original filename with the hashed version.

Installation

pnpm add -D webpack-assets-manifest

npm install webpack-assets-manifest -D

yarn add webpack-assets-manifest -D

New in version 6

• This plugin is now written with TypeScript.
• TypeScript types are provided by this package.
• The package exports esm and cjs.
• Added manifest.utils for use in the customize hook.
  • See examples/customized.js
  • https://github.com/webdeveric/webpack-assets-manifest/blob/b6ed8c09394bf33c8fadd5adff8bad7694f295ba/src/plugin.ts#L185-L195

Breaking changes

• Bumped minimum webpack version to 5.61
• Bumped minimum Node version to 20.10
• The plugin is exported using a named export instead of default.
  • Use import { WebpackAssetsManifest } from 'webpack-assets-manifest';

New in version 5

• Compatible with webpack 5 only (5.1+ required).
• Supports finding asset modules.
• Updated options schema to prevent additional properties. This helps with catching typos in option names.
• :warning: Updated default value of the output option to be assets-manifest.json. This is to prevent confusion when working with Web app manifests or WebExtension manifests.

New in version 4

• Requires Node 10+.

• Compatible with webpack 4 only (4.40+ required).

• Added options: enabled, entrypointsUseAssets, contextRelativeKeys.

• Updated writeToDisk option to default to auto.

• Use lock files for various operations.

• done hook is now an AsyncSeriesHook.

• :warning: The structure of the entrypoints data has been updated to include preload and prefetch assets. Assets for an entrypoint are now included in an assets property under the entrypoint.

  Example:

  {
    "entrypoints": {
      "main": {
        "assets": {
          "css": ["main.css"],
          "js": ["main.js"]
        },
        "prefetch": {
          "js": ["prefetch.js"]
        },
        "preload": {
          "js": ["preload.js"]
        }
      }
    }
  }
  

Usage

In your webpack config, require the plugin then add an instance to the plugins array.

import { WebpackAssetsManifest } from 'webpack-assets-manifest';

export default {
  entry: {
    // Your entry points
  },
  output: {
    // Your output details
  },
  module: {
    // Your loader rules go here.
  },
  plugins: [
    new WebpackAssetsManifest({
      // Options go here
    }),
  ],
};

Sample output

{
  "main.js": "main-9c68d5e8de1b810a80e4.js",
  "main.css": "main-9c68d5e8de1b810a80e4.css",
  "images/logo.svg": "images/logo-b111da4f34cefce092b965ebc1078ee3.svg"
}

Options (read the schema)

enabled

Type: boolean

Default: true

Is the plugin enabled?

output

Type: string

Default: assets-manifest.json

This is where to save the manifest file relative to your webpack output.path.

assets

Type: object

Default: {}

Data is stored in this object.

Sharing data

You can share data between instances by passing in your own object in the assets option.

This is useful in multi-compiler mode.

const data = Object.create(null);

const manifest1 = new WebpackAssetsManifest({
  assets: data,
});

const manifest2 = new WebpackAssetsManifest({
  assets: data,
});

contextRelativeKeys

Type: boolean

Default: false

Keys are relative to the compiler context.

space

Type: int

Default: 2

Number of spaces to use for pretty printing.

replacer

Type: null, function, or array

Default: null

Replacer reference

You'll probably want to use the transform hook instead.

fileExtRegex

Type: regex

Default: /\.\w{2,4}\.(?:map|gz)$|\.\w+$/i

This is the regular expression used to find file extensions. You'll probably never need to change this.

writeToDisk

Type: boolean, string

Default: 'auto'

Write the manifest to disk using fs.

:warning: If you're using another language for your site and you're using webpack-dev-server to process your assets during development, you should set writeToDisk: true and provide an absolute path in output so the manifest file is actually written to disk and not kept only in memory.

sortManifest

Type: boolean, function

Default: true

The manifest is sorted alphabetically by default. You can turn off sorting by setting sortManifest: false.

If you want more control over how the manifest is sorted, you can provide your own comparison function. See the sorted example.

new WebpackAssetsManifest({
  sortManifest(left, right) {
    // Return -1, 0, or 1
  },
});

merge

Type: boolean, string

Default: false

If the output file already exists and you'd like to add to it, use merge: true. The default behavior is to use the existing keys/values without modification.

new WebpackAssetsManifest({
  output: '/path/to/manifest.json',
  merge: true,
});

If you need to customize during merge, use merge: 'customize'.

If you want to know if customize was called when merging with an existing manifest, you can check manifest.isMerging.

new WebpackAssetsManifest({
  merge: 'customize',
  customize(entry, original, manifest, asset) {
    if ( manifest.isMerging ) {
      // Do something
    }
  },
}),

publicPath

Type: string, function, boolean,

Default: null

When using publicPath: true, your webpack config output.publicPath will be used as the value prefix.

const manifest = new WebpackAssetsManifest({
  publicPath: true,
});

When using a string, it will be the value prefix. One common use is to prefix your CDN URL.

const manifest = new WebpackAssetsManifest({
  publicPath: 'https://cdn.example.com',
});

If you'd like to have more control, use a function. See the custom CDN example.

const manifest = new WebpackAssetsManifest({
  publicPath(filename, manifest) {
    // customize filename here
    return filename;
  },
});

entrypoints

Type: boolean

Default: false

Include compilation.entrypoints in the manifest file.

entrypointsKey

Type: string, boolean

Default: entrypoints

If this is set to false, the entrypoints will be added to the root of the manifest.

entrypointsUseAssets

Type: boolean

Default: false

Entrypoint data should use the value from assets, which means the values could be customized and not just a string file path. This new option defaults to false so the new behavior is opt-in.

integrity

Type: boolean

Default: false

Include the subresource integrity hash.

integrityHashes

Type: array

Default: [ 'sha256', 'sha384', 'sha512' ]

Hash algorithms to use when generating SRI. For browsers, the currently the allowed integrity hashes are sha256, sha384, and sha512.

Other hash algorithms can be used if your target environment is not a browser. If you were to create a tool to audit your S3 buckets for data integrity, you could use something like this example to record the md5 hashes.

integrityPropertyName

Type: string

Default: integrity

This is the property that will be set on each entry in compilation.assets, which will then be available during customize. It is customizable so that you can have multiple instances of this plugin and not have them overwrite the currentAsset.integrity property.

You'll probably only need to change this if you're using multiple instances of this plugin to create different manifests.

apply

Type: function

Default: null

Callback to run after setup is complete.

customize

Type: function

Default: null

Callback to customize each entry in the manifest.

You can use this to customize entry names for example. In the sample below, we adjust img keys so that it's easier to use them with a template engine:

new WebpackAssetsManifest({
  customize(entry, original, manifest, asset) {
    if (manifest.utils.isKeyValuePair(entry) && entry.key.startsWith('img/')) {
      return { key: entry.key.split('img/')[1], value: entry.value };
    }

    return entry;
  }
}

The function is called per each entry and provides you a way to intercept and rewrite each object. The result is then merged into a whole manifest.

View the example to see what else you can do with this function.

transform

Type: function

Default: null

Callback to transform the entire manifest.

done

Type: function

Default: null

Callback to run after the compilation is done and the manifest has been written.

Hooks

This plugin is using hooks from Tapable.

The apply, customize, transform, and done options are automatically tapped into the appropriate hook.

Name	Type	Callback signature
apply	SyncHook	function(manifest){}
customize	SyncWaterfallHook	function(entry, original, manifest, asset){}
transform	SyncWaterfallHook	function(assets, manifest){}
done	AsyncSeriesHook	async function(manifest, stats){}
options	SyncWaterfallHook	function(options){}
afterOptions	SyncHook	function(options){}

Tapping into hooks

Tap into a hook by calling the tap method on the hook as shown below.

If you want more control over exactly what gets added to your manifest, then use the customize and transform hooks. See the customized and transformed examples.

const manifest = new WebpackAssetsManifest();

manifest.hooks.apply.tap('YourPluginName', function (manifest) {
  // Do something here
  manifest.set('some-key', 'some-value');
});

manifest.hooks.customize.tap('YourPluginName', function (entry, original, manifest, asset) {
  // customize entry here
  return entry;
});

manifest.hooks.transform.tap('YourPluginName', function (assets, manifest) {
  // customize assets here
  return assets;
});

manifest.hooks.options.tap('YourPluginName', function (options) {
  // customize options here
  return options;
});

manifest.hooks.done.tap('YourPluginName', function (manifest, stats) {
  console.log(`The manifest has been written to ${manifest.getOutputPath()}`);
  console.log(`${manifest}`);
});

manifest.hooks.done.tapPromise('YourPluginName', async (manifest, stats) => {
  await yourAsyncOperation();
});

These hooks can also be set by passing them in the constructor options.

new WebpackAssetsManifest({
  done(manifest, stats) {
    console.log(`The manifest has been written to ${manifest.getOutputPath()}`);
    console.log(`${manifest}`);
  },
});

Manifest methods

If the manifest instance is passed to a hook, you can use the following methods to manage what goes into the manifest.

• has(key)
• get(key)
• set(key, value)
• setRaw(key, value)
• delete(key)

If you want to write the manifest to another location, you can use writeTo(destination).

new WebpackAssetsManifest({
  async done(manifest) {
    await manifest.writeTo('/some/other/path/assets-manifest.json');
  },
});