@benpley/wappler-cache-buster

v1.0.0

Published

19 days ago

Automatic cache busting for static assets in Wappler NodeJS projects using file modification timestamps

0High
0Medium
0Low

benpley

wappler wappler-extension server-connect cache-busting versioning static-assets ejs express nodejs helper middleware

Wappler Cache Buster

Automatic cache busting for static assets using file modification timestamps. This extension adds a cacheBuster() helper function to your EJS templates that automatically appends version numbers to your CSS, JavaScript, images, and other static assets.

Features

✅ Automatic version updates - Version only changes when files are actually modified
✅ No manual versioning - Set it and forget it
✅ Works with all static assets - CSS, JavaScript, images, fonts, PDFs, etc.
✅ Browser-friendly caching - Allows proper caching between deployments
✅ Fallback protection - Handles missing files gracefully
✅ Zero configuration - Works out of the box

Installation

Via NPM (Recommended)

Step 1: Install the package in your Wappler project directory:

npm install @benpley/wappler-cache-buster

Step 2: Create a loader file at extensions/server_connect/routes/cache-buster-loader.js:

/**
 * Cache Buster Module Loader
 */
module.exports = require('@benpley/wappler-cache-buster').loader;

Step 3: Restart your Wappler server

You should see this message in the console:

✓ Cache Buster Helper loaded - Cache busting enabled for static assets

Manual Installation

If you prefer not to use NPM:

Copy all files to extensions/server_connect/modules/cache-buster/ in your project
Create a loader file at extensions/server_connect/routes/cache-buster-loader.js:
```
module.exports = require('../modules/cache-buster/loader');
```
Restart your Wappler server

Project Structure

After installation:

your-wappler-project/
├── node_modules/
│   └── @benpley/
│       └── wappler-cache-buster/
├── extensions/
│   └── server_connect/
│       └── routes/
│           └── cache-buster-loader.js  ← Your loader file
└── public/
    ├── css/
    ├── js/
    └── assets/

Usage

Once installed, the cacheBuster() function is automatically available in all your EJS templates.

Basic Usage

CSS Files

<link rel="stylesheet" href="<%=cacheBuster('/css/style.css')%>">

Output: /css/style.css?v=1702324004815

JavaScript Files

<script src="<%=cacheBuster('/js/app.js')%>"></script>

Output: /js/app.js?v=1702324004815

Images

<img src="<%=cacheBuster('/assets/images/logo.png')%>" alt="Logo">

Output: /assets/images/logo.png?v=1702324004815

Advanced Usage

Favicon

<link rel="icon" type="image/png" href="<%=cacheBuster('/assets/images/favicon.png')%>">

Background Images (Inline CSS)

<div style="background-image: url('<%=cacheBuster('/assets/images/hero.jpg')%>')">
  Content
</div>

Open Graph Images

<meta property="og:image" content="<%=cacheBuster('/assets/images/og-image.jpg')%>">

Custom Fonts

<link rel="stylesheet" href="<%=cacheBuster('/assets/fonts/custom-font.css')%>">

Download Links

<a href="<%=cacheBuster('/assets/documents/brochure.pdf')%>" download>Download Brochure</a>

Complete Layout Example

<!doctype html>
<html>
<head>
  <meta charset="UTF-8">
  <title>My Site</title>
  
  <!-- Favicon -->
  <link rel="icon" href="<%=cacheBuster('/assets/images/favicon.png')%>">
  
  <!-- Stylesheets -->
  <link rel="stylesheet" href="<%=cacheBuster('/css/bootstrap.min.css')%>">
  <link rel="stylesheet" href="<%=cacheBuster('/css/style.css')%>">
  
  <!-- Custom Fonts -->
  <link rel="stylesheet" href="<%=cacheBuster('/assets/fonts/fonts.css')%>">
