html-assets-hash

html-assets-hash

A lightweight CLI tool that appends short hashes to your HTML asset URLs to help avoid loading outdated files from the browser cache.

This tool replaces placeholder version parameters in your HTML asset URLs with a hash of the corresponding file’s contents. It scans for <script> and <link> tags that include src or href attributes with a version parameter like ?v=, such as:

<script src="app.js?v="></script>
<link href="style.css?v=" rel="stylesheet">

This placeholder acts as an intentional marker — only assets with ?v= will be modified. When run, the tool computes a SHA-256 hash of each referenced asset (e.g. app.js, style.css) and inserts the first 8 characters of that hash into the URL:

<script src="app.js?v=a1b2c3d4"></script>
<link href="style.css?v=e5f6g7h8" rel="stylesheet">

If a version string is already present (e.g. ?v=old1234), it will be updated with the current hash. Assets without a ?v= marker remain unchanged, giving you control over which URLs should be processed.

• External URLs (like CDNs) are ignored.

• Asset URLs with multiple query parameters (e.g. ?v=1234&foo=bar) are not modified.

• Targeted <script> and <link> tags must not contain < or > characters within them (including in attribute values); such tags are skipped and not processed.

For simplicity and zero dependencies, the HTML is parsed using regular expressions. While not a general-purpose solution for HTML parsing, it's reliable for this narrowly defined use case.

Usage

npx html-assets-hash <html-file-path> [base-path]

• <html-file-path>: Path to the HTML file to process
• [base-path]: (Optional) Base directory to resolve relative asset paths. Defaults to the HTML file's directory

Example

npx html-assets-hash public/index.html

This will transform:

<script src="app.js?v="></script>
<link href="styles.css?v=old456" rel="stylesheet">

Into:

<script src="app.js?v=a1b2c3d4"></script>
<link href="styles.css?v=e5f6g7h8" rel="stylesheet">

Notes on security

• This tool is intended to run only on trusted input, specifically well-formed HTML files.

• It does not sanitize or restrict file access. A malicious HTML file could be crafted to:

  • Enumerate files on the local system.

  • Compute and exfiltrate partial SHA-256 hashes of local files.

• Do not use this tool on untrusted or user-generated content.

License

This project is licensed under the terms of the Apache License, Version 2.0

Get involved

Check out the CONTRIBUTING file to learn how to contribute, and the CONTRIBUTORS file to see who’s helped make it happen.