A cache buster that versions a website's files for immutable cache control.
npm install cbst --save-dev # project installation (recommended)
npm install cbst --global # global installation
cbst <input dir> <output dir> [<config file>]
This diff demonstrates how versioning is applied to a simple website:
# /index.html
<!DOCTYPE html>
<html>
<head>
<title>Hello, World!</title>
- <link rel="stylesheet" href="/css/main.css">
+ <link rel="stylesheet" href="/css/main.v-ed1e118152.css">
</head>
<body>
<h1>Hello, World!</h1>
<p>
- <img id="welcome" src="/img/loading.svg">
+ <img id="welcome" src="/img/loading.v-834ab3df39.svg">
</p>
<script type="module">
- import { main } from './js/main.js';
+ import { main } from './js/main.v-f39e95e656.js';
setTimeout(main, 1000);
</script>
</body>
</html>
# /js/main.js -> /js/main.v-f39e95e656.js
- import { hello } from './hello.js';
+ import { hello } from './hello.v-93724d33b5.js';
export function main() {
hello('world');
- document.getElementById('welcome').src = '/img/welcome.svg';
+ document.getElementById('welcome').src = '/img/welcome.v-afe45bb832.svg';
}
# /css/main.css -> /css/main.v-ed1e118152.css
# /js/hello.js -> /js/hello.v-93724d33b5.js
# etc.
The configuration file (JSON) supports the following properties:
exclude
[].source
["*.html", "*.css", "*.js", "*.svg", "*.json"].html
["*.html"].dynamic
["*.html"].metadata
hashLength
10.File patterns support * (slash-free wildcards) and /**/ (directory
wildcards).
As cbst transforms files, it also rewrites any references to other versioned
files. References are detected by scanning source files for quoted strings
that
If a reference can be resolved to a file, and that file is not dynamic, the
reference is rewritten with the versioned filename.
If a reference cannot be resolved to a file, the reference is not modified.
Static files (not listed in dynamic) will be versioned based on a hash of
their contents, as well as the contents of any referenced files. Circular
references are resolved deterministically.
Static files should be delivered with a Cache-Control header that allows
browsers and proxies to cache them indefinitely. For example:
Cache-Control: public, max-age=31536000, immutable
Version tags generated by cbst are prefixed with v-. You may configure your
web server to deliver files containing .v- in their name with the above
immutable cache control header.
Dynamic files (those listed in dynamic) will not be versioned, but any
references detected inside these files will be rewritten if necessary. For
example, *.html files are usually be marked dynamic because they are directly
visited, not indirectly requested like other files.
Dynamic files should be delivered with a Cache-Control header that requires
browsers and proxies to revalidate the file in a timely fashion. Additional
E-Tag or Last-Modified headers should be provided to allow conditional
requests. For example:
Cache-Control: public, max-age=604800, stale-while-revalidate=86400
ETag: 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
See also
I can't use my favorite libraries from npm with this because they require Node.js resolution and/or bundling.
Chicken and egg problem here. The industry got used to bundlers and started building libraries for the web assuming that everyone used a bundler.
Ask library authors to ship standard ES modules. That will make all our lives easier.
Isn't bundling still more performant for larger websites?
You should be fine if your website is delivered via HTTP/2 with compression and solid cache control.
For recurring users, bundled websites that are modified regularly require downloading/parsing the entire bundle after every modification.
With fine-grained file versioning and long-term caching, the first page visit may suffer, but recurring users will have a better experience.
Finally, avoiding frameworks and large dependencies is a much more effective optimization in the first place.
What about minification?
It's out of scope for cbst. There are too many options to consider, and any
integration with minifiers will probably result in config/plug-in hell.
Instead, websites should be minified in a separate pass during a production build, usually before cache busting.
Why is this implemented with regular expressions? Everyone knows you can't parse HTML, CSS, and JS like that!!1
It's a trade-off. The RegExp-based implementation is simple, fast, and will only fail in obscure cases (hopefully).
FAQs
A cache buster that versions a website's files for immutable cache control
The npm package cbst receives a total of 7 weekly downloads. As such, cbst popularity was classified as not popular.
We found that cbst demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.