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

How it works

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

Inspired by Trunk, html-asset-hasher looks for data-hasher and data-file attributes on <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.

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

Once you're ready, run html-asset-hasher against your static HTML file. 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.15]
      --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-file="src/styles/main.css" rel="stylesheet" />

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"
/>

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

Contributing

To contribute to html-asset-hasher, you'll need to install Cocogitto:

cargo install cocogitto

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

./install-hooks.sh

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

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