{"id":22897308,"url":"https://github.com/center-key/rev-web-assets","last_synced_at":"2025-12-24T03:08:45.829Z","repository":{"id":60442055,"uuid":"542560066","full_name":"center-key/rev-web-assets","owner":"center-key","description":"🔢 Revision web asset filenames with cache busting content hash fingerprints (CLI for package.json scripts)","archived":false,"fork":false,"pushed_at":"2025-04-20T06:30:12.000Z","size":839,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T22:07:40.590Z","etag":null,"topics":["assets","cache","cdn","fingerprint","hash","html","revision","website"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/center-key.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-09-28T11:39:43.000Z","updated_at":"2025-04-20T06:30:15.000Z","dependencies_parsed_at":"2023-11-10T12:47:16.847Z","dependency_job_id":"5dd8680b-4323-4599-bfcf-13f7987bf507","html_url":"https://github.com/center-key/rev-web-assets","commit_stats":{"total_commits":32,"total_committers":1,"mean_commits":32.0,"dds":0.0,"last_synced_commit":"cf74b2d4a856c1619e46721efb7bec766a8eb75c"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/center-key%2Frev-web-assets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/center-key%2Frev-web-assets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/center-key%2Frev-web-assets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/center-key%2Frev-web-assets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/center-key","download_url":"https://codeload.github.com/center-key/rev-web-assets/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252961837,"owners_count":21832196,"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":["assets","cache","cdn","fingerprint","hash","html","revision","website"],"created_at":"2024-12-14T00:16:33.551Z","updated_at":"2025-12-24T03:08:45.809Z","avatar_url":"https://github.com/center-key.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rev-web-assets\n\u003cimg src=https://centerkey.com/graphics/center-key-logo.svg align=right width=200 alt=logo\u003e\n\n_Revision web asset filenames with cache busting content hash fingerprints_\n\n[![License:MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/center-key/rev-web-assets/blob/main/LICENSE.txt)\n[![npm](https://img.shields.io/npm/v/rev-web-assets.svg)](https://www.npmjs.com/package/rev-web-assets)\n[![Build](https://github.com/center-key/rev-web-assets/actions/workflows/run-spec-on-push.yaml/badge.svg)](https://github.com/center-key/rev-web-assets/actions/workflows/run-spec-on-push.yaml)\n\n**rev-web-assets** updates the asset filenames of a website to contain a eight-digit hex hash.\u0026nbsp;\nThe command's console output includes a timestamp and formatting helpful in build systems.\n\n\u003cimg src=https://raw.githubusercontent.com/center-key/rev-web-assets/main/screenshot.png\nwidth=800 alt=screenshot\u003e\n\n## A) Setup\nInstall package for node:\n```shell\n$ npm install --save-dev rev-web-assets\n```\n\n## B) Usage\n### 1. Synopsis\n```\nrev-web-assets [SOURCE] [TARGET]\n```\nParameters:\n* The **first** parameter is the *source* folder.\n* The **second** parameter is the *target* folder.\n\n### 2. npm package.json scripts\nRun `rev-web-assets` from the `\"scripts\"` section of your **package.json** file.\n\nExample **package.json** scripts:\n```json\n   \"scripts\": {\n      \"revision\": \"rev-web-assets build/dev/web-app build/prod/web-app\"\n   },\n```\n\n### 3. Command-line npx\nExample terminal commands:\n```shell\n$ npm install --save-dev rev-web-assets\n$ npx rev-web-assets build/dev/web-app build/prod/web-app\n```\nYou can also install **rev-web-assets** globally (`--global`) and then run it anywhere directly from the terminal.\n\n### 4. CLI flags\nCommand-line flags:\n| Flag                  | Description                                                            | Value      |\n| --------------------- | ---------------------------------------------------------------------- | ---------- |\n| `--cd`                | Change working directory before starting starting.                     | **string** |\n| `--force`             | Revision (hash) all asset files even if not referenced.                | N/A        |\n| `--hide404s`          | Suppress warning messages about missing asset files.                   | N/A        |\n| `--manifest`          | Output the list of files to: **manifest.json**                         | N/A        |\n| `--meta-content-base` | Make meta URLs, like \"og:image\", absolute.                             | **string** |\n| `--note`              | Place to add a comment only for humans.                                | **string** |\n| `--quiet`             | Suppress informational messages.                                       | N/A        |\n| `--skip`              | Do not revision (hash) asset files with paths containing given string. | **string** |\n| `--summary`           | Only print out the single line summary message.                        | N/A        |\n\n### 5. Examples\n   - `rev-web-assets web/source web/target`\u003cbr\u003e\n   Revisions the files in the **web/source** folder and saves the new files to the **web/target** folder.\n\n   - `rev-web-assets --cd=web source target`\u003cbr\u003e\n   Identical to the previous example.\n\n   - `rev-web-assets source target --quiet`\u003cbr\u003e\n   Displays no output.\n\n   - `rev-web-assets source target --summary`\u003cbr\u003e\n   Displays the summary informaion but not informaion about individual filenames.\n\n   - `rev-web-assets source 'target/Web Files' --summary`\u003cbr\u003e\n   Save the target files to a folder that has a space in its name.\n\n   - `rev-web-assets source target --meta-content-base=https://example.net`\u003cbr\u003e\n   Prepends the base to `\u003cmeta\u003e` URLs.\n\n\u003e [!NOTE]\n\u003e _Single quotes in commands are normalized so they work cross-platform and avoid the\nerrors often encountered on Microsoft Windows._\n\nURLs in `\u003cmeta\u003e` tag `content` attributes generally need to be absolute URLs.\u0026nbsp;\nSetting the `--meta-content-base` flag to `https://example.net` will transform the line of HTML\nfrom:\n```html\n\u003cmeta property=og:image content=\"logo.png\"\u003e\n```\ninto something like:\n```html\n\u003cmeta property=og:image content=\"https://example.net/logo.ad41b20.png\"\u003e\n```\n\n### 6. Manifest\nThe `--manifest` flag produces a JSON file containing an array objects with details about each file:\n```typescript\nexport type ManifestDetail = {\n   origin:          string,          //source path of asset file\n   filename:        string,          //source filename of asset file\n   canonical:       string,          //normalized path used to lookup asset in manifest\n   canonicalFolder: string,          //directory of the normalized path of the asset file\n   isHtml:          boolean,         //asset file is HTML\n   isCss:           boolean,         //asset file is CSS\n   bytes:           number | null,   //asset file size\n   hash:            string | null,   //eight-digit cache busting hex humber that changes if the asset changes\n   hashedFilename:  string | null,   //filename of the asset with hash inserted before the file extension\n   destFolder:      string,          //directory of the target asset\n   destPath:        string | null,   //folder and filename of the target asset\n   usedIn:          string[] | null, //files that references the asset\n   references:      number | null,   //number of times the asset is referenced\n   skipped:         boolean,         //asset file is configured to not be hashed\n   };\n```\nExample:\n```json\n   {\n      \"origin\": \"src/website/graphics/logo.png\",\n      \"filename\": \"logo.png\",\n      \"canonicalFolder\": \"graphics\",\n      \"canonical\": \"graphics/logo.png\",\n      \"bytes\": 7203,\n      \"isHtml\": false,\n      \"isCss\": false,\n      \"hash\": \"ad42b203\",\n      \"hashedFilename\": \"logo.ad42b203.png\",\n      \"destFolder\": \"target/website/graphics\",\n      \"destPath\": \"target/website/graphics/logo.ad42b203.png\",\n      \"usedIn\": [\n         \"index.html\",\n         \"products/index.html\",\n         \"style.css\",\n      ],\n      \"references\": 7\n   },\n```\n\n## C) Application Code\nEven though **rev-web-assets** is primarily intended for build scripts, the package can be used programmatically in ESM and TypeScript projects.\n\nExample:\n``` typescript\nimport { revWebAssets } from 'rev-web-assets';\n\nconst options = { saveManifest: true };\nconst results = revWebAssets.revision('source', 'target', options);\nconsole.info('Number of web files processed:', results.count);\n```\n\nSee the **TypeScript Declarations** at the top of [rev-web-assets.ts](src/rev-web-assets.ts) for documentation.\n\n\u003cbr\u003e\n\n---\n**CLI Build Tools for package.json**\n   - 🎋 [add-dist-header](https://github.com/center-key/add-dist-header):\u0026nbsp; _Prepend a one-line banner comment (with license notice) to distribution files_\n   - 📄 [copy-file-util](https://github.com/center-key/copy-file-util):\u0026nbsp; _Copy or rename a file with optional package version number_\n   - 📂 [copy-folder-util](https://github.com/center-key/copy-folder-util):\u0026nbsp; _Recursively copy files from one folder to another folder_\n   - 🪺 [recursive-exec](https://github.com/center-key/recursive-exec):\u0026nbsp; _Run a command on each file in a folder and its subfolders_\n   - 🔍 [replacer-util](https://github.com/center-key/replacer-util):\u0026nbsp; _Find and replace strings or template outputs in text files_\n   - 🔢 [rev-web-assets](https://github.com/center-key/rev-web-assets):\u0026nbsp; _Revision web asset filenames with cache busting content hash fingerprints_\n   - 🚆 [run-scripts-util](https://github.com/center-key/run-scripts-util):\u0026nbsp; _Organize npm package.json scripts into groups of easy to manage commands_\n   - 🚦 [w3c-html-validator](https://github.com/center-key/w3c-html-validator):\u0026nbsp; _Check the markup validity of HTML files using the W3C validator_\n\nFeel free to submit questions at:\u003cbr\u003e\n[github.com/center-key/rev-web-assets/issues](https://github.com/center-key/rev-web-assets/issues)\n\n[MIT License](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcenter-key%2Frev-web-assets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcenter-key%2Frev-web-assets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcenter-key%2Frev-web-assets/lists"}