webpack-uri-search-hash

A webpack 5 plugin that keeps emitted asset filenames stable on disk, but appends a content-derived query hash to the asset URLs webpack generates.

What it does

Instead of changing filenames like this:

• main.abc123.js
• lazy.def456.css

this plugin keeps the files themselves stable:

• main.js
• lazy.css

but rewrites the generated request URLs to include a hash in the query string:

• main.js?hash=abc123...
• lazy.css?hash=def456...

That gives you cache busting through the URL while preserving stable on-disk filenames.

What it supports

• webpack 5
• async JavaScript chunk loading
• async CSS chunk loading via mini-css-extract-plugin
• entry <script> and <link> tags generated by html-webpack-plugin

What it does not do

• it does not rename emitted files
• it does not rewrite hand-written HTML files
• it does not support webpack 4

Installation

npm install -D webpack-uri-search-hash

You will typically also use it with webpack 5, and optionally:

• html-webpack-plugin
• mini-css-extract-plugin

Usage

Basic usage

const UriSearchHashPlugin = require('webpack-uri-search-hash');

module.exports = {
  output: {
    filename: 'main.js',
    chunkFilename: '[name].js',
  },
  plugins: [new UriSearchHashPlugin()],
};

With that setup, webpack can still emit files like:

• main.js
• lazy.js

but runtime chunk requests become:

• lazy.js?hash=<contenthash>

With CSS chunks

const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const UriSearchHashPlugin = require('webpack-uri-search-hash');

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, 'css-loader'],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: 'main.css',
      chunkFilename: '[name].css',
    }),
    new UriSearchHashPlugin(),
  ],
};

Async CSS requests then become:

• lazy.css?hash=<contenthash>

With HtmlWebpackPlugin

const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const UriSearchHashPlugin = require('webpack-uri-search-hash');

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({ filename: 'main.css' }),
    new HtmlWebpackPlugin(),
    new UriSearchHashPlugin(),
  ],
};

Generated tags become:

<script defer="defer" src="main.js?hash=<contenthash>"></script>
<link href="main.css?hash=<contenthash>" rel="stylesheet">

Options

queryKey

Type: string Default: 'hash'

Controls the query parameter name.

new UriSearchHashPlugin({
  queryKey: 'v',
});

Result:

• lazy.js?v=<contenthash>

hashFormat

Type: string Default: '[contenthash]'

Controls how the hash value is rendered in the query string.

Supported forms follow webpack-style content hash placeholders:

• [contenthash]
• [contenthash:8]
• custom wrappers like v-[contenthash:8]

new UriSearchHashPlugin({
  hashFormat: 'v-[contenthash:8]',
});

Result:

• lazy.js?hash=v-1a2b3c4d

You can combine both options:

new UriSearchHashPlugin({
  queryKey: 'version',
  hashFormat: 'build-[contenthash:12]',
});

Result:

• lazy.js?version=build-1a2b3c4d5e6f

License

MIT