{"id":28175592,"url":"https://github.com/4awpawz/buster","last_synced_at":"2025-05-15T23:15:52.402Z","repository":{"id":32458801,"uuid":"129569277","full_name":"4awpawz/buster","owner":"4awpawz","description":"a cache buster called Buster","archived":false,"fork":false,"pushed_at":"2024-11-29T13:38:06.000Z","size":2408,"stargazers_count":14,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-11T03:36:57.489Z","etag":null,"topics":["browser","buster","cache-busting","cachebuster","cli","fingerprint","hash","manifest","web-developer","web-development","website","workflow"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4awpawz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-15T02:09:18.000Z","updated_at":"2025-01-04T13:15:49.000Z","dependencies_parsed_at":"2024-01-29T00:03:08.168Z","dependency_job_id":"44bfa185-f0a8-43a8-ace6-4628f2c4661a","html_url":"https://github.com/4awpawz/buster","commit_stats":{"total_commits":210,"total_committers":1,"mean_commits":210.0,"dds":0.0,"last_synced_commit":"ce23d136aa84dcaf3345c394b8d3d2e1af17bbd2"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4awpawz%2Fbuster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4awpawz%2Fbuster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4awpawz%2Fbuster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4awpawz%2Fbuster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4awpawz","download_url":"https://codeload.github.com/4awpawz/buster/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436902,"owners_count":22070949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","buster","cache-busting","cachebuster","cli","fingerprint","hash","manifest","web-developer","web-development","website","workflow"],"created_at":"2025-05-15T23:14:53.798Z","updated_at":"2025-05-15T23:15:52.393Z","avatar_url":"https://github.com/4awpawz.png","language":"JavaScript","funding_links":["https://www.buymeacoffee.com/4awpawz"],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"./github/buster.png\" width=\"152\" height=\"181\" alt=\"Bulldog\"\u003e A Cache Buster Called *Buster*\n\nBuster busts your browser cache problems!\n\n## Version\n\nv1.2.1\n\n## Features\n\n* Cache busts your project's files in place.\n\n* Fingerprints (renames) files based on their content using MD5 hash-based cache busting file names.\n\n* Replaces references in files to original file names with their MD5 hash-based file names.\n\n* Optionally outputs a manifest file to buster.manifest.json.\n\n* Simple and intuitive configuration using .buster.json.\n\n* Invokable via the command line and scriptable.\n\n* Easily integrates into your project workflow.\n\n## Installation\n\n### Install Globally\n\nThis is the ideal solution if you want to use Buster as a general utility from the command line.\n\n    $ npm install -g @4awpawz/buster\n\n### Install Locally\n\nThis is the ideal solution if you want to integrate Buster into your project.\n\n    $ npm install --save-dev @4awpawz/buster\n\n## Important\n\n* __Buster Is Destructive__. Buster does not make backups of your files. Buster performs its operations directly on the files that operational directives indicate. See \"A Typical Buster Workflow\" below.\n\n* Versions prior to v1.1.0 generated hashes based solely on the content of the files targeted by its operational directives. This opened up the opportunity for clashes on files that had no content. __To address this issue, beginning with v1.1.0, Buster will generates unique hashes for all files by including the path of the file targeted by operational directives as well as its content__.\n\n## Buster Primer\n\n### Site Relative File Paths And Site Relative URLs\n\nIn the documentation that follows, references are made to __site relative file paths__ and to __site relative URLs__.\n\n1. \"site relative file paths\" pertain strictly to your project's file structure. They are used to declare the __input__ in [operational directives](#operational-directives) when declaring the file paths to assets in your project that you want targeted by Buster for cache busting.\n\n1. \"Site relative URLs\" pertain strictly to your website's runtime environment and are used to reference assets throughout your site (e.g. the _src attribute_ of an img tag, the _href_ attribute of a link tag, the _URL() CSS function_  declared inside of a CSS stylesheet).\n\nThe important thing here is to understand that in order for Buster to perform its cache busting you, the developer, must insure that your site employs site relative URLs when referencing its assets. This is because Buster converts your site relative file paths to site relative URLs which it then uses to search the content of your site's files for site relative URLs that need to be updated to point to the assets it has fingerprinted with unique hashes.\n\n#### A Typical Buster Work Flow\n\nYour development build tool generates your __production ready site__ (as opposed to development) into your project's __release folder__. When configuring Buster to cache bust your site, you would target your project files in the __release folder__ by using __site relative file paths__ in your Buster configuration's [operational directives](#operational-directives). Then from the root of your project you can use the command line to run Buster to cache bust your site in the release folder. You can then run your site from the release folder to insure that it is functioning as expected and once it is determined that it is functioning as expected you can then deploy your site directly from the release folder to its server using a command line utility such as rsync.\n\nIn a typical website project with the following or similar project structure\n\n```\n|- myproject\n|- |- release/\n|- |- |- media/\n|- |- |- |- housecat.jpg\n|- |- |- index.html\n|- |- .buster.json\n```\n\nthe site relative file path used in an operational directive to target housecat.jpg would be release/media/housecat.jpg and the site relative URL used to identify the image file in the browser would be media/housecat.jpg.\n\n## Operational Directives\n\nBuster employs a concept called an *Operational Directive*, abbreviated *od*, which you *declare* in your _.buster.json_ configuration file and which Buster uses to direct the operations it performs on your project's files. Each od is comprised of 2 parts, an [input](#input), and an [operation](#operation).\n\n### Input\n\nA site relative file path to one or more files.\n\nSupports *globs/wildcard* patterns.\n\n\u003e__Important__ Buster assumes that all site relative file paths are relative to `process.cwd()`.\n\n\u003e__Important__ Buster implements its *glob* support using node package __glob__. Please refer to node package [*glob*](https://www.npmjs.com/package/glob) should you need additional information on using globs with Buster.\n\n### Operation\n\nIndicates the *actions* that Buster is to perform on the od's input file(s). It is a number preceded by a colon which separates the number from the input (e.g. \":1\"). The following 3 operations are currently supported:\n\n#### :1\n\nApply this operation only to those files whose own file names are to be fingerprinted for cache busting purposes (e.g. `.jpg, .gif, .map`).\n\nThe format of each unique MD5 hash-based file name will be __[original file's base name].[unique hash].[original file's extension]__ (e.g. `cat.[unique hash].jpg`). Should the original file's base name contain 1 or more _periods_ (e.g. __main.js__.map) the format of the MD5 hash-based file name will, as an example, be __main.[unique hash].js.map__.\n\n#### :2\n\nApply this operation only to those files whose contents are to be searched for site relative URLs that point to assets whose file names have been fingerprinted and therefor need to be updated and whose own file names are not to be fingerprinted for cache busting purposes (e.g. `.html`).\n\n#### :3\n\nApply this operation only to those files whose own file names are to be fingerprinted for cache busting purposes and whose contents are to be searched for site relative URLs that point to assets whose file names have been fingerprinted and therefor need to be updated (e.g. `.css`).\n\n### Hashed File Name Format\n\nThe format of each unique MD5 hash-based file name will be __[original file's base name].[unique hash].[original file's extension]__ (e.g. `cat.[unique hash].jpg`). Should the original file's base name contain 1 or more _periods_ (e.g. __main.js__.map) the format of the MD5 hash-based file name will, as an example, be __main.[unique hash].js.map__.\n\n### Operational Directive Examples\n\n#### Example Operational Directives Using Site Relative File Path:\n\nGiven the following project structure\n\n```\n|- myproject\n|- |- release/\n|- |- |- media/\n|- |- |- |- housecat.jpg\n|- |- |- index.html =\u003e contains img tag with a site relative url for its src i.e. \u003cimg src=\"/media/housecat.jpg\"\u003e\n|- |- .buster.json\n```\n\nand running Buster from the command line in the myproject folder with the following operational directives\n\n```\n`release/media/housecat.jpg:1`\n`release/index.html:2`\n```\n\nwill result in the following:\n\n```\n|- myproject\n|- |- release/\n|- |- |- media/\n|- |- |- |- housecat.[unique hash].jpg\n|- |- |- index.html =\u003e now contains img tag whose src attribute points to hashed img i.e. \u003cimg src=\"/media/housecat.[unique hash].jpg\"\u003e\n|- |- .buster.json\n```\n\n#### Example Operational Directives Using Site Relative File Paths And Globs:\n\nGiven the following project structure\n\n```\n|- myproject\n|- |- release/\n|- |- |- media/\n|- |- |- |- housecat.jpg\n|- |- |- |- purringcat.jpg\n|- |- |- |- bigcats/\n|- |- |- |- |- lion.jpg\n|- |- |- |- |- tiger.jpg\n|- |- |- index.html =\u003e contains img tags with site relative urls for its src e.g. \u003cimg src=\"/media/housecat.jpg\"\u003e, \u003cimg src=\"/media/bigcats/lion.jpg\"\u003e\n|- |- .buster.json\n```\n\nand running Buster with the following directives\n\n```\n`release/media/**/*.jpg:1\n`release/**/*.html:2`\n```\n\nwill result as follows:\n\n```\n|- myproject\n|- |- release/\n|- |- |- media/\n|- |- |- |- housecat.[unique hash].jpg\n|- |- |- |- purringcat.[unique hash].jpg\n|- |- |- |- bigcats/\n|- |- |- |- |- lion.[unique hash].jpg\n|- |- |- |- |- tiger.[unique hash].jpg\n|- |- |- index.html =\u003e now contains img tags whose src attributes point to hashed img i.e. \u003cimg src=\"/media/housecat.[unique hash].jpg\"\u003e, \u003cimg src=\"/media/bigcats/lion.[unique hash].jpg\"\u003e\n|- |- .buster.json\n```\n\n## buster.json Configuration\n\n\u003e__*Important*__ Buster expects *.buster.json* to reside in your project's root folder, alongside package.json.\n\n```json\n{\n    \"options\": {\n        \"manifest\": true,\n        \"verbose\": true,\n        \"ignore\": \"media/original/**/*.jpg,media/original/**/*.gif\"\n    },\n    \"directives\": [\n        \"release/media/**/*.jpg:1\",\n        \"release/./index.html:2\",\n        \"release/css/test.css:3\",\n        \"release/script/test.js:3\"\n    ]\n}\n```\n\n### Options\n\nBuster supports the following configuration options:\n\n### ignore\n\nA _quoted list_ of one or more comma separated _site relative file paths_ to files that are to be ignored, defaults to `\"\"`.\n\nSupports _globs_ and _wildcard_ characters patterns.\n\n### manifest\n\nA _boolean_, `true` to save the manifest to _buster.manifest.json_ in the project's _root folder_, defaults to `false`.\n\n### verbose\n\nA _boolean_, `true` to output verbose logging, defaults to `false`.\n\n## Typical Workflows\n\n### Integrating Buster Into Your Project's Workflow\n\nInstall Buster locally:\n\n```shell\nmyproject \u003e $ npm install -D @4awpawz/buster\n```\n\nThen create a .buster.json configuration file in your project's root folder, alongside package.json:\n\n```json\n{\n    \"directives\": [\n        \"release/media/**/*.jpg:1\",\n        \"release/css/**/*.css.map:1\",\n        \"release/scripts/**/*.js.map:1\",\n        \"release/**/*.html:2\",\n        \"release/css/**/*.css:3\",\n        \"release/scripts/**/*.js:3\"\n    ]\n}\n```\n\nThen add the following to your project's package.json's `scripts` property:\n\n```json\n\"scripts\": {\n    \"bust\": \"buster\"\n}\n```\n\nYou can then run buster from the command line by invoking it as follows:\n\n```shell\nmyproject \u003e npm run bust\n```\n\n### Calling Buster From Within A Script\n\nBuster can be called from within a *script*, allowing it to be used as part of a greater workflow:\n\n```js\nconst buster = require(\"@4awpawz/buster\");\n\nconst paramsConfig = {\n    options: {\n        manifest: true\n    },\n    directives: [\n        \"release/media/**/*.jpg:1\",\n        \"release/css/**/*.css.map:1\",\n        \"release/scripts/**/*.js.map:1\",\n        \"release/**/*.html:2\",\n        \"release/css/**/*.css:3\",\n        \"release/scripts/**/*.js:3\"\n    ]\n}\n\nawait buster(paramsConfig);\n```\n\n## Filing Bugs And Feature Requests\n* https://github.com/4awpawz/buster/issues\n\n## Changelog\n\n### v1.2.1\n\nThis release only encompasses changes to the project's README.md file, specifically for the addition of the solicitation to 'Buy me a coffee'.\n\n### v1.1.1\n\nThis release only encompasses changes to the project's documentation in this README.md file.\n\n### v1.1.0\n\nThis release includes an improved hashing algorithm that generates unique hashes for all files, including those that have no content.\n\n### v1.0.0\n\nThis is the first major release of Buster and incorporates many breaking changes from prior versions. Most notably, prior versions had a \"safe mode\" configuration option that would instruct Buster to cache bust \"in place\", meaning that it would not create backups and would not be able to restore files to their prior state. As it turns out, the vast majority of Buster's users are using \"safe mode\" because it fits their workflow of generating their site into a dedicated folder that can be cache busted and that could easily be repopulated by just regenerating the site. These changes were implemented to refactor Buster to precisely match this typical workflow.\n\n### v0.3.1\n\nThis release addresses fixes for security warnings for packages used internally by Buster only. There are no changes to the code base.\n\n### v0.3.0\n\nThis release addresses one bug and fixes for security warnings for packages used internally by Buster only. Also landing with this release is reduced console output; use the `verbose` config option if needed.\n\nMajor bug fixes:\n\n* Addresses issue [`#14`](https://github.com/4awpawz/buster/issues/14) which could cause Buster to mangle hashed file names. **Please note that beginning with this release, Buster now generates hashed file names as *[hash]-[file name].[file extension]*.  You are strongly advised to upgrade your projects and rebuild them.**\n\n### v0.2.4\n\nThis release addresses fixes for security warnings for packages used internally by Buster only. There are no changes to the code base.\n\n### v0.2.3\n\nMajor bug fixes:\n\n* Addresses issue [`#13`](https://github.com/4awpawz/buster/issues/13) which would cause Buster to crash when reading a configuration file that doesn't exist.\n\n\n* Addresses issue [`#12`](https://github.com/4awpawz/buster/issues/12) which would cause Buster to crash when setting paramsConfig to a default value of `{}` to indicate that it wasn't passed.\n\n### v0.2.2\n\nThis release includes no changes to the code base.\n\n* Addresses issue [`#11`]( https://github.com/4awpawz/buster/issues/11) which seeks to lockdown all project dependencies including descendants using NPM's `shrinkwrap`.\n\n### v0.2.1\n\nMajor and minor bug fixes - includes but not limited to the following:\n\n* Addresses issue [`10`](https://github.com/4awpawz/buster/issues/10) which would cause buster to fail when reading command line configuration data belonging to the application that launched it with paramsConfig.\n\n* Addresses issue [`#9`](https://github.com/4awpawz/buster/issues/9) which would sometimes cause `restore` to fail. This fix totally replaces the one introduced in v0.2.0, and now handles the issue earlier in the restore processing cycle.\n\n### v0.2.0\n\nMajor refactor -  includes but not limited to the following:\n\n* Introduces experimental [\"safe mode\"](#safe-mode) feature, resolves [`#6`](https://github.com/4awpawz/buster/issues/6).\n\n* v0.1.6 breaks handling of backup files bug, fixes [`#5`](https://github.com/4awpawz/buster/issues/5).\n\n* Removes hashed files from the manifest returned by glob during restore.\n\n* Implements new resolution of destination paths.\n\n* Removes the \"file-exists\" package from the project.\n\n* Catching some async exceptions to prevent unresolved promise exceptions.\n\n* Configuration attempts to resolve from paramsConfig (i.e. passed via a script) first.\n\n* Updated README.md\n\n### v0.1.6\n\n* Addresses a bug in command-line processing which would cause Buster to crash when the user enters only *\"bust\"* or *\"restore\"* from the command-line.\n\n* Addresses a bug in od processing which would cause Buster to crash when attempting to create folders that already  exist.\n\n* Addresses a bug in od processing which would cause Buster to crash when attempting to delete files that no longer exist.\n\n## Copyright And License\n\nCopyright \u0026copy; 2018, `Jeffrey Schwartz`. Released under the `MIT license`.\n\n## Community\n\nFor help, discussion about best practices, or any other conversation that would benefit from being searchable:\n\n[Discuss Buster on Github](https://github.com/4awpawz/buster/discussions)\n\nFor casual conversation with others about using Buster:\n\n[Discuss Buster on Twitter and other social media.](https://twitter.com).\n\n## Show Your Appreciation\n\n\u003ca href=\"https://www.buymeacoffee.com/4awpawz\"\u003e\u003cimg src=\"./github/buymeacoffee.png\" alt=\"image\"\u003e\u003c/a\u003e\n\nPlease 👀 watch and leave us a 🌟 star. :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4awpawz%2Fbuster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4awpawz%2Fbuster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4awpawz%2Fbuster/lists"}