</head>
<body>
  <!-- Your content -->
  
  <!-- Scripts -->
  <script src="<%=cacheBuster('/js/jquery.min.js')%>"></script>
  <script src="<%=cacheBuster('/js/app.js')%>"></script>
</body>
</html>

How It Works

File Path: You provide a path relative to your public folder
Modification Time: The helper retrieves the file's last modification timestamp from the filesystem
Version Parameter: Appends the timestamp as a query parameter (e.g., ?v=1702324004815)
Cache Control: Browsers cache the file, but automatically fetch new versions when the file changes

Version Update Behavior

✅ Version DOES change when:

You edit and save the file
You upload a new version of the file
The file's modification date changes

❌ Version DOES NOT change when:

Users refresh the page
Server restarts (unless file was modified)
Different users visit the site

Requirements

Wappler: 5.0.0 or higher
Node.js: 12.0.0 or higher
Express: 4.0.0 or higher (included with Wappler)
Template Engine: EJS (Wappler default)
Project Type: NodeJS projects

Supported File Types

Works with any static file in your public folder:

Stylesheets: .css, .scss
Scripts: .js, .mjs
Images: .jpg, .png, .gif, .svg, .webp, .ico
Fonts: .woff, .woff2, .ttf, .otf, .eot
Documents: .pdf, .zip, .doc, .xls
Videos: .mp4, .webm, .ogg
Any other static asset

File Path Rules

✅ Must start with / - Relative to the public folder
✅ Example: /css/style.css (not css/style.css)
✅ Full path: /assets/images/subfolder/image.png

Error Handling

If a file doesn't exist or can't be accessed:

A warning is logged to the console
The helper returns the path with a current timestamp fallback
Your template continues to render without errors

Troubleshooting

Extension not loading?

Check loader file exists:

✓ extensions/server_connect/routes/cache-buster-loader.js

Check console for load message:

✓ Cache Buster Helper loaded - Cache busting enabled for static assets

Function not available in templates?

Restart server completely
Check loader file is correct
Verify you're using EJS templates
Clear browser cache

Version changing every page load?

This means the file doesn't exist:

Verify file path is correct
Check file exists in public/ folder
Ensure path starts with /

Want to force a cache bust?

Simply touch/save the file to update its modification time:

touch public/css/style.css

Updating

To update to the latest version:

npm update @benpley/wappler-cache-buster

Then restart your Wappler server.

Uninstalling

npm uninstall @benpley/wappler-cache-buster

Then:

Delete extensions/server_connect/routes/cache-buster-loader.js
Restart server
Remove cacheBuster() calls from templates

Benefits

For Developers

No manual version management needed
Versions update automatically when files are modified
No build process required
Simple to implement

For End Users

Always see the latest version of your site
No need to clear browser cache
Faster page loads through proper caching

For SEO

Consistent URLs (query parameters don't affect SEO)
Better page speed scores
Proper cache control headers

Technical Details

Module Type: Server Connect Extension
Load Priority: Before routes (ensures availability in all templates)
Performance: Minimal impact - file stats cached by OS
Memory: Negligible - no caching in application memory

API

cacheBuster(filePath)

Returns a path with version query parameter appended.

Parameters:

filePath (string) - Path relative to public folder, starting with /

Returns:

(string) - Path with version parameter (e.g., /css/style.css?v=1702324004815)

Example:

cacheBuster('/css/style.css')
// Returns: '/css/style.css?v=1702324004815'

Contributing

Contributions are welcome! If you have suggestions for improvements or find any issues, please share them on the Wappler Community Forum.

License

MIT License - Free to use in personal and commercial projects. See LICENSE file for details.

Author

Ben Pleysier

Issues and Support

For bug reports, feature requests, or assistance, please use the Wappler Community Forum.

Changelog

1.0.0 (2025-12-13)

Initial release
Basic cacheBuster functionality
Support for all static assets
Error handling and fallbacks
Comprehensive documentation

Made with ❤️ for the Wappler Community