vite-svg-to-ico 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaj Kowalski
+
+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,83 @@
+# vite-svg-to-ico
+
+Vite plugin that converts an SVG file into a multi-size `.ico` favicon at build time. Serves the generated ICO during development with HMR support.
+
+## Install
+
+```sh
+npm install -D vite-svg-to-ico
+```
+
+Requires [`sharp`](https://sharp.pixelplumbing.com/) as a runtime dependency (installed automatically).
+
+## Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import svgToIco from "vite-svg-to-ico";
+
+export default defineConfig({
+  plugins: [svgToIco({ input: "src/icon.svg" })],
+});
+```
+
+### Custom sizes and output filename
+
+```ts
+svgToIco({
+  input: "src/logo.svg",
+  output: "icon.ico",
+  sizes: [16, 24, 32, 48, 64, 128, 256],
+});
+```
+
+### Skip PNG optimization for faster builds
+
+```ts
+svgToIco({
+  input: "src/icon.svg",
+  optimize: false,
+});
+```
+
+### Emit the source SVG alongside the ICO
+
+```ts
+svgToIco({
+  input: "src/icon.svg",
+  includeSource: true,
+});
+```
+
+### Emit the source SVG with a custom filename
+
+```ts
+svgToIco({
+  input: "src/icon.svg",
+  includeSource: { name: "logo.svg" },
+});
+```
+
+## Options
+
+| Option          | Type                             | Default         | Description                                         |
+| --------------- | -------------------------------- | --------------- | --------------------------------------------------- |
+| `input`         | `string`                         | **(required)**  | Path to the source SVG file.                        |
+| `output`        | `string`                         | `'favicon.ico'` | Output filename for the generated ICO.              |
+| `sizes`         | `number \| number[]`             | `[16, 32, 48]`  | Pixel dimensions to rasterize (1-256).              |
+| `optimize`      | `boolean`                        | `true`          | Max PNG compression (level 9 + adaptive filtering). |
+| `includeSource` | `boolean \| { name?, enabled? }` | `false`         | Emit the source SVG alongside the ICO.              |
+
+## How it works
+
+- **Build**: reads the SVG, rasterizes it to PNG at each size via `sharp`, packs the PNGs into an ICO container (PNG-in-ICO format), and emits it as a Rollup asset.
+- **Dev**: pre-generates the ICO on server start and serves it via middleware. Regenerates automatically when the source SVG changes (HMR).
+
+## Debug
+
+Set `DEBUG=vite-svg-to-ico` to enable timing instrumentation.
+
+## License
+
+[MIT](https://github.com/kjanat/vite-svg-to-ico/blob/master/LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,89 @@
+import { Plugin } from "vite";
+
+//#region src/types.d.ts
+/** Configuration for the [`vite-svg-to-ico`](https://github.com/kjanat/vite-svg-to-ico "GitHub") plugin.
+ * @see https://npmjs.com/package/vite-svg-to-ico#options
+ */
+interface PluginOptions {
+  /** Absolute or root-relative path to the source SVG file. */
+  input: string;
+  /** Output filename for the generated `.ico` asset.
+   * @default 'favicon.ico' */
+  output?: string;
+  /** Pixel dimensions to rasterize (each value produces a square PNG layer).
+   *
+   * A single value is wrapped into an array automatically.
+   * Must be integers in the range 1–256 per the ICO spec.
+   * @default [16, 32, 48] */
+  sizes?: IconSize | IconSize[];
+  /** Apply maximum PNG compression (level 9 + adaptive filtering).
+   * @default true */
+  optimize?: boolean;
+  /** Copy over the input SVG file to the output directory alongside the ICO.
+   *
+   * Pass `true` to emit with the original basename, or an object to customise.
+   * @default false */
+  includeSource?: boolean | IncludeSourceOptions;
+}
+/** Common ICO pixel dimensions with IDE autocompletion; any integer 1–256 is accepted. */
+type IconSize = 16 | 24 | 32 | 48 | 64 | 128 | 256 | (number & {});
+/** Fine-grained control for emitting the source SVG alongside the ICO. */
+interface IncludeSourceOptions {
+  /** Override the output filename for the emitted SVG.
+   * @default basename(input) */
+  name?: string;
+  /** Whether to emit the source SVG.
+   * @default true */
+  enabled?: boolean;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Vite plugin that converts an SVG source into a multi-size `.ico` favicon.
+ *
+ * @description
+ * Returns three composable sub-plugins:
+ * 1. **config** — validates options after config is resolved.
+ * 2. **serve** — lazily generates the ICO and serves it via dev-server middleware;
+ *    regenerates on HMR when the source SVG changes.
+ * 3. **build** — generates the ICO at build time and emits it as a Rollup asset.
+ *
+ * @example Basic usage
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import svgToIco from 'vite-svg-to-ico';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     svgToIco({ input: 'src/icon.svg' }),
+ *   ],
+ * });
+ *
+ * @example Custom sizes and output filename
+ * svgToIco({
+ *   input: 'src/logo.svg',
+ *   output: 'icon.ico',
+ *   sizes: [16, 24, 32, 48, 64, 128, 256],
+ * })
+ *
+ * @example Skip PNG optimization for faster builds
+ * svgToIco({
+ *   input: 'src/icon.svg',
+ *   optimize: false,
+ * })
+ *
+ * @example Emit the source SVG alongside the ICO
+ * svgToIco({
+ *   input: 'src/icon.svg',
+ *   includeSource: true,
+ * })
+ *
+ * @example Emit the source SVG with a custom filename
+ * svgToIco({
+ *   input: 'src/icon.svg',
+ *   includeSource: { name: 'logo.svg' },
+ * })
+ */
+declare function svgToIco(opts: PluginOptions): Plugin[];
+//#endregion
+export { type IconSize, type IncludeSourceOptions, type PluginOptions, svgToIco as default };

package/dist/index.mjs

@@ -0,0 +1,247 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import sharp from "sharp";
+
+//#region src/ico.ts
+/**
+* Rasterize an SVG to multiple PNG sizes and pack them into an ICO buffer.
+*
+* @param svg      - SVG contents as a Buffer, or a filesystem path to read.
+* @param sizes    - Square pixel dimensions for each PNG layer.
+* @param optimize - Whether to use maximum PNG compression.
+* @returns ICO file contents as a {@link Buffer}.
+*/
+async function generateIco(svg, sizes, optimize) {
+	const svgBuffer = Buffer.isBuffer(svg) ? svg : await readFile(svg);
+	return packIco(await Promise.all(sizes.map((size) => sharp(svgBuffer).resize(size, size, {
+		fit: "contain",
+		background: {
+			r: 0,
+			g: 0,
+			b: 0,
+			alpha: 0
+		}
+	}).png({
+		compressionLevel: optimize ? 9 : 6,
+		adaptiveFiltering: optimize
+	}).toBuffer())), sizes);
+}
+/** ICO type identifier (1 = icon, 2 = cursor). */
+const ICO_TYPE = 1;
+/** Byte length of the ICONDIR header. */
+const HEADER_SIZE = 6;
+/** Byte length of a single ICONDIRENTRY. */
+const ENTRY_SIZE = 16;
+/**
+* Pack pre-rendered PNG buffers into an ICO container.
+*
+* Uses the modern PNG-in-ICO format (supported since Windows Vista).
+* Each PNG is stored verbatim — no BMP conversion or pixel manipulation.
+*
+* @see {@link https://en.wikipedia.org/wiki/ICO_(file_format) "ICO (file format)"}
+*/
+function packIco(pngs, sizes) {
+	const count = pngs.length;
+	const dataOffset = HEADER_SIZE + count * ENTRY_SIZE;
+	const header = Buffer.alloc(HEADER_SIZE);
+	header.writeUInt16LE(0, 0);
+	header.writeUInt16LE(ICO_TYPE, 2);
+	header.writeUInt16LE(count, 4);
+	let offset = dataOffset;
+	const entries = Buffer.alloc(count * ENTRY_SIZE);
+	for (const [i, [png, size]] of pngs.map((p, j) => [p, sizes[j] ?? 0]).entries()) {
+		const pos = i * ENTRY_SIZE;
+		entries.writeUInt8(size >= 256 ? 0 : size, pos);
+		entries.writeUInt8(size >= 256 ? 0 : size, pos + 1);
+		entries.writeUInt8(0, pos + 2);
+		entries.writeUInt8(0, pos + 3);
+		entries.writeUInt16LE(1, pos + 4);
+		entries.writeUInt16LE(32, pos + 6);
+		entries.writeUInt32LE(png.length, pos + 8);
+		entries.writeUInt32LE(offset, pos + 12);
+		offset += png.length;
+	}
+	return Buffer.concat([
+		header,
+		entries,
+		...pngs
+	]);
+}
+
+//#endregion
+//#region src/instrumentation.ts
+const DEBUG = process.env.DEBUG === "vite-svg-to-ico";
+/**
+* Debug-only timing instrumentation.
+*
+* Enable with `DEBUG=vite-svg-to-ico`.
+*/
+var Instrumentation = class {
+	times = /* @__PURE__ */ new Map();
+	/** Begin a labeled timer; no-op when {@link DEBUG} is `false`. */
+	start(label) {
+		if (!DEBUG) return;
+		this.times.set(label, performance.now());
+		console.log(`[svg-to-ico] ${label}...`);
+	}
+	/** Log elapsed time for a previously started label; no-op when {@link DEBUG} is `false`. */
+	end(label) {
+		if (!DEBUG) return;
+		const start = this.times.get(label);
+		if (start) {
+			const duration = (performance.now() - start).toFixed(2);
+			console.log(`[svg-to-ico] ${label} (${duration}ms)`);
+		}
+	}
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* Vite plugin that converts an SVG source into a multi-size `.ico` favicon.
+*
+* @description
+* Returns three composable sub-plugins:
+* 1. **config** — validates options after config is resolved.
+* 2. **serve** — lazily generates the ICO and serves it via dev-server middleware;
+*    regenerates on HMR when the source SVG changes.
+* 3. **build** — generates the ICO at build time and emits it as a Rollup asset.
+*
+* @example Basic usage
+* // vite.config.ts
+* import { defineConfig } from 'vite';
+* import svgToIco from 'vite-svg-to-ico';
+*
+* export default defineConfig({
+*   plugins: [
+*     svgToIco({ input: 'src/icon.svg' }),
+*   ],
+* });
+*
+* @example Custom sizes and output filename
+* svgToIco({
+*   input: 'src/logo.svg',
+*   output: 'icon.ico',
+*   sizes: [16, 24, 32, 48, 64, 128, 256],
+* })
+*
+* @example Skip PNG optimization for faster builds
+* svgToIco({
+*   input: 'src/icon.svg',
+*   optimize: false,
+* })
+*
+* @example Emit the source SVG alongside the ICO
+* svgToIco({
+*   input: 'src/icon.svg',
+*   includeSource: true,
+* })
+*
+* @example Emit the source SVG with a custom filename
+* svgToIco({
+*   input: 'src/icon.svg',
+*   includeSource: { name: 'logo.svg' },
+* })
+*/
+function svgToIco(opts) {
+	let generatedIco = null;
+	let logger = null;
+	const { input, output = "favicon.ico", sizes: rawSizes = [
+		16,
+		32,
+		48
+	], optimize = true, includeSource: rawIncludeSource = false } = opts;
+	const sizes = Array.isArray(rawSizes) ? rawSizes : [rawSizes];
+	const sourceOpts = typeof rawIncludeSource === "object" ? {
+		enabled: rawIncludeSource.enabled ?? true,
+		name: rawIncludeSource.name ?? basename(input)
+	} : {
+		enabled: rawIncludeSource,
+		name: basename(input)
+	};
+	return [
+		{
+			name: "svg-to-ico:config",
+			enforce: "post",
+			configResolved(config) {
+				logger = config.logger;
+				if (!input) throw new Error("[svg-to-ico] `input` option is required");
+				const invalid = sizes.filter((s) => !Number.isInteger(s) || s < 1 || s > 256);
+				if (invalid.length > 0) throw new Error(`[svg-to-ico] Invalid sizes: ${invalid.join(", ")}. Must be integers 1–256.`);
+			}
+		},
+		{
+			name: "svg-to-ico:serve",
+			apply: "serve",
+			enforce: "post",
+			configureServer(server) {
+				server.middlewares.use(`/${output}`, async (_req, res, next) => {
+					try {
+						if (!generatedIco) generatedIco = await generateIco(input, sizes, optimize);
+						res.setHeader("Content-Type", "image/x-icon");
+						res.end(generatedIco);
+					} catch (e) {
+						next(e);
+					}
+				});
+				if (sourceOpts.enabled) server.middlewares.use(`/${sourceOpts.name}`, async (_req, res, next) => {
+					try {
+						const svgBuffer = await readFile(input);
+						res.setHeader("Content-Type", "image/svg+xml");
+						res.end(svgBuffer);
+					} catch (e) {
+						next(e);
+					}
+				});
+			},
+			async buildStart() {
+				const I = new Instrumentation();
+				I.start("Generate ICO (serve)");
+				generatedIco = await generateIco(input, sizes, optimize);
+				I.end("Generate ICO (serve)");
+			},
+			async handleHotUpdate({ file, server }) {
+				if (file === input) {
+					const I = new Instrumentation();
+					I.start("Regenerate ICO (HMR)");
+					generatedIco = await generateIco(input, sizes, optimize);
+					I.end("Regenerate ICO (HMR)");
+					server.hot.send({
+						type: "full-reload",
+						path: `/${output}`
+					});
+				}
+			}
+		},
+		{
+			name: "svg-to-ico:build",
+			apply: "build",
+			enforce: "post",
+			async buildStart() {
+				const I = new Instrumentation();
+				I.start("Generate ICO (build)");
+				try {
+					const svgBuffer = await readFile(input);
+					const icoBuffer = await generateIco(svgBuffer, sizes, optimize);
+					this.emitFile({
+						type: "asset",
+						fileName: output,
+						source: icoBuffer
+					});
+					if (sourceOpts.enabled) this.emitFile({
+						type: "asset",
+						fileName: sourceOpts.name,
+						source: svgBuffer
+					});
+					I.end("Generate ICO (build)");
+					if (DEBUG && logger) logger.info(`Generated ${output}`);
+				} catch (error) {
+					this.error(`[svg-to-ico] Failed to generate ICO: ${error}`);
+				}
+			}
+		}
+	];
+}
+
+//#endregion
+export { svgToIco as default };

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "vite-svg-to-ico",
+	"version": "0.1.0",
+	"description": "A Vite plugin that converts SVG files to ICO format during the build process.",
+	"keywords": [
+		"vite-plugin",
+		"vite",
+		"svg",
+		"ico",
+		"favicon",
+		"converter"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/kjanat/vite-svg-to-ico"
+	},
+	"license": "MIT",
+	"author": "Kaj Kowalski <info@kajkowalski.nl> (https://github.com/kjanat)",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"bd": "tsdown",
+		"build": "tsdown",
+		"dev": "tsdown --watch",
+		"fmt": "dprint fmt",
+		"prepack": "bunx prettier --write README.md",
+		"prepublish": "bun bd",
+		"typecheck": "tsgo --noEmit"
+	},
+	"dependencies": {
+		"sharp": "^0.34.5"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@typescript/native-preview": "^7.0.0-dev.20260225.1",
+		"dprint": "^0.52.0",
+		"tsdown": "^0.20.3",
+		"typescript": "^5.9.3",
+		"unplugin-unused": "^0.5.7"
+	},
+	"peerDependencies": {
+		"vite": "^6.0.0 || ^7.0.0"
+	},
+	"packageManager": "bun@1.3.9",
+	"publishConfig": {
+		"exports": {
+			".": "./dist/index.mjs",
+			"./package.json": "./package.json"
+		}
+	}
+}