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

package/README.md

@@ -1,14 +1,17 @@
 # @onedarnleyroad/vite-plugin-svg-sprite
 
-A Vite plugin that builds an SVG sprite sheet from a directory of SVG files.
+A Vite plugin that builds SVG sprite sheets from a directory of SVG files — with content-hashed filenames and full Vite manifest integration.
 
 ## Features
 
 - Combines individual SVGs into a single `<svg>` sprite with `<symbol>` elements
+- **Content-hashed output** (e.g. `sprite-DAskUDYW.svg`) so browsers never serve stale sprites
+- **Vite manifest integration** — works out of the box with [nystudio107's Craft Vite plugin](https://nystudio107.com/docs/vite/) and any other manifest consumer
+- **Multiple sprites from subfolders** — organise icons into `light/`, `dark/`, etc. and get one sprite per folder
 - Namespaces internal IDs to prevent conflicts across icons
 - Preserves existing `<title>` elements, or falls back to the filename
 - Strips comments and empty `<defs>` blocks
-- Rebuilds automatically in watch mode (HMR-aware)
+- Dev server serves sprites from memory with full-reload on change
 
 ## Installation
 
@@ -24,10 +27,12 @@ import { defineConfig } from 'vite'
 import svgSprite from '@onedarnleyroad/vite-plugin-svg-sprite'
 
 export default defineConfig({
+  build: {
+    manifest: true,
+  },
   plugins: [
     svgSprite({
       inputDir: 'src/icons',
-      outputFile: 'web/dist/sprite.svg',
     }),
   ],
 })
@@ -35,16 +40,36 @@ export default defineConfig({
 
 ### Options
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `inputDir` | `string` | Directory containing the source `.svg` files |
-| `outputFile` | `string` | Path for the generated sprite sheet |
+| Option      | Type     | Default    | Description                                                                 |
+|-------------|----------|------------|-----------------------------------------------------------------------------|
+| `inputDir`  | `string` | _required_ | Directory containing the source `.svg` files.                               |
+| `outputDir` | `string` | `'assets'` | Output directory, relative to Vite's `build.outDir`.                         |
+| `prefix`    | `string` | `'sprite'` | Filename prefix. The dash between prefix and folder name is always added. |
 
-Both paths are resolved relative to the project root (where `vite.config.js` lives).
+All paths are resolved relative to the project root.
 
-## Output
+## Subfolders
 
-Each SVG becomes a `<symbol>` with an `id` prefixed with `svg-`. For example, `arrow.svg` becomes:
+Organise icons into subfolders to produce one sprite per folder. Loose `.svg` files at the root of `inputDir` go into the default sprite.
+
+```
+src/icons/
+├── arrow.svg      ─┐
+├── close.svg       ├─→ sprite.svg         → dist/assets/sprite-{HASH}.svg
+├── menu.svg       ─┘
+├── light/
+│   ├── sun.svg    ─┐
+│   └── star.svg   ─┴─→ sprite-light.svg   → dist/assets/sprite-light-{HASH}.svg
+└── dark/
+    ├── moon.svg   ─┐
+    └── cloud.svg  ─┴─→ sprite-dark.svg    → dist/assets/sprite-dark-{HASH}.svg
+```
+
+Only the first level of subfolders is scanned. Empty subfolders are skipped.
+
+## Output symbol IDs
+
+Each SVG becomes a `<symbol>` with `id="svg-{filename}"`. For example, `arrow.svg` becomes:
 
 ```html
 <symbol id="svg-arrow" viewBox="0 0 24 24">
@@ -53,14 +78,58 @@ Each SVG becomes a `<symbol>` with an `id` prefixed with `svg-`. For example, `a
 </symbol>
 ```
 
-Use it in your HTML with `<use>`:
+## Using the sprite
 
-```html
+### With Vite manifest (recommended)
+
+With `build.manifest: true` enabled, each sprite is registered in `manifest.json` keyed by its `inputDir`-relative path:
+
+```json
+{
+  "src/icons/sprite.svg":       { "file": "assets/sprite-DAskUDYW.svg",       "src": "src/icons/sprite.svg",       "isEntry": false },
+  "src/icons/sprite-light.svg": { "file": "assets/sprite-light-xV7q1sYy.svg", "src": "src/icons/sprite-light.svg", "isEntry": false }
+}
+```
+
+With Craft CMS + [nystudio107/craft-vite](https://nystudio107.com/docs/vite/), use `craft.vite.asset()` — **not `entry()`**. The `asset()` helper is dev-server-aware; `entry()` always reads the manifest, so in dev it would serve stale built files:
+
+```twig
 <svg aria-hidden="true">
-  <use href="/dist/sprite.svg#svg-arrow" />
+  <use href="{{ craft.vite.asset('src/icons/sprite.svg') }}#svg-arrow"></use>
+</svg>
+
+<svg aria-hidden="true">
+  <use href="{{ craft.vite.asset('src/icons/sprite-light.svg') }}#svg-sun"></use>
 </svg>
 ```
 
+In dev, `asset()` returns the Vite dev-server URL (e.g. `https://…:3000/src/icons/sprite.svg`), which the plugin's in-memory middleware serves. In production it returns the hashed URL from the manifest.
+
+### 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.
+
+## Migrating from v1
+
+v2 is a breaking change. The API moved from "write a single file to an exact path" to "emit hashed assets that Vite owns".
+
+```js
+// v1
+svgSprite({
+  inputDir: 'src/icons',
+  outputFile: 'web/dist/sprite.svg',
+})
+
+// v2
+svgSprite({
+  inputDir: 'src/icons',
+  // outputDir defaults to 'assets' (inside Vite's build.outDir)
+  // prefix defaults to 'sprite'
+})
+```
+
+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.
+
 ## License
 
 MIT © [One Darnley Road](https://onedarnleyroad.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onedarnleyroad/vite-plugin-svg-sprite",
-  "version": "1.0.0",
+  "version": "2.0.0-beta.1",
   "description": "Vite plugin that builds an SVG sprite sheet from a directory of SVG files",
   "type": "module",
   "exports": {

package/src/index.js

@@ -1,59 +1,162 @@
-import { readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
-import { resolve, basename, extname, dirname } from 'path'
-
-export default function svgSpritePlugin({ inputDir, outputFile }) {
-    const input = resolve(inputDir)
-    const output = resolve(outputFile)
-
-    function build() {
-        const symbols = readdirSync(input)
-            .filter(f => f.endsWith('.svg'))
-            .sort()
-            .map(file => {
-                const name = basename(file, extname(file))
-                const svg = readFileSync(resolve(input, file), 'utf-8')
-
-                // Preserve existing <title> if present, otherwise use filename
-                const existingTitle = svg.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim()
-                const title = existingTitle ?? `${name} icon`
-
-                // Strip comments, existing <title> tags, and empty <defs> blocks
-                const cleaned = svg
-                    .replace(/<!--[\s\S]*?-->/g, '')
-                    .replace(/<title[^>]*>[\s\S]*?<\/title>/gi, '')
-                    .replace(/<defs[^>]*>\s*<\/defs>/gi, '')
-
-                // Namespace internal IDs to avoid conflicts when sprites are merged
-                const namespaced = cleaned
-                    .replace(/\bid="([^"]+)"/g, `id="${name}-$1"`)
-                    .replace(/\burl\(#([^)]+)\)/g, `url(#${name}-$1)`)
-                    .replace(/\bhref="#([^"]+)"/g, `href="#${name}-$1"`)
-                    .replace(/\bxlink:href="#([^"]+)"/g, `xlink:href="#${name}-$1"`)
-
-                const viewBox = namespaced.match(/viewBox="([^"]+)"/)?.[1] ?? '0 0 24 24'
-
-                const inner = namespaced
-                    .replace(/<svg[^>]*>/i, '')
-                    .replace(/<\/svg>/i, '')
-                    .replace(/\s*\n\s*/g, ' ')
-                    .replace(/>\s+</g, '><')
-                    .trim()
-
-                return `<symbol id="svg-${name}" viewBox="${viewBox}"><title>${title}</title>${inner}</symbol>`
-            })
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'fs'
+import { resolve, basename, extname, join } from 'path'
+import { createHash } from 'crypto'
+
+function hashContent(content) {
+    return createHash('sha256').update(content).digest('base64url').slice(0, 8)
+}
+
+function buildSymbol(svg, name) {
+    const existingTitle = svg.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim()
+    const title = existingTitle ?? `${name} icon`
+
+    const cleaned = svg
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<title[^>]*>[\s\S]*?<\/title>/gi, '')
+        .replace(/<defs[^>]*>\s*<\/defs>/gi, '')
+
+    const namespaced = cleaned
+        .replace(/\bid="([^"]+)"/g, `id="${name}-$1"`)
+        .replace(/\burl\(#([^)]+)\)/g, `url(#${name}-$1)`)
+        .replace(/\bhref="#([^"]+)"/g, `href="#${name}-$1"`)
+        .replace(/\bxlink:href="#([^"]+)"/g, `xlink:href="#${name}-$1"`)
+
+    const viewBox = namespaced.match(/viewBox="([^"]+)"/)?.[1] ?? '0 0 24 24'
+
+    const inner = namespaced
+        .replace(/<svg[^>]*>/i, '')
+        .replace(/<\/svg>/i, '')
+        .replace(/\s*\n\s*/g, ' ')
+        .replace(/>\s+</g, '><')
+        .trim()
+
+    return `<symbol id="svg-${name}" viewBox="${viewBox}"><title>${title}</title>${inner}</symbol>`
+}
+
+function buildSpriteSvg(dir, files) {
+    const symbols = files.sort().map(file => {
+        const name = basename(file, extname(file))
+        const svg = readFileSync(join(dir, file), 'utf-8')
+        return buildSymbol(svg, name)
+    })
+    return `<svg xmlns="http://www.w3.org/2000/svg">\n${symbols.join('\n')}\n</svg>`
+}
+
+function collectSpriteGroups(inputDir, prefix) {
+    const absInput = resolve(inputDir)
+    const entries = readdirSync(absInput, { withFileTypes: true })
+
+    const groups = []
+
+    const rootFiles = entries
+        .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.svg'))
+        .map(e => e.name)
+    if (rootFiles.length > 0) {
+        groups.push({ logicalName: `${prefix}.svg`, dir: absInput, files: rootFiles })
+    }
+
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+        const subDir = join(absInput, entry.name)
+        const subFiles = readdirSync(subDir, { withFileTypes: true })
+            .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.svg'))
+            .map(e => e.name)
+        if (subFiles.length === 0) continue
+        groups.push({ logicalName: `${prefix}-${entry.name}.svg`, dir: subDir, files: subFiles })
+    }
+
+    return groups
+}
 
-        mkdirSync(dirname(output), { recursive: true })
-        writeFileSync(output, `<svg xmlns="http://www.w3.org/2000/svg">\n${symbols.join('\n')}\n</svg>`)
+export default function svgSpritePlugin(options = {}) {
+    if ('outputFile' in options) {
+        throw new Error(
+            '[vite-plugin-svg-sprite] `outputFile` was removed in v2. Use `outputDir` (relative to Vite\'s build.outDir) and `prefix` instead. See README for migration.'
+        )
     }
 
+    const { inputDir, outputDir = 'assets', prefix = 'sprite' } = options
+
+    if (!inputDir) {
+        throw new Error('[vite-plugin-svg-sprite] `inputDir` is required.')
+    }
+
+    const absInputDir = resolve(inputDir)
+    const emitted = []
+    let viteConfig
+
     return {
         name: 'svg-sprite',
-        buildStart() {
-            if (this.meta.watchMode) build()
+
+        configResolved(config) {
+            viteConfig = config
+        },
+
+        generateBundle() {
+            emitted.length = 0
+            for (const group of collectSpriteGroups(inputDir, prefix)) {
+                const source = buildSpriteSvg(group.dir, group.files)
+                const base = group.logicalName.replace(/\.svg$/, '')
+                const hashedFileName = join(outputDir, `${base}-${hashContent(source)}.svg`)
+                const key = join(inputDir, group.logicalName)
+                this.emitFile({ type: 'asset', fileName: hashedFileName, source })
+                emitted.push({ key, fileName: hashedFileName })
+            }
         },
-        writeBundle: build,
-        handleHotUpdate({ file }) {
-            if (file.startsWith(input)) build()
+
+        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
+
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+
+            for (const { key, fileName } of emitted) {
+                manifest[key] = {
+                    file: fileName,
+                    src: key,
+                    isEntry: false,
+                }
+            }
+
+            writeFileSync(manifestPath, JSON.stringify(manifest, null, 2))
+        },
+
+        configureServer(server) {
+            const sprites = new Map()
+
+            const rebuild = () => {
+                sprites.clear()
+                for (const group of collectSpriteGroups(inputDir, prefix)) {
+                    const key = join(inputDir, group.logicalName)
+                    sprites.set(key, buildSpriteSvg(group.dir, group.files))
+                }
+            }
+            rebuild()
+
+            server.middlewares.use((req, res, next) => {
+                const path = req.url?.split('?')[0]?.replace(/^\//, '')
+                if (!path) return next()
+                const match = sprites.get(path)
+                if (!match) return next()
+                res.setHeader('Content-Type', 'image/svg+xml')
+                res.setHeader('Cache-Control', 'no-cache')
+                res.end(match)
+            })
+
+            server.watcher.add(absInputDir)
+            const onChange = file => {
+                if (!file.startsWith(absInputDir)) return
+                rebuild()
+                server.ws.send({ type: 'full-reload' })
+            }
+            server.watcher.on('change', onChange)
+            server.watcher.on('add', onChange)
+            server.watcher.on('unlink', onChange)
         },
     }
 }