html-asset-hasher

Asset cache busting for your static HTML files, with optional Tailwind CSS bundling!

summary source mailing lists tickets

Getting started

Requirements

• cargo
• tailwindcss (optional)

Tailwind CSS support (optional)

Refer to the Tailwind CSS documentation for configuration details. If Tailwind CSS isn't installed, the tailwindcss binary will be downloaded and used to generate the CSS.

Installation

With cargo:

cargo install html-asset-hasher

Building from git:

cargo install --git https://git.sr.ht/~quaff/html-asset-hasher

With cargo-binstall:

cargo binstall html-asset-hasher

Note: Currently, only supports Linux; For improved build times in your CI/CD pipelines.

How it works

html-asset-hasher currently supports <img>, <link> and <script> tags for images, stylesheets and scripts. It also offers Subresource Integrity (SRI) support.

Inspired by Trunk, html-asset-hasher looks for data-hasher, data-file and data-url attributes on <img>, <link> and <script> tags:

• data-hasher: A flag attribute that indicates the tag should be parsed.
• data-file: Specifies the relative path to the asset you want to hash.
• data-url: Specifies the URL you want to download and hash.

Note: if both are present, data-url will take precedence over data-file.

That's it! These few attributes are all you need to enable cache busting.

Once you're ready, run html-asset-hasher against your static HTML file. By default, the generated files will be output to the dist/ directory in your root working directory.

Usage

Usage: html-asset-hasher [OPTIONS] [PATHS]...

Arguments:
  [PATHS]...  Input HTML files or directories

Options:
  -o, --output <DIR>                         Output directory [default: dist]
  -s, --sha2-hash <SHA2_HASH>                SHA2 Hash algorithm [default: sha384]
  -t, --tailwind-version <TAILWIND_VERSION>  TailwindCSS version to download [default: 3.4.17]
      --debug                                Turn debugging information on
  -h, --help                                 Print help
  -V, --version                              Print version

Example

Here’s an example of how to use html-asset-hasher in an HTML file (index.html):

<link data-hasher data-file="assets/favicon.ico" rel="icon" />
<link data-hasher data-file="src/styles/tailwind.css" rel="tailwind-css" />
<link data-hasher data-url="https://example.com/main.css" rel="stylesheet" />
<script
  data-hasher
  data-file="src/scripts/main.js"
  type="text/javascript"
></script>
<img data-hasher data-url="https://example.com/image.png" alt="example image" />

To process the file, run:

html-asset-hasher index.html

The generated HTML will be saved to dist/index.html, and it will look something like this:

<link
  rel="icon"
  href="favicon.iLfWPvSXyJusY1MS4bh2Gg-Eq5FzRNNFH2qBtptWOJ30c8AYPl5L7aR1dKtwp_no.ico"
/>
<link
  rel="stylesheet"
  href="tailwind.COunCCmPUZVOsiyGCRp7tDQxoo3jOzAScLezMwB8ygZPmPJCZHuLypHXRUbusv0N.css"
  integrity="sha384-COunCCmPUZVOsiyGCRp7tDQxoo3jOzAScLezMwB8ygZPmPJCZHuLypHXRUbusv0N"
/>
<link
  rel="stylesheet"
  href="main.E1QXOJQvt1C-Cewy5WvqKozszqqDMGydV4TeOw3lEoJS1xClsbKBBWyCFKMDi34V.css"
  integrity="sha384-E1QXOJQvt1C+Cewy5WvqKozszqqDMGydV4TeOw3lEoJS1xClsbKBBWyCFKMDi34V"
/>
<script
  src="main.1H217gwSVyLSIfaLxHbE7dRb3v4mYCKbpQvzx0cegeju1MVsGrX5xXxAvs_HgeFs.js"
  integrity="sha384-1H217gwSVyLSIfaLxHbE7dRb3v4mYCKbpQvzx0cegeju1MVsGrX5xXxAvs+HgeFs"
  crossorigin="anonymous"
></script>
<img
  src="image.e1QXOJQvt1C+Cewy5WvqKozszqqDMGydV4TeOw3lEoJS1xClsbKBBWyCFKMDi34V.png"
  alt="example image"
/>

For a full working demo, check out the code for my website.

Contributing

To contribute to html-asset-hasher, you'll need npm on your system, install nodejs-18 or higher with your package manager of choice.

Next, run the following script in the root of the repository to install the necessary Git hooks along with commitlint:

./contributing.sh

These hooks will ensure that your commits adhere to project standards.

For more information on commit conventions, refer to the Conventional Commits guidelines.