@stephansama/vite-iconify-svgmap 0.1.0

package/dist/svelte/integration.d.mts

@@ -0,0 +1,23 @@
+import { t as Options } from "../type-S4YO472i.mjs";
+import { Plugin } from "vite";
+
+//#region src/svelte.d.ts
+/**
+ * Vite plugins for sveltekit. add after `sveltekit()`:
+ *
+ * ```js
+ * plugins: [sveltekit(), iconifySvgmap()];
+ * ```
+ *
+ * Sveltekit prerenders in a worker thread during its server build's
+ * `writeBundle` and runs the adapter in `closeBundle`:
+ *
+ * - When the client build is written, an empty placeholder sprite is added for
+ *   every installed icon pack so the prerender crawler does not fail on `<use
+ *   href>` links to sprites that do not exist yet
+ * - After prerendering the real sprites replace the placeholders (unused ones are
+ *   removed), before the adapter copies the client output
+ */
+declare function iconifySvgmapSvelteKit(options?: Options): Plugin[];
+//#endregion
+export { iconifySvgmapSvelteKit as default };

package/dist/svelte/integration.mjs

@@ -0,0 +1,80 @@
+import { a as getState, i as NAME_REGEX, n as iconifySvgmap, o as name, r as writeSprites } from "../src-CsllISxW.mjs";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/svelte.ts
+const EMPTY_SPRITE = `<svg xmlns="http://www.w3.org/2000/svg" style="display:none"></svg>`;
+const JSON_EXTENSION_REGEX = /\.json$/;
+/**
+* Vite plugins for sveltekit. add after `sveltekit()`:
+*
+* ```js
+* plugins: [sveltekit(), iconifySvgmap()];
+* ```
+*
+* Sveltekit prerenders in a worker thread during its server build's
+* `writeBundle` and runs the adapter in `closeBundle`:
+*
+* - When the client build is written, an empty placeholder sprite is added for
+*   every installed icon pack so the prerender crawler does not fail on `<use
+*   href>` links to sprites that do not exist yet
+* - After prerendering the real sprites replace the placeholders (unused ones are
+*   removed), before the adapter copies the client output
+*/
+function iconifySvgmapSvelteKit(options = {}) {
+	const state = getState();
+	return [iconifySvgmap(options), {
+		apply: "build",
+		name: `${name}:sveltekit`,
+		writeBundle: {
+			async handler(outputOptions) {
+				if (!outputOptions.dir) return;
+				if (!Boolean(this.environment?.config.build.ssr)) {
+					await writePlaceholders(outputOptions.dir);
+					return;
+				}
+				const clientDirectory = path.resolve(outputOptions.dir, "..", "client");
+				const written = new Set(await writeSprites(clientDirectory));
+				for (const placeholder of state.placeholders) if (!written.has(placeholder)) await fs.promises.rm(placeholder, { force: true });
+				state.placeholders.clear();
+				if (written.size > 0) this.info(`wrote ${written.size} svg sprite(s)`);
+			},
+			order: "post",
+			sequential: true
+		}
+	}];
+	async function writePlaceholders(clientDirectory) {
+		const spriteDirectory = path.join(clientDirectory, state.spriteDir);
+		await fs.promises.mkdir(spriteDirectory, { recursive: true });
+		for (const pack of listInstalledPacks(state.root)) {
+			const filename = path.join(spriteDirectory, `${pack}.svg`);
+			if (fs.existsSync(filename)) continue;
+			await fs.promises.writeFile(filename, EMPTY_SPRITE);
+			state.placeholders.add(filename);
+		}
+	}
+}
+/** Icon packs resolvable from `root`, following node's module resolution */
+function listInstalledPacks(root) {
+	const packs = /* @__PURE__ */ new Set();
+	let directory = path.resolve(root);
+	while (true) {
+		const modules = path.join(directory, "node_modules");
+		for (const pack of readDirectory(path.join(modules, "@iconify-json"))) if (NAME_REGEX.test(pack)) packs.add(pack);
+		for (const file of readDirectory(path.join(modules, "@iconify", "json", "json"))) {
+			const pack = file.replace(JSON_EXTENSION_REGEX, "");
+			if (NAME_REGEX.test(pack)) packs.add(pack);
+		}
+		const parent = path.dirname(directory);
+		if (parent === directory) return packs;
+		directory = parent;
+	}
+}
+function readDirectory(directory) {
+	try {
+		return fs.readdirSync(directory);
+	} catch {
+		return [];
+	}
+}
+//#endregion
+export { iconifySvgmapSvelteKit as default };

package/dist/type-S4YO472i.d.mts

@@ -0,0 +1,18 @@
+//#region src/type.d.ts
+interface Options {
+  /**
+   * Folder, relative to the output directory, that sprites for icons
+   * registered with `getIcon` are written to
+   *
+   * @default "_iconify"
+   */
+  dir?: string;
+  /**
+   * Directory used to resolve `@iconify-json/*` packages
+   *
+   * @default vite's `root`
+   */
+  root?: string | URL;
+}
+//#endregion
+export { Options as t };

package/frameworks/astro/astro.d.ts

@@ -0,0 +1,5 @@
+// lets plain tsc resolve `.astro` imports; editors use @astrojs/ts-plugin
+declare module "*.astro" {
+	const component: (properties: Record<string, unknown>) => unknown;
+	export default component;
+}

package/frameworks/astro/component.ts

@@ -0,0 +1 @@
+export { default as Icon } from "./icon.astro";

package/frameworks/astro/icon.astro

@@ -0,0 +1,31 @@
+---
+/// <reference types="../../client.d.ts" />
+import type { HTMLAttributes } from "astro/types";
+
+import { getIcon } from "virtual:iconify-svgmap";
+
+interface Props extends Omit<HTMLAttributes<"svg">, "height" | "width"> {
+	/** Icon name inside the pack, e.g. `astro` */
+	name: string;
+	/** Iconify pack, e.g. `logos` for `@iconify-json/logos` */
+	pack: string;
+	/** Width and height of the icon @default "1em" */
+	size?: number | string;
+	/** Accessible label; without it the icon is hidden from assistive tech */
+	title?: string;
+}
+
+const { name, pack, size = "1em", title, ...attributes } = Astro.props;
+const href = getIcon(pack, name);
+---
+
+<svg
+	aria-hidden={title ? undefined : "true"}
+	height={size}
+	role={title ? "img" : undefined}
+	width={size}
+	{...attributes}
+>
+	{title && <title>{title}</title>}
+	<use href={href}></use>
+</svg>

package/frameworks/astro/index.ts

@@ -0,0 +1,3 @@
+export { default as integration } from "../../dist/astro/integration.mjs";
+
+export { Icon } from "./component";

package/frameworks/svelte/component.d.ts

@@ -0,0 +1,19 @@
+import type { Component } from "svelte";
+import type { SVGAttributes } from "svelte/elements";
+
+export interface IconProps extends Omit<
+	SVGAttributes<SVGSVGElement>,
+	"height" | "width"
+> {
+	/** Icon name inside the pack, e.g. `astro` */
+	name: string;
+	/** Iconify pack, e.g. `logos` for `@iconify-json/logos` */
+	pack: string;
+	/** Width and height of the icon @default "1em" */
+	size?: number | string;
+	/** Accessible label; without it the icon is hidden from assistive tech */
+	title?: string;
+}
+
+/** Svg sprite icon registered through `getIcon` */
+export declare const Icon: Component<IconProps>;

package/frameworks/svelte/component.js

@@ -0,0 +1 @@
+export { default as Icon } from "./icon.svelte";

package/frameworks/svelte/icon.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+	import type { SVGAttributes } from "svelte/elements";
+
+	import { getIcon } from "virtual:iconify-svgmap";
+
+	interface Props extends Omit<
+		SVGAttributes<SVGSVGElement>,
+		"height" | "width"
+	> {
+		/** Icon name inside the pack, e.g. `astro` */
+		name: string;
+		/** Iconify pack, e.g. `logos` for `@iconify-json/logos` */
+		pack: string;
+		/** Width and height of the icon @default "1em" */
+		size?: number | string;
+		/** Accessible label; without it the icon is hidden from assistive tech */
+		title?: string;
+	}
+
+	const { name, pack, size = "1em", title, ...attributes }: Props = $props();
+	const href = $derived(getIcon(pack, name));
+</script>
+
+<svg
+	aria-hidden={title ? undefined : "true"}
+	height={size}
+	role={title ? "img" : undefined}
+	width={size}
+	{...attributes}
+>
+	{#if title}<title>{title}</title>{/if}
+	<use {href}></use>
+</svg>

package/frameworks/svelte/index.d.ts

@@ -0,0 +1,3 @@
+export { default as integration } from "../../dist/svelte/integration.mjs";
+
+export { Icon, type IconProps } from "./component";

package/frameworks/svelte/index.js

@@ -0,0 +1,3 @@
+export { default as integration } from "../../dist/svelte/integration.mjs";
+
+export { Icon } from "./component.js";

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@stephansama/vite-iconify-svgmap",
+  "version": "0.1.0",
+  "description": "Vite plugin for generating iconify svg sprite maps in memory",
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "astro",
+    "astro-integration",
+    "svgmap",
+    "svg-sprite",
+    "iconify",
+    "tanstack-intent",
+    "astro-component",
+    "svelte"
+  ],
+  "homepage": "https://packages.stephansama.info/api/@stephansama/vite-iconify-svgmap",
+  "bugs": {
+    "url": "https://github.com/stephansama/packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stephansama/packages.git",
+    "directory": "core/vite-iconify-svgmap"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Stephan Randle",
+    "email": "stephanrandle.dev@gmail.com",
+    "url": "https://stephansama.info"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./astro": "./frameworks/astro/index.ts",
+    "./astro/component": "./frameworks/astro/component.ts",
+    "./astro/integration": "./dist/astro/integration.mjs",
+    "./client": {
+      "types": "./client.d.ts"
+    },
+    "./package.json": "./package.json",
+    "./svelte": {
+      "types": "./frameworks/svelte/index.d.ts",
+      "svelte": "./frameworks/svelte/component.js",
+      "default": "./frameworks/svelte/index.js"
+    },
+    "./svelte/component": {
+      "types": "./frameworks/svelte/component.d.ts",
+      "svelte": "./frameworks/svelte/component.js",
+      "default": "./frameworks/svelte/component.js"
+    },
+    "./svelte/integration": "./dist/svelte/integration.mjs"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "client.d.ts",
+    "dist",
+    "frameworks",
+    "skills"
+  ],
+  "devDependencies": {
+    "@iconify-json/logos": "1.2.10",
+    "@iconify-json/octicon": "1.2.21",
+    "@iconify/types": "2.0.0",
+    "@iconify/utils": "2.3.0",
+    "@tanstack/intent": "0.0.41",
+    "astro": "6.3.1",
+    "svelte": "5.51.2",
+    "tsdown": "0.21.10",
+    "vite": "6.3.5"
+  },
+  "peerDependencies": {
+    "astro": ">=5",
+    "svelte": ">=5",
+    "vite": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "inlinedDependencies": {
+    "@antfu/install-pkg": "1.1.0",
+    "@antfu/utils": "8.1.1",
+    "@iconify/utils": "2.3.0",
+    "acorn": "8.16.0",
+    "kolorist": "1.8.0",
+    "local-pkg": "1.1.2",
+    "mlly": "1.8.2",
+    "package-manager-detector": "1.6.0",
+    "pathe": "2.0.3",
+    "quansync": "0.2.11",
+    "tinyexec": "1.1.2",
+    "ufo": "1.6.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:snapshot": "tsdown -u",
+    "dev": "tsdown --watch",
+    "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix"
+  }
+}

package/skills/vite-iconify-svgmap/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: vite-iconify-svgmap
+description: >
+  Vite plugin (with an Astro integration) that builds SVG sprite maps from
+  @iconify-json/* icon packs in memory. Import icons statically with
+  `import href from "virtual:iconify-svgmap/<pack>/<icon>"`, or call
+  `getIcon(pack, name)` from "virtual:iconify-svgmap" for icons only known while
+  rendering. Add `@stephansama/vite-iconify-svgmap/client` to tsconfig types.
+type: framework
+requires:
+  - vite
+library: "@stephansama/vite-iconify-svgmap"
+library_version: "0.0.0"
+sources:
+  - stephansama/packages:core/vite-iconify-svgmap/src/index.ts
+  - stephansama/packages:core/vite-iconify-svgmap/src/astro.ts
+  - stephansama/packages:core/vite-iconify-svgmap/src/svelte.ts
+  - stephansama/packages:core/vite-iconify-svgmap/frameworks/astro/icon.astro
+  - stephansama/packages:core/vite-iconify-svgmap/frameworks/svelte/icon.svelte
+  - stephansama/packages:core/vite-iconify-svgmap/src/state.ts
+  - stephansama/packages:core/vite-iconify-svgmap/client.d.ts
+---
+
+# vite-iconify-svgmap
+
+Generates SVG sprite maps from Iconify icon packs. Icon usage is tracked in memory; the only files written are the final sprites.
+
+## Setup
+
+1. Install the plugin and at least one `@iconify-json/*` pack:
+
+```sh
+pnpm add -D @stephansama/vite-iconify-svgmap @iconify-json/mdi
+```
+
+1. Astro: add the integration to `astro.config.mjs`:
+
+```js
+import iconifySvgmap from "@stephansama/vite-iconify-svgmap/astro/integration";
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  integrations: [iconifySvgmap()],
+});
+```
+
+SvelteKit: add the plugins from `@stephansama/vite-iconify-svgmap/svelte/integration` after `sveltekit()` in `vite.config.js`:
+
+```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()] });
+```
+
+Plain Vite: add `iconifySvgmap()` from `@stephansama/vite-iconify-svgmap` to `plugins`.
+
+1. Add the virtual module types to `tsconfig.json`:
+
+```json
+{ "compilerOptions": { "types": ["@stephansama/vite-iconify-svgmap/client"] } }
+```
+
+## Core Patterns
+
+### Static imports (preferred)
+
+```astro
+---
+import home from "virtual:iconify-svgmap/mdi/home";
+---
+
+<svg width="24" height="24" aria-hidden="true"><use href={home}></use></svg>
+```
+
+The default export is the sprite href (`/_astro/mdi.<hash>.svg#home` in builds). Unknown packs or icons fail the build.
+
+### Icons only known while rendering
+
+```astro
+---
+import { getIcon } from "virtual:iconify-svgmap";
+
+const href = getIcon(entry.data.pack, entry.data.icon);
+---
+
+<svg width="24" height="24" aria-hidden="true"><use href={href}></use></svg>
+```
+
+`getIcon` is synchronous. It registers the icon in memory and returns `/_iconify/<pack>.svg?v=<build>#<icon>`. The Astro integration writes those sprites in `astro:build:done`; without Astro call `writeSprites(clientOutDir)` after rendering.
+
+### Icon components (astro, svelte)
+
+```astro
+---
+import { Icon } from "@stephansama/vite-iconify-svgmap/astro/component";
+---
+
+<Icon pack="mdi" name="home" size={24} title="Home" class="nav-icon" />
+```
+
+`@stephansama/vite-iconify-svgmap/astro/component` and `@stephansama/vite-iconify-svgmap/svelte/component` (Svelte 5) both export `Icon`. It calls `getIcon` and renders `<svg><use href /></svg>`. Props: `pack`, `name`, `size` (default `"1em"`), `title` (adds `role="img"`, otherwise `aria-hidden="true"`); other attributes pass through to `<svg>`. Same rules as `getIcon`: needs the Astro integration (or `writeSprites`) and server rendering during the build; client-only Svelte components are not registered.
+
+## Common Mistakes
+
+### HIGH Computed virtual imports
+
+Wrong:
+
+```js
+const href = await import(`virtual:iconify-svgmap/${pack}/${name}`);
+```
+
+Correct:
+
+```js
+import { getIcon } from "virtual:iconify-svgmap";
+const href = getIcon(pack, name);
+```
+
+Vite cannot resolve template-literal virtual imports. Use `getIcon` for dynamic names.
+
+### HIGH Using the raw plugin with getIcon in SvelteKit
+
+Wrong:
+
+```js
+export default defineConfig({ plugins: [sveltekit(), iconifySvgmap()] }); // from "@stephansama/vite-iconify-svgmap"
+```
+
+Correct:
+
+```js
+import iconifySvgmap from "@stephansama/vite-iconify-svgmap/svelte/integration";
+export default defineConfig({ plugins: [sveltekit(), iconifySvgmap()] });
+```
+
+Without the `/svelte/integration` plugins the prerender crawler fails with `404 /_iconify/<pack>.svg` and sprites are never written.
+
+### HIGH Using the raw plugin with getIcon in Astro
+
+Wrong:
+
+```js
+export default defineConfig({ vite: { plugins: [iconifySvgmap()] } });
+```
+
+Correct:
+
+```js
+export default defineConfig({ integrations: [iconifySvgmap()] });
+```
+
+Astro prerenders after Vite's build hooks, so only the integration (`/astro/integration`) can write `getIcon` sprites. Static imports work either way.
+
+### MEDIUM getIcon at request time
+
+Icons first requested by on-demand rendered routes, only by client-side code, or by prerendering in another runtime (e.g. workerd) are not included in written sprites. Worker threads of the build process (SvelteKit's prerenderer) are supported. Use static imports, or make sure those icons are also rendered during the build.
+
+Source: `core/vite-iconify-svgmap/src/index.ts`