@onedarnleyroad/vite-plugin-svg-sprite 2.0.0-beta.8 → 2.1.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
 
@@ -109,28 +112,32 @@ With Craft CMS + [nystudio107/craft-vite](https://nystudio107.com/docs/vite/):
 
 #### A reusable, accessible macro
 
-Rather than hand-writing the `<svg><use>` wrapper each time, wrap it in a Twig macro. Pass `folder:` for a subfolder sprite — it maps to the `sprite-{folder}.svg` manifest key for you, so templates keep the folder mental model. Icons default to decorative (`aria-hidden="true"`), and switch to a labelled `role="img"` when the icon carries meaning on its own:
+Rather than hand-writing the `<svg><use>` wrapper each time, wrap it in a Twig macro. The two things you set most often — the icon **name** and its **classes** — are positional; the rest (subfolder, accessible label, extra attributes) goes in an `options` hash. Icons default to decorative (`aria-hidden="true"`), and switch to a labelled `role="img"` when the icon carries meaning on its own:
 
 ```twig
-{% macro icon(name, folder = null, label = null, prefix = 'sprite', class = 'icon', extra = {}) %}
-  {% set key  = folder ? "#{prefix}-#{folder}.svg" : "#{prefix}.svg" %}
-  {% set a11y = label
+{% macro icon(name, classList = '', options = {}) %}
+  {% set folder = options.folder ?? null %}
+  {% set label  = options.label ?? null %}
+  {% set file   = folder ? "sprite-#{folder}.svg" : 'sprite.svg' %}
+  {% set a11y   = label
     ? { role: 'img', 'aria-label': label }
     : { 'aria-hidden': 'true', focusable: 'false' } %}
-  <svg{{ attr({ class: class }|merge(a11y)|merge(extra)) }}>
-    <use href="{{ craft.vite.entry(key) }}#svg-{{ name }}"></use>
+  <svg{{ attr({ class: classList }|merge(a11y)|merge(options.attrs ?? {})) }}>
+    <use href="{{ craft.vite.entry(file) }}#svg-{{ name }}"></use>
   </svg>
 {% endmacro %}
 ```
 
 ```twig
-{{ icon('arrow') }}                                   {# root sprite → entry('sprite.svg') #}
-{{ icon('sun', folder: 'light') }}                    {# subfolder → entry('sprite-light.svg') #}
-{{ icon('search', label: 'Search') }}                 {# meaningful → role="img" + aria-label #}
-<button aria-label="Close">{{ icon('x') }}</button>   {# icon-only control: label the button #}
+{{ icon('arrow', 'icon') }}                                  {# root sprite → entry('sprite.svg') #}
+{{ icon('sun', 'icon', { folder: 'light' }) }}               {# subfolder → entry('sprite-light.svg') #}
+{{ icon('search', 'icon', { label: 'Search' }) }}            {# meaningful → role="img" + aria-label #}
+<button aria-label="Close">{{ icon('x', 'icon') }}</button>  {# icon-only control: label the button #}
 ```
 
-Reach for `aria-hidden="true"` only when the icon is decorative — i.e. sitting next to visible text. A standalone, meaning-bearing icon needs an accessible name (via `label`, or on the enclosing control such as a button), or it's invisible to assistive tech. (`attr()` is Craft's built-in attribute renderer.)
+Reach for `aria-hidden="true"` only when the icon is decorative — i.e. sitting next to visible text. A standalone, meaning-bearing icon needs an accessible name (via `options.label`, or on the enclosing control such as a button), or it's invisible to assistive tech. (`'icon'` is a CSS class you define to size the `<svg>` — sprite symbols have no intrinsic dimensions; the walkthrough below covers sizing and colour. `attr()` is Craft's built-in attribute renderer.)
+
+> **Full Craft CMS walkthrough:** [SVG icon sprites in Craft CMS with Vite](https://github.com/onedarnleyroad/craftcms/wiki/SVG-icon-sprites-in-Craft-CMS-with-Vite) — end-to-end setup, the macro, sizing & colour gotchas, and sprites vs. inlining.
 
 ## Development workflow
 
@@ -144,7 +151,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 +174,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), or the full [Craft + Vite walkthrough](https://github.com/onedarnleyroad/craftcms/wiki/SVG-icon-sprites-in-Craft-CMS-with-Vite).
+
+**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.1.0",
   "description": "Vite plugin that builds an SVG sprite sheet from a directory of SVG files",
   "type": "module",
   "exports": {
@@ -15,14 +15,25 @@
     "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"
   },
   "peerDependencies": {
-    "vite": ">=4.0.0"
+    "vite": ">=3.0.0"
   }
 }

package/src/index.js

@@ -142,11 +142,15 @@ export default function svgSpritePlugin(options = {}) {
         writeBundle(outputOptions) {
             if (!viteConfig?.build?.manifest) return
 
-            const manifestName = typeof viteConfig.build.manifest === 'string'
-                ? viteConfig.build.manifest
-                : '.vite/manifest.json'
-            const manifestPath = resolve(outputOptions.dir, manifestName)
-            if (!existsSync(manifestPath)) return
+            // Vite 5+ writes the default manifest to .vite/manifest.json; Vite 3/4 write
+            // manifest.json at the outDir root. Try both when no custom path is configured.
+            const manifestNames = typeof viteConfig.build.manifest === 'string'
+                ? [viteConfig.build.manifest]
+                : ['.vite/manifest.json', 'manifest.json']
+            const manifestPath = manifestNames
+                .map(name => resolve(outputOptions.dir, name))
+                .find(path => existsSync(path))
+            if (!manifestPath) return
 
             const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'))