rollup-plugin-source-hash

A rollup.js plugin that inserts hash values based on pre-bundled source code into filenames and bundled code.

Features

• Generates hash values based on pre-bundled source code
• Inserts hash values in bundle code and filenames
• Supports custom placeholders
• Deletes outdated bundles on each build (optional)

Why?

Rollup's built-in [hash] naming option and various hash-related plugins generate hash values based on the bundled output. This means bundles created from the same source that use different rollup configurations (output format, transpilation, minification, comments, etc.) will generate different hash values:

# Rollup [hash] and other plugins
# Same source code, different hash for each file
bundle-742cd4.cjs
bundle-ddc4fb.js
bundle-8023f4.min.js
bundle-c463f6.mjs

This plugin generates hash values based on the source code before Rollup has completed its bundling process. As a result, bundles created from the same source code will generate the same hash value regardless of the rollup configuration used to create them. This hash value serves as a build ID, easily identifying all bundles generated from the same source code:

# This plugin
# Same source code, same hash for each file
bundle-742cd4.cjs
bundle-742cd4.js
bundle-742cd4.min.js
bundle-742cd4.mjs

This plugin can also inject a generated hash value into the bundled output:

// Source
const hash = '__SOURCEHASH__'; // Default

// Bundle output
const hash = '742cd4';

Installation

NPM

npm install --save-dev rollup-plugin-source-hash

Usage

// Rollup configuration
import sourceHash from 'rollup-plugin-source-hash';

export default {
  input: 'main.js',
  output: {
    file: 'bundle-[sourcehash].js' // Default
  },
  plugins: [
    sourceHash({
      // Options...
    })
  ]
};

The filePlaceholder value will be replaced with the generated source hash:

# Bundle file
bundle-742cd4.js

All codePlaceholders will be replaced with the generated source hash:

// Source: main.js
const hash = '__SOURCEHASH__'; // Default

// Bundle: bundle-742cd4.js
const hash = '742cd4';

Options

autoDelete

• Type: boolean
• Default: true

Determines if previous builds will be automatically deleted when new builds are generated.

sourceHash({
  autoDelete: true // Default
});

The plugin will search for previous builds in the same output directory and match files based on the name pattern and hash value length. For example, if a name pattern of "bundle-[sourcehash].js" is used to generate a new bundle named bundle-742cd4.js, all files that start with bundle-, are followed by an eight character alphanumeric value, and end with .js will be deleted.

// Rollup configuration
output: {
  file: 'bundle-[sourcehash].js'; // Default
}

# Bundle file
bundle-742cd4.js

# These files will be deleted
bundle-ddc4fb.js
bundle-8023f4.js
bundle-c463f6.js

# These files will not be deleted
bundle.js
bundle-acbd18db4cc2f85cedef654fccc4a4d8.js

codePlaceholder

• Type: string
• Default: "__SOURCEHASH__";

The source code placeholder string to replace with the generated hash value.

sourceHash({
  codePlaceholder: '__SOURCEHASH__'
});

filePlaceholder

• Type: string
• Default: "[sourcehash]"

The bundle file name placeholder string to replace with the generated hash value.

sourceHash({
  filePlaceholder: '[sourcehash]'
});

hashArgs

• Type: array|string
• Default: ["shake256", { outputLength: 3 }]

The arguments to pass to Node's crypto.createHash method.

// Array
sourceHash({
  hashArgs: ['shake256', { outputLength: 3 }]
});

// String
sourceHash({
  hashArgs: 'md5'
});

From the Node.js createHash documentation:

The algorithm is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are 'sha256', 'sha512', etc. On recent releases of OpenSSL, openssl list -digest-algorithms will display the available digest algorithms.

For XOF hash functions such as 'shake256', the outputLength option can be used to specify the desired output length in bytes.

Sponsorship

A sponsorship is more than just a way to show appreciation for the open-source authors and projects we rely on; it can be the spark that ignites the next big idea, the inspiration to create something new, and the motivation to share so that others may benefit.

If you benefit from this project, please consider lending your support and encouraging future efforts by becoming a sponsor.

Thank you! 🙏🏻

Contact & Support

• Follow 👨🏻‍💻 @jhildenbiddle on Twitter and GitHub for announcements
• Create a 💬 GitHub issue for bug reports, feature requests, or questions
• Add a ⭐️ star on GitHub and 🐦 tweet to promote the project
• Become a 💖 sponsor to support the project and future efforts

License

This project is licensed under the MIT License. See the LICENSE for details.

Copyright (c) John Hildenbiddle (@jhildenbiddle)