{"_id":"@benpley/wappler-cache-buster","name":"@benpley/wappler-cache-buster","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@benpley/wappler-cache-buster","version":"1.0.0","description":"Automatic cache busting for static assets in Wappler NodeJS projects using file modification timestamps","main":"index.js","scripts":{"test":"echo \"No tests specified\" && exit 0"},"keywords":["wappler","wappler-extension","server-connect","cache-busting","versioning","static-assets","ejs","express","nodejs","helper","middleware"],"author":{"name":"Ben Pleysier"},"license":"MIT","engines":{"node":">=12.0.0"},"peerDependencies":{"express":">=4.0.0"},"_id":"@benpley/wappler-cache-buster@1.0.0","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-vygCavAoCVZPIDbJWSxcIVpAXFSHirj8Cbi3dQFNszzoRXGkWPpcVANsPrRwVcR+JNRsy81MOVMCZXrbPyARig==","shasum":"915d64f9d3e2df40769ee287d711fad1c377750e","tarball":"https://registry.npmjs.org/@benpley/wappler-cache-buster/-/wappler-cache-buster-1.0.0.tgz","fileCount":6,"unpackedSize":12921,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC3gfAslwQxB4z2I9+QChs/FKSBsER0MXxJskFmsuQtwwIhAJsNVI77lc8dGvOHPKRGuD40uMON9mR1WNu1L1AyDT21"}]},"_npmUser":{"name":"benpley","email":"ben@pleysier.com.au"},"directories":{},"maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wappler-cache-buster_1.0.0_1765617264492_0.021400682180297226"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-13T09:14:24.381Z","1.0.0":"2025-12-13T09:14:24.646Z","modified":"2025-12-13T09:14:24.960Z"},"maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"description":"Automatic cache busting for static assets in Wappler NodeJS projects using file modification timestamps","keywords":["wappler","wappler-extension","server-connect","cache-busting","versioning","static-assets","ejs","express","nodejs","helper","middleware"],"author":{"name":"Ben Pleysier"},"license":"MIT","readme":"# Wappler Cache Buster\n\nAutomatic 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.\n\n## Features\n\n✅ **Automatic version updates** - Version only changes when files are actually modified  \n✅ **No manual versioning** - Set it and forget it  \n✅ **Works with all static assets** - CSS, JavaScript, images, fonts, PDFs, etc.  \n✅ **Browser-friendly caching** - Allows proper caching between deployments  \n✅ **Fallback protection** - Handles missing files gracefully  \n✅ **Zero configuration** - Works out of the box  \n\n## Installation\n\n### Via NPM (Recommended)\n\n**Step 1:** Install the package in your Wappler project directory:\n\n```bash\nnpm install @benpley/wappler-cache-buster\n```\n\n**Step 2:** Create a loader file at `extensions/server_connect/routes/cache-buster-loader.js`:\n\n```javascript\n/**\n * Cache Buster Module Loader\n */\nmodule.exports = require('@benpley/wappler-cache-buster').loader;\n```\n\n**Step 3:** Restart your Wappler server\n\nYou should see this message in the console:\n```\n✓ Cache Buster Helper loaded - Cache busting enabled for static assets\n```\n\n### Manual Installation\n\nIf you prefer not to use NPM:\n\n1. Copy all files to `extensions/server_connect/modules/cache-buster/` in your project\n2. Create a loader file at `extensions/server_connect/routes/cache-buster-loader.js`:\n   ```javascript\n   module.exports = require('../modules/cache-buster/loader');\n   ```\n3. Restart your Wappler server\n\n### Project Structure\n\nAfter installation:\n```\nyour-wappler-project/\n├── node_modules/\n│   └── @benpley/\n│       └── wappler-cache-buster/\n├── extensions/\n│   └── server_connect/\n│       └── routes/\n│           └── cache-buster-loader.js  ← Your loader file\n└── public/\n    ├── css/\n    ├── js/\n    └── assets/\n```\n\n## Usage\n\nOnce installed, the `cacheBuster()` function is automatically available in all your EJS templates.\n\n### Basic Usage\n\n#### CSS Files\n```html\n<link rel=\"stylesheet\" href=\"<%=cacheBuster('/css/style.css')%>\">\n```\nOutput: `/css/style.css?v=1702324004815`\n\n#### JavaScript Files\n```html\n<script src=\"<%=cacheBuster('/js/app.js')%>\"></script>\n```\nOutput: `/js/app.js?v=1702324004815`\n\n#### Images\n```html\n<img src=\"<%=cacheBuster('/assets/images/logo.png')%>\" alt=\"Logo\">\n```\nOutput: `/assets/images/logo.png?v=1702324004815`\n\n### Advanced Usage\n\n#### Favicon\n```html\n<link rel=\"icon\" type=\"image/png\" href=\"<%=cacheBuster('/assets/images/favicon.png')%>\">\n```\n\n#### Background Images (Inline CSS)\n```html\n<div style=\"background-image: url('<%=cacheBuster('/assets/images/hero.jpg')%>')\">\n  Content\n</div>\n```\n\n#### Open Graph Images\n```html\n<meta property=\"og:image\" content=\"<%=cacheBuster('/assets/images/og-image.jpg')%>\">\n```\n\n#### Custom Fonts\n```html\n<link rel=\"stylesheet\" href=\"<%=cacheBuster('/assets/fonts/custom-font.css')%>\">\n```\n\n#### Download Links\n```html\n<a href=\"<%=cacheBuster('/assets/documents/brochure.pdf')%>\" download>Download Brochure</a>\n```\n\n### Complete Layout Example\n\n```html\n<!doctype html>\n<html>\n<head>\n  <meta charset=\"UTF-8\">\n  <title>My Site</title>\n  \n  <!-- Favicon -->\n  <link rel=\"icon\" href=\"<%=cacheBuster('/assets/images/favicon.png')%>\">\n  \n  <!-- Stylesheets -->\n  <link rel=\"stylesheet\" href=\"<%=cacheBuster('/css/bootstrap.min.css')%>\">\n  <link rel=\"stylesheet\" href=\"<%=cacheBuster('/css/style.css')%>\">\n  \n  <!-- Custom Fonts -->\n  <link rel=\"stylesheet\" href=\"<%=cacheBuster('/assets/fonts/fonts.css')%>\">\n</head>\n<body>\n  <!-- Your content -->\n  \n  <!-- Scripts -->\n  <script src=\"<%=cacheBuster('/js/jquery.min.js')%>\"></script>\n  <script src=\"<%=cacheBuster('/js/app.js')%>\"></script>\n</body>\n</html>\n```\n\n## How It Works\n\n1. **File Path**: You provide a path relative to your `public` folder\n2. **Modification Time**: The helper retrieves the file's last modification timestamp from the filesystem\n3. **Version Parameter**: Appends the timestamp as a query parameter (e.g., `?v=1702324004815`)\n4. **Cache Control**: Browsers cache the file, but automatically fetch new versions when the file changes\n\n### Version Update Behavior\n\n✅ **Version DOES change when:**\n- You edit and save the file\n- You upload a new version of the file\n- The file's modification date changes\n\n❌ **Version DOES NOT change when:**\n- Users refresh the page\n- Server restarts (unless file was modified)\n- Different users visit the site\n\n## Requirements\n\n- **Wappler**: 5.0.0 or higher\n- **Node.js**: 12.0.0 or higher\n- **Express**: 4.0.0 or higher (included with Wappler)\n- **Template Engine**: EJS (Wappler default)\n- **Project Type**: NodeJS projects\n\n## Supported File Types\n\nWorks with **any static file** in your `public` folder:\n\n- **Stylesheets**: `.css`, `.scss`\n- **Scripts**: `.js`, `.mjs`\n- **Images**: `.jpg`, `.png`, `.gif`, `.svg`, `.webp`, `.ico`\n- **Fonts**: `.woff`, `.woff2`, `.ttf`, `.otf`, `.eot`\n- **Documents**: `.pdf`, `.zip`, `.doc`, `.xls`\n- **Videos**: `.mp4`, `.webm`, `.ogg`\n- **Any other static asset**\n\n## File Path Rules\n\n- ✅ **Must start with `/`** - Relative to the `public` folder\n- ✅ **Example**: `/css/style.css` (not `css/style.css`)\n- ✅ **Full path**: `/assets/images/subfolder/image.png`\n\n## Error Handling\n\nIf a file doesn't exist or can't be accessed:\n- A warning is logged to the console\n- The helper returns the path with a current timestamp fallback\n- Your template continues to render without errors\n\n## Troubleshooting\n\n### Extension not loading?\n\n**Check loader file exists:**\n```\n✓ extensions/server_connect/routes/cache-buster-loader.js\n```\n\n**Check console for load message:**\n```\n✓ Cache Buster Helper loaded - Cache busting enabled for static assets\n```\n\n### Function not available in templates?\n\n1. Restart server completely\n2. Check loader file is correct\n3. Verify you're using EJS templates\n4. Clear browser cache\n\n### Version changing every page load?\n\nThis means the file doesn't exist:\n- Verify file path is correct\n- Check file exists in `public/` folder\n- Ensure path starts with `/`\n\n### Want to force a cache bust?\n\nSimply touch/save the file to update its modification time:\n```bash\ntouch public/css/style.css\n```\n\n## Updating\n\nTo update to the latest version:\n\n```bash\nnpm update @benpley/wappler-cache-buster\n```\n\nThen restart your Wappler server.\n\n## Uninstalling\n\n```bash\nnpm uninstall @benpley/wappler-cache-buster\n```\n\nThen:\n- Delete `extensions/server_connect/routes/cache-buster-loader.js`\n- Restart server\n- Remove `cacheBuster()` calls from templates\n\n## Benefits\n\n### For Developers\n- No manual version management needed\n- Versions update automatically when files are modified\n- No build process required\n- Simple to implement\n\n### For End Users\n- Always see the latest version of your site\n- No need to clear browser cache\n- Faster page loads through proper caching\n\n### For SEO\n- Consistent URLs (query parameters don't affect SEO)\n- Better page speed scores\n- Proper cache control headers\n\n## Technical Details\n\n- **Module Type**: Server Connect Extension\n- **Load Priority**: Before routes (ensures availability in all templates)\n- **Performance**: Minimal impact - file stats cached by OS\n- **Memory**: Negligible - no caching in application memory\n\n## API\n\n### cacheBuster(filePath)\n\nReturns a path with version query parameter appended.\n\n**Parameters:**\n- `filePath` (string) - Path relative to `public` folder, starting with `/`\n\n**Returns:**\n- (string) - Path with version parameter (e.g., `/css/style.css?v=1702324004815`)\n\n**Example:**\n```javascript\ncacheBuster('/css/style.css')\n// Returns: '/css/style.css?v=1702324004815'\n```\n\n## Contributing\n\nContributions are welcome! If you have suggestions for improvements or find any issues, please share them on the Wappler Community Forum.\n\n## License\n\nMIT License - Free to use in personal and commercial projects. See [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Ben Pleysier**\n\n## Issues and Support\n\nFor bug reports, feature requests, or assistance, please use the [Wappler Community Forum](https://community.wappler.io).\n\n## Changelog\n\n### 1.0.0 (2025-12-13)\n- Initial release\n- Basic cacheBuster functionality\n- Support for all static assets\n- Error handling and fallbacks\n- Comprehensive documentation\n\n---\n\nMade with ❤️ for the Wappler Community\n","readmeFilename":"README.md","_rev":"1-e6327c02fb9433e73808cf54dff89fad"}