@onedarnleyroad/vite-plugin-svg-sprite 2.0.0-beta.8 → 2.0.0

package/README.md

@@ -1,6 +1,9 @@
 # @onedarnleyroad/vite-plugin-svg-sprite
 
-A Vite plugin that builds SVG sprite sheets from a directory of SVG files — with content-hashed filenames and full Vite manifest integration.
+[![npm](https://img.shields.io/npm/v/@onedarnleyroad/vite-plugin-svg-sprite)](https://www.npmjs.com/package/@onedarnleyroad/vite-plugin-svg-sprite)
+[![license](https://img.shields.io/npm/l/@onedarnleyroad/vite-plugin-svg-sprite)](./LICENSE)
+
+A Vite plugin that builds **content-hashed SVG sprite sheets** at build time and registers them in **Vite's manifest** — built for server-rendered apps like **Craft CMS** (via [nystudio107's Vite plugin](https://nystudio107.com/docs/vite/)), and works with any manifest consumer. Organise icons into folders to get one sprite per folder, and reference them from templates with no JavaScript.
 
 ## Features
 
@@ -144,7 +147,7 @@ Every edit under `inputDir` triggers a rebuild (a second or two), updates `manif
 
 ### Without manifest
 
-You can reference the sprite directly if you don't use a manifest — but the filename will be hashed, so you'd need to read the hash yourself or disable hashing manually. The manifest-based flow is strongly recommended.
+You can reference a sprite file directly without a manifest, but its filename is always content-hashed — there's no option to turn hashing off — so you'd have to discover the emitted name yourself (e.g. by globbing `assets/sprite-*.svg`). The manifest-based flow is strongly recommended.
 
 ## Migrating from v1
 
@@ -167,6 +170,32 @@ svgSprite({
 
 Passing `outputFile` in v2 throws an error. Update your templates to read the sprite URL from Vite's manifest instead of hard-coding the path.
 
+## How this differs from other SVG sprite plugins
+
+Several Vite plugins generate SVG sprites; they mostly split by *how the sprite reaches the page*:
+
+- **Runtime injection** (e.g. [`vite-plugin-svg-icons`](https://github.com/vbenjs/vite-plugin-svg-icons)) injects the sprite into the DOM via a virtual import. Great for SPAs; needs JavaScript to run.
+- **Import-based** plugins expose each icon as a JS module or framework component. Great when your icons live in JS/JSX.
+- **This plugin is build-time and manifest-driven.** It emits content-hashed `.svg` files and registers them in Vite's manifest under stable logical keys, so a **server-rendered** template (Craft/Twig, Laravel/Blade, etc.) resolves the hashed URL with no JavaScript — e.g. `craft.vite.entry('sprite.svg')`. It also emits one sprite per subfolder.
+
+If you want runtime/HMR injection or a virtual import, one of the others will suit you better. If you render HTML on the server and resolve assets through a Vite manifest, this is built for that.
+
+## FAQ
+
+**Does it work with Craft CMS?** Yes — it's the primary target. With [nystudio107's Craft Vite plugin](https://nystudio107.com/docs/vite/), reference a sprite with `craft.vite.entry('sprite.svg')` (see [Using the sprite](#using-the-sprite)).
+
+**How do I reference an icon in a Twig template?** Use `<use href="{{ craft.vite.entry('sprite.svg') }}#svg-{name}">`, or the reusable [`icon()` macro](#a-reusable-accessible-macro).
+
+**Can I have more than one sprite?** Yes — each subfolder of `inputDir` becomes its own sprite, keyed `sprite-{folder}.svg`. See [Subfolders](#subfolders).
+
+**Can two icons share a filename across folders?** Yes. `arrow.svg` and `brand/arrow.svg` both become `<symbol id="svg-arrow">`, but in *separate* sprite files — and you reference each by its own sprite URL (`entry('sprite.svg')#svg-arrow` vs `entry('sprite-brand.svg')#svg-arrow`), so the file URL disambiguates them and they render fine on the same page. The ids only repeat *across* files, never within one; the only thing to avoid is inlining multiple sprites into a single document and referencing by bare `#svg-arrow`.
+
+**Does it run during `vite dev` / support HMR?** No — it's build-only. Run `vite build --watch` alongside your dev server for a live-ish loop.
+
+**Does it optimise SVGs?** No — it does light cleanup (strips the XML prolog / comments / empty `<defs>`, collapses whitespace, namespaces IDs), but it doesn't touch path data, so bring source SVGs that are already production-ready. Each icon needs a `viewBox` — the plugin strips `width`/`height` and scales from it.
+
+**Why are the manifest keys `sprite.svg` and `sprite-light.svg`, not paths?** Because nystudio107's `entry()` resolves keys with a substring match, and a path-style `light/sprite.svg` would collide with the root `sprite.svg`. Basename keys avoid that.
+
 ## License
 
 MIT © [One Darnley Road](https://onedarnleyroad.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onedarnleyroad/vite-plugin-svg-sprite",
-  "version": "2.0.0-beta.8",
+  "version": "2.0.0",
   "description": "Vite plugin that builds an SVG sprite sheet from a directory of SVG files",
   "type": "module",
   "exports": {
@@ -15,10 +15,21 @@
     "vite-plugin",
     "svg",
     "sprite",
-    "svg-sprite"
+    "svg-sprite",
+    "svg-symbols",
+    "icons",
+    "manifest",
+    "craft-cms",
+    "nystudio107"
   ],
   "author": "One Darnley Road <hello@onedarnleyroad.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onedarnleyroad/vite-plugin-svg-sprite.git"
+  },
+  "homepage": "https://github.com/onedarnleyroad/vite-plugin-svg-sprite#readme",
+  "bugs": "https://github.com/onedarnleyroad/vite-plugin-svg-sprite/issues",
   "publishConfig": {
     "access": "public"
   },