https://github.com/posthtml/posthtml-hash
PostHTML plugin for hashing file names
https://github.com/posthtml/posthtml-hash
asset cache hash posthtml posthtml-plugin
Last synced: 8 months ago
JSON representation
PostHTML plugin for hashing file names
- Host: GitHub
- URL: https://github.com/posthtml/posthtml-hash
- Owner: posthtml
- License: mit
- Created: 2019-08-25T22:29:05.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-12-14T18:47:39.000Z (about 1 year ago)
- Last Synced: 2025-05-08T00:41:33.753Z (9 months ago)
- Topics: asset, cache, hash, posthtml, posthtml-plugin
- Language: TypeScript
- Homepage:
- Size: 437 KB
- Stars: 7
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# posthtml-hash 
[![NPM][npm]][npm-url]
`posthtml-hash` is a [PostHTML](https://github.com/posthtml/posthtml) plugin for hashing file names to enable caching.
```diff
-
+
-
+
```
## Install
```bash
# Yarn
yarn add -D posthtml-hash
# npm
npm i -D posthtml-hash
# pnpm
pnpm i -D posthtml-hash
```
## Usage
### Input
By default, the plugin will attempt to hash file names that contain `[hash]`. As an additional qualifier, only nodes containing `href`, `src`, or `content` attributes are eligible.
```html
```
### Node.js
The recommended usage of this plugin is to incorporate it in your post-build process.
Let's say that you use Rollup to bundle and minify your CSS and JavaScript. The template `index.html` is copied to the `build` folder.
```js
// postbuild.js
const fs = require("fs");
const posthtml = require("posthtml");
const { hash } = require("posthtml-hash");
const html = fs.readFileSync("./build/index.html");
posthtml()
.use(hash({ path: "build" }))
.process(html)
.then((result) => fs.writeFileSync("./build/index.html", result.html));
```
For convenience, you can add the post-build script to your package.json. The `postbuild` script is automatically invoked following the `build` script.
```json
{
"scripts": {
"build": "rollup -c",
"postbuild": "node postbuild.js"
}
}
```
### Custom Hash Length
Customize the hash length by specifying an integer after the `hash:{NUMBER}`. The default hash length is `20`.
**Note**: This only works for a pattern that uses square brackets and a colon separator. Use the `hashLength` option for different patterns.
```html
```
### Options
This plugin assumes that the file to process is in the same directory as the PostHTML script. If not, specify the relative path to the html file in `options.path`:
```js
hash({
/**
* Relative path to the HTML file being processed
* @default ""
*/
path: "public",
/**
* File name pattern (regular expression) to match
* @default new RegExp(/\[hash.*]/g)
*/
pattern: new RegExp(/custom-file-pattern/),
/**
* Hash length
* @default 20
*/
hashLength: 8,
/**
* Transform the href/src/content attribute value to a relative file path
* @default (filepath) => filepath
*/
transformPath: (filepath) => filepath.replace("https://example.com/", ""),
});
```
## Recipes
### Custom Pattern and Hash Length
```js
hash({
pattern: new RegExp(/custom-file-pattern/),
hashLength: 8,
});
```
Result:
```diff
-
+
```
### Remote origin URLs
Input HTML:
```html
```
```js
hash({
transformPath: (filepath) => {
// removes the targeted remote origin URL when looking up the files locally
return filepath.replace("https://example.com/", "");
},
});
```
## Examples
See the [examples folder](examples) for end-to-end use cases.
## Contributing
See the [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs).
## [Changelog](CHANGELOG.md)
## License
[MIT](LICENSE)
[npm]: https://img.shields.io/npm/v/posthtml-hash.svg?color=%23fb7954
[npm-url]: https://npmjs.com/package/posthtml-hash