@stephansama/vite-iconify-svgmap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+         MIT License
+
+Copyright (c) 2025 Stephan Randle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+<div align="center">
+
+# [`@stephansama`](https://github.com/stephansama) / vite-iconify-svgmap
+
+<!-- BADGE start -->
+
+[![source code](https://img.shields.io/badge/Source-666666?style=flat&logo=github&label=Github&labelColor=211F1F)](https://github.com/stephansama/packages/tree/main/core/vite-iconify-svgmap)
+[![documentation](https://img.shields.io/badge/Documentation-211F1F?style=flat&logo=Wikibooks&labelColor=211F1F)](https://packages.stephansama.info/api/@stephansama/vite-iconify-svgmap)
+[![npm](https://img.shields.io/npm/v/%40stephansama%2Fvite-iconify-svgmap?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F)](https://www.npmx.dev/package/@stephansama/vite-iconify-svgmap)
+[![socket.dev](https://badge.socket.dev/npm/package/@stephansama/vite-iconify-svgmap)](https://socket.dev/npm/package/@stephansama/vite-iconify-svgmap/overview)
+[![jsr](https://jsr.io/badges/@stephansama/vite-iconify-svgmap)](https://jsr.io/@stephansama/vite-iconify-svgmap)
+[![npm downloads](https://img.shields.io/npm/dw/@stephansama/vite-iconify-svgmap?labelColor=211F1F)](https://www.npmx.dev/package/@stephansama/vite-iconify-svgmap)
+
+[![@iconify/types](https://img.shields.io/badge/@iconify/types-2.0.0-026C9C.svg?logo=iconify&logoColor=ffffff&labelColor=026C9C)](https://npmx.dev/package/@iconify/types)
+[![@tanstack/intent](https://img.shields.io/badge/@tanstack/intent-0.0.41-00a6f4.svg?logo=tanstack&logoColor=ffffff&labelColor=00a6f4)](https://npmx.dev/package/@tanstack/intent)
+[![astro](https://img.shields.io/badge/astro-6.3.1-BC52EE.svg?logo=astro&logoColor=ffffff&labelColor=BC52EE)](https://npmx.dev/package/astro)
+[![svelte](https://img.shields.io/badge/svelte-5.51.2-FF3E00.svg?logo=svelte&logoColor=ffffff&labelColor=FF3E00)](https://npmx.dev/package/svelte)
+[![tsdown](https://img.shields.io/badge/tsdown-0.21.10-3178C6.svg?logo=rolldown&logoColor=ffffff&labelColor=3178C6)](https://npmx.dev/package/tsdown)
+[![vite](https://img.shields.io/badge/vite-6.3.5-9135FF.svg?logo=vite&logoColor=ffffff&labelColor=9135FF)](https://npmx.dev/package/vite)
+
+<!-- BADGE end -->
+
+Vite plugin for generating iconify svg sprite maps in memory
+
+</div>
+
+##### Table of contents
+
+<details><summary>Open Table of contents</summary>
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Astro](#astro)
+  - [SvelteKit](#sveltekit)
+  - [Vite](#vite)
+  - [Static imports](#static-imports)
+  - [Icons known while rendering](#icons-known-while-rendering)
+  - [Icon components](#icon-components)
+- [Options](#options)
+- [How it works](#how-it-works)
+
+</details>
+
+## Installation
+
+Install the plugin and at least one `@iconify-json/*` icon pack
+
+```sh
+pnpm install -D @stephansama/vite-iconify-svgmap @iconify-json/logos
+```
+
+Add the virtual module types to your `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@stephansama/vite-iconify-svgmap/client"]
+  }
+}
+```
+
+## Usage
+
+### Astro
+
+The astro integration adds the vite plugin and writes sprites for icons
+registered with `getIcon` once every page has rendered.
+
+```js
+// astro.config.mjs
+import iconifySvgmap from "@stephansama/vite-iconify-svgmap/astro/integration";
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  integrations: [iconifySvgmap()],
+});
+```
+
+### SvelteKit
+
+Add the sveltekit plugins **after** `sveltekit()`:
+
+```js
+// vite.config.js
+import iconifySvgmap from "@stephansama/vite-iconify-svgmap/svelte/integration";
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [sveltekit(), iconifySvgmap()],
+});
+```
+
+SvelteKit prerenders in a worker thread and has no hook after prerendering,
+so this plugin:
+
+- receives `getIcon` calls made inside the prerender worker over an in
+  memory `BroadcastChannel`
+- writes empty placeholder sprites for every installed icon pack when the
+  client build finishes, so the prerender crawler does not fail on
+  `<use href>` links to sprites that do not exist yet
+- writes the real sprites (and removes unused placeholders) after
+  prerendering, before the adapter copies the client output
+
+### Vite
+
+```js
+// vite.config.js
+import iconifySvgmap from "@stephansama/vite-iconify-svgmap";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [iconifySvgmap()],
+});
+```
+
+Static imports need nothing else. If you use `getIcon` in a server rendered
+or prerendered app, call `writeSprites` with your client output directory
+once rendering has finished:
+
+```js
+import { writeSprites } from "@stephansama/vite-iconify-svgmap";
+
+await writeSprites("dist");
+```
+
+### Static imports
+
+Import an icon as `virtual:iconify-svgmap/<pack>/<icon>` to get its sprite
+href. Unknown packs or icons fail the build.
+
+```astro
+---
+import astro from "virtual:iconify-svgmap/logos/astro";
+---
+
+<svg width="24" height="24"><use href={astro}></use></svg>
+```
+
+Only the imported icons end up in a content hashed sprite per pack (for
+example `/_astro/logos.BzUCTX55.svg`).
+
+### Icons known while rendering
+
+When the icon name is only known while rendering (cms data, frontmatter,
+loops), use `getIcon`:
+
+```astro
+---
+import { getIcon } from "virtual:iconify-svgmap";
+
+const href = getIcon(entry.data.iconPack, entry.data.icon);
+---
+
+<svg width="24" height="24"><use href={href}></use></svg>
+```
+
+`getIcon` records the icon in memory and returns
+`/_iconify/<pack>.svg?v=<build>#<icon>`. The sprite is written after all pages
+have rendered.
+
+> \[!NOTE]
+> `getIcon` icons must be rendered during the build, in the same process or
+> one of its worker threads (static astro sites and prerendered sveltekit
+> pages). Icons first requested at runtime by an on demand rendered route, or
+> only by client side code, are not included in the written sprites. During
+> development every icon works, including client rendered ones.
+
+### Icon components
+
+Each framework subpath exports an `Icon` component that wraps `getIcon` in an
+`<svg><use /></svg>`. They follow the same rules as `getIcon`: icons must be
+rendered on the server during the build (for example astro pages or
+server rendered svelte islands) and the sprites written afterwards (the astro
+integration does this).
+
+| Framework | Import                                                                      |
+| --------- | --------------------------------------------------------------------------- |
+| astro     | `import { Icon } from "@stephansama/vite-iconify-svgmap/astro/component";`  |
+| svelte 5  | `import { Icon } from "@stephansama/vite-iconify-svgmap/svelte/component";` |
+
+```astro
+---
+import { Icon } from "@stephansama/vite-iconify-svgmap/astro/component";
+---
+
+<Icon pack="logos" name="github-icon" size={24} title="GitHub" />
+<Icon pack="heroicons" name="heart-solid" class="text-red-500" />
+```
+
+```svelte
+<script>
+  import { Icon } from "@stephansama/vite-iconify-svgmap/svelte/component";
+</script>
+
+<Icon pack="logos" name="svelte-icon" size={24} title="Svelte" />
+```
+
+| Prop    | Default | Description                                                          |
+| ------- | ------- | -------------------------------------------------------------------- |
+| `pack`  |         | iconify pack, e.g. `logos` for `@iconify-json/logos`                 |
+| `name`  |         | icon name inside the pack                                            |
+| `size`  | `"1em"` | width and height                                                     |
+| `title` |         | accessible label; without it the icon gets `aria-hidden="true"`      |
+| ...     |         | any other svg attribute (`class`, `style`, ...) is passed to `<svg>` |
+
+Icons that use `currentColor` follow the css `color` of the component.
+
+## Options
+
+| Option | Default       | Description                                                                            |
+| ------ | ------------- | -------------------------------------------------------------------------------------- |
+| `dir`  | `"_iconify"`  | folder, relative to the output directory, for sprites of icons registered by `getIcon` |
+| `root` | vite's `root` | directory used to resolve `@iconify-json/*` packages                                   |
+
+## How it works
+
+Nothing is written to the file system until the final output:
+
+- icon packs are loaded lazily, only when an icon from the pack is requested
+- during development sprites are generated in memory and served by the dev
+  server
+- static imports are emitted as vite assets, so they are hashed and moved to
+  the output like any other asset
+- `getIcon` usage is kept in an in memory registry and flushed once by
+  `writeSprites`

package/client.d.ts

@@ -0,0 +1,16 @@
+declare module "virtual:iconify-svgmap" {
+	/**
+	 * Register an icon while rendering and return its sprite href, e.g.
+	 * `/_iconify/<pack>.svg?v=<build>#<name>`
+	 */
+	export function getIcon(pack: string, name: string): string;
+}
+
+declare module "virtual:iconify-svgmap/*" {
+	/**
+	 * Sprite href for the imported icon, e.g.
+	 * `/_astro/<pack>-<hash>.svg#<icon>`
+	 */
+	const href: string;
+	export default href;
+}

package/dist/astro/integration.d.mts

@@ -0,0 +1,11 @@
+import { t as Options } from "../type-S4YO472i.mjs";
+import { AstroIntegration } from "astro";
+
+//#region src/astro.d.ts
+/**
+ * Astro integration that adds the vite plugin and writes sprites for icons
+ * registered with `getIcon` once every page has been rendered
+ */
+declare function iconifySvgmapIntegration(options?: Options): AstroIntegration;
+//#endregion
+export { iconifySvgmapIntegration as default };

package/dist/astro/integration.mjs

@@ -0,0 +1,22 @@
+import { n as iconifySvgmap, o as name, r as writeSprites } from "../src-CsllISxW.mjs";
+//#region src/astro.ts
+/**
+* Astro integration that adds the vite plugin and writes sprites for icons
+* registered with `getIcon` once every page has been rendered
+*/
+function iconifySvgmapIntegration(options = {}) {
+	return {
+		name,
+		hooks: {
+			async "astro:build:done"({ dir, logger }) {
+				const written = await writeSprites(dir);
+				if (written.length > 0) logger.info(`wrote ${written.length} svg sprite(s)`);
+			},
+			"astro:config:setup"({ updateConfig }) {
+				updateConfig({ vite: { plugins: [iconifySvgmap(options)] } });
+			}
+		}
+	};
+}
+//#endregion
+export { iconifySvgmapIntegration as default };

package/dist/index.d.mts

@@ -0,0 +1,24 @@
+import { t as Options } from "./type-S4YO472i.mjs";
+import { Plugin } from "vite";
+
+//#region src/index.d.ts
+declare const VIRTUAL_MODULE_ID = "virtual:iconify-svgmap";
+/**
+ * Vite plugin that turns iconify icons into svg sprite maps
+ *
+ * - `import href from "virtual:iconify-svgmap/<pack>/<icon>"` resolves at build
+ *   time and emits a content hashed `<pack>.svg` sprite through vite
+ * - `import { getIcon } from "virtual:iconify-svgmap"` registers icons while
+ *   pages render; call {@link writeSprites} after rendering to write their
+ *   sprites (the `/astro` integration does this for you)
+ */
+declare function iconifySvgmap(options?: Options): Plugin;
+/**
+ * Write sprites for every icon registered with `getIcon` into
+ * `<outDirectory>/<dir>/<pack>.svg`. call this after all pages have rendered.
+ *
+ * @returns The paths of the written sprites
+ */
+declare function writeSprites(outDirectory: string | URL): Promise<string[]>;
+//#endregion
+export { type Options, VIRTUAL_MODULE_ID, iconifySvgmap as default, writeSprites };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as iconifySvgmap, r as writeSprites, t as VIRTUAL_MODULE_ID } from "./src-CsllISxW.mjs";
+export { VIRTUAL_MODULE_ID, iconifySvgmap as default, writeSprites };