| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Name | Name | Last commit date | ||
|---|---|---|---|---|
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:
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 names 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 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 native 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).
| Back | FazBrowse Home | New Git URL |