react-icons-sprite 0.4.0 → 0.6.0

package/README.md

@@ -1,10 +1,30 @@
 # react-icons-sprite
 
-`react-icons-sprite` is a lightweight plugin for Vite and Webpack, built on top of [react-icons](https://github.com/react-icons/react-icons). It automatically detects the `react-icons` components you use, generates a single SVG spritesheet containing them, and rewrites your code to reference those symbols via `<use>`. This approach both shrinks your bundle (no more inlined React components for every icon) and reduces runtime overhead, since React no longer has to reconcile large, nested SVG trees.
+`react-icons-sprite` is a lightweight plugin for Vite and Webpack that turns React icon components into a single SVG spritesheet and rewrites your code to reference those symbols via `<use>`.
+
+It supports multiple React icon packages that export icons as individual React components. This approach both shrinks your bundle (no more inlined React components for every icon) and reduces runtime overhead, since React no longer has to reconcile large, nested SVG trees.
+
+## Supported icon libraries
+
+Out of the box, imports from the following libraries are detected and transformed:
+
+- `react-icons/*` packs (e.g. `react-icons/bi`, `react-icons/fa`, ...)
+- `lucide-react`
+- `@radix-ui/react-icons`
+- `@heroicons/react` (v1 and v2 subpaths)
+- `@tabler/icons-react`
+- `phosphor-react`
+- `@phosphor-icons/react`
+- `react-feather`
+- `react-bootstrap-icons`
+- `grommet-icons`
+- `remixicon-react`
+- `@remixicon/react`
+- `devicons-react`
 
 ## Motivation
 
-By default, when you use `react-icons`, each icon is a React component. For example:
+By default, when you use an icon library like `react-icons`, each icon is a React component. For example:
 
 ```tsx
 import { LuWheat } from "react-icons/lu";
@@ -64,7 +84,7 @@ export function Example() {
 import { b as n } from './icon-FONPSuqX.js';
 
 var r = e(t());
-const i = () => (0, r.jsx)(n, { iconId: `ri-LuWheat` });
+const i = () => (0, r.jsx)(n, { iconId: `ri-react-icons-lu-LuWheat` });
 export { i as IconWheat };
 ```
 
@@ -93,6 +113,26 @@ Runtime difference:
 
 This is a big win when you’re rendering icons in lists, tables, or maps where dozens or hundreds of them appear at once.
 
+### Performance comparison
+
+| icon (pack)        | react-icons icon render mean time |     react-icons-sprite icon render mean time | Relative difference     |
+|--------------------|----------------------------------:|---------------------------------------------:|------------------------:|
+| **FiCpu** (fi)     |                          0.188 ms |                                        0.048 ms | 74.6% reduction         |
+| **MdBuild** (md)   |                          0.198 ms |                                        0.048 ms | 76.0% reduction         |
+| **FaCamera** (fa)  |                             0.162 ms |                                        0.015 ms | 90.7% reduction         |
+| **IoAperture** (io5)|                             0.029 ms |                                        0.015 ms | 49.7% reduction         |
+| **BiBell** (bi)    |                             0.023 ms |                                        0.014 ms | 38.5% reduction         |
+| **AiOutlineAlert** (ai) |                             0.023 ms |                                        0.014 ms | 38.3% reduction         |
+| **BsAlarm** (bs)   |                             0.027 ms |                                        0.014 ms | 47.4% reduction         |
+| **RiAnchor** (ri)  |                             0.023 ms |                                        0.014 ms | 38.6% reduction         |
+| **CgArrows** (cg)  |                             0.029 ms |                                        0.014 ms | 52.0% reduction         |
+| **HiAcademicCap** (hi) |                             0.023 ms |                                        0.014 ms | 38.6% reduction         |
+| **SiTypescript** (si) |                             0.023 ms |                                        0.014 ms | 39.7% reduction         |
+| **TiThLarge** (ti) |                             0.023 ms |                                        0.014 ms | 40.0% reduction         |
+
+* **Test details / machine:** **Lenovo Legion 5 Pro 16ACH6H** (Ryzen 7 5800H — 8 cores / 16 threads, base ≈ 3.2 GHz, turbo ≈ 4.4 GHz, DDR4-3200 memory); Node.js v24.10.0.
+* Differences will vary based on icons used in your application, but they will generally be the range of 50-75% reduction in render time. Larger icons will generate a larger difference.
+
 ## Installation
 
 Install the plugin via npm or yarn:
@@ -115,7 +155,7 @@ export default defineConfig({
 ```
 
 ### Webpack
-Add the loader to transform modules that import from `react-icons/*` and install the plugin to emit the sprite and rewrite the placeholder URL.
+Add the loader to transform modules that import icons and install the plugin to emit the sprite and rewrite the placeholder URL.
 
 ```js
 // webpack.config.js (v5)
@@ -144,18 +184,14 @@ module.exports = {
       // optional: fileName: 'icons.svg'
     }),
   ],
-  output: {
-    // ensure your publicPath is set correctly if you deploy under a sub-path
-    // publicPath: '/',
-  },
 };
 ```
 
 ## How it works
 
-In **development mode**, the plugin does nothing special. Icons are rendered as they normally would from `react-icons`. This keeps hot module replacement (HMR) snappy — there’s no extra parsing of the codebase or regenerating of the sprite on every save. If the plugin were to build the sprite during dev, it would need to constantly scan for `react-icons` imports and rebuild the sheet, which is expensive and slows down iteration. So, in dev, you get the normal `react-icons` behavior.
+In **development mode**, the plugin does nothing special. Icons are rendered as they normally would from your icon library. This keeps hot module replacement (HMR) snappy — there’s no extra parsing of the codebase or regenerating of the sprite on every save. If the plugin were to build the sprite during dev, it would need to constantly scan for icon imports and rebuild the sheet, which is expensive and slows down iteration. So, in dev, you get the normal component behavior.
 
-In **build mode**, the plugin transforms your code. It parses each module, looks for imports from `react-icons/*`, and rewrites the JSX. Instead of rendering full inline `<svg>` trees, it replaces them with `<ReactIconsSpriteIcon iconId="..." />`. While doing this, it collects every unique icon used across the project. After the bundling step, the plugin renders all those icons once to static markup and generates a single SVG file containing `<symbol>` definitions for each one. Finally, it rewrites your bundle to point every `<ReactIconsSpriteIcon>` at that spritesheet using a `<use>` tag.
+In **build mode**, the plugin transforms your code. It parses each module, looks for imports from supported React icon packages, and rewrites the JSX. Instead of rendering full inline `<svg>` trees, it replaces them with `<ReactIconsSpriteIcon iconId="..." />`. While doing this, it collects every unique icon used across the project. After the bundling step, the plugin renders all those icons once to static markup and generates a single SVG file containing `<symbol>` definitions for each one. Finally, it rewrites your bundle to point every `<ReactIconsSpriteIcon>` at that spritesheet using a `<use>` tag.
 
 The result: during development you keep fast feedback loops, and in production you ship a single optimized sprite file with lightweight `<use>` references.
 

package/dist/collector-DrPR8kXO.mjs

@@ -0,0 +1,7 @@
+import { r as createCollector } from "./core-BoovxbBC.mjs";
+
+//#region src/collector.ts
+const collector = createCollector();
+
+//#endregion
+export { collector as t };

package/dist/{core-CcX_8jJU.mjs → core-BoovxbBC.mjs}

@@ -8,9 +8,30 @@ import _generate from "@babel/generator";
 //#region src/core.ts
 const traverse = _traverse.default ?? _traverse;
 const generate = _generate.default ?? _generate;
-const PLACEHOLDER = "__SPRITE_URL_PLACEHOLDER__";
 const ICON_SOURCE = "react-icons-sprite";
 const ICON_COMPONENT_NAME = "ReactIconsSpriteIcon";
+const DEFAULT_ICON_SOURCES = [
+	/^react-icons\/[\w-]+$/,
+	/^lucide-react$/,
+	/^@radix-ui\/react-icons$/,
+	/^@heroicons\/react(?:\/.*)?$/,
+	/^@tabler\/icons-react$/,
+	/^phosphor-react$/,
+	/^@phosphor-icons\/react$/,
+	/^react-feather$/,
+	/^react-bootstrap-icons$/,
+	/^grommet-icons$/,
+	/^remixicon-react$/,
+	/^@remixicon\/react$/,
+	/^devicons-react$/
+];
+const sourceMatchesSupported = (source, sources = DEFAULT_ICON_SOURCES) => sources.some((re) => re.test(source));
+const normalizeAlias = (pack) => {
+	return pack.replace(/^@/, "").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+};
+const computeIconId = (pack, exportName) => {
+	return `ri-${normalizeAlias(pack)}-${exportName}`;
+};
 const parseAst = (code, filename = "module.tsx") => {
 	return parse(code, {
 		sourceType: "module",
@@ -18,9 +39,9 @@ const parseAst = (code, filename = "module.tsx") => {
 		sourceFilename: filename
 	});
 };
-const collectReactIconImports = (ast) => {
+const collectIconImports = (ast, sources = DEFAULT_ICON_SOURCES) => {
 	const map = /* @__PURE__ */ new Map();
-	for (const node of ast.program.body) if (t.isImportDeclaration(node) && /^react-icons\/[\w-]+$/.test(node.source.value) && node.importKind !== "type") {
+	for (const node of ast.program.body) if (t.isImportDeclaration(node) && sourceMatchesSupported(node.source.value, sources) && node.importKind !== "type") {
 		const pack = node.source.value;
 		for (const spec of node.specifiers) if (t.isImportSpecifier(spec) && t.isIdentifier(spec.imported) && t.isIdentifier(spec.local) && spec.importKind !== "type") {
 			const exportName = spec.imported.name;
@@ -64,7 +85,10 @@ const replaceJsxWithSprite = (ast, localNameToImport, iconLocalName, register) =
 			if (!meta) return;
 			if (isAlreadyIcon(name)) return;
 			path.node.name = t.jSXIdentifier(iconLocalName);
-			if (!path.node.attributes.some((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name, { name: "iconId" }))) path.node.attributes.unshift(t.jSXAttribute(t.jSXIdentifier("iconId"), t.stringLiteral(`ri-${meta.exportName}`)));
+			if (!path.node.attributes.some((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name, { name: "iconId" }))) {
+				const idValue = computeIconId(meta.pack, meta.exportName);
+				path.node.attributes.unshift(t.jSXAttribute(t.jSXIdentifier("iconId"), t.stringLiteral(idValue)));
+			}
 			usedLocalNames.add(local);
 			anyReplacements = true;
 			register(meta.pack, meta.exportName);
@@ -105,9 +129,9 @@ const generateCode = (ast, origCode, id) => {
 		map
 	};
 };
-const transformModule = (code, id, register) => {
+const transformModule = (code, id, register, sources = DEFAULT_ICON_SOURCES) => {
 	const ast = parseAst(code, id);
-	const localNameToImport = collectReactIconImports(ast);
+	const localNameToImport = collectIconImports(ast, sources);
 	if (localNameToImport.size === 0) return {
 		code,
 		map: null,
@@ -151,7 +175,7 @@ const renderOneIcon = async (pack, exportName) => {
 		pack
 ))[exportName];
 	if (!Comp) throw new Error(`Icon export not found: ${pack} -> ${exportName}`);
-	const id = `ri-${exportName}`;
+	const id = computeIconId(pack, exportName);
 	const html = renderToStaticMarkup(createElement(Comp));
 	const viewBox = html.match(/viewBox="([^"]+)"/i)?.[1] ?? "0 0 24 24";
 	const svgAttrsRaw = html.match(/^<svg\b([^>]*)>/i)?.[1] ?? "";
@@ -188,4 +212,4 @@ const createCollector = () => {
 };
 
 //#endregion
-export { transformModule as i, buildSprite as n, createCollector as r, PLACEHOLDER as t };
+export { transformModule as i, buildSprite as n, createCollector as r, DEFAULT_ICON_SOURCES as t };

package/dist/icon.mjs

@@ -1,7 +1,7 @@
 import { jsx } from "react/jsx-runtime";
 
 //#region src/icon.tsx
-const ReactIconsSpriteIcon = ({ iconId,...rest }) => {
+const ReactIconsSpriteIcon = ({ iconId, ...rest }) => {
 	const iconHref = `__SPRITE_URL_PLACEHOLDER__#${iconId}`;
 	return /* @__PURE__ */ jsx("svg", {
 		height: "1em",

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+//#region src/index.d.ts
+declare const REACT_ICONS_SPRITE_URL_PLACEHOLDER = "__SPRITE_URL_PLACEHOLDER__";
+//#endregion
+export { REACT_ICONS_SPRITE_URL_PLACEHOLDER };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { t as REACT_ICONS_SPRITE_URL_PLACEHOLDER } from "./src-Bf4uZBwp.mjs";
+
+export { REACT_ICONS_SPRITE_URL_PLACEHOLDER };

package/dist/src-Bf4uZBwp.mjs

@@ -0,0 +1,5 @@
+//#region src/index.ts
+const REACT_ICONS_SPRITE_URL_PLACEHOLDER = "__SPRITE_URL_PLACEHOLDER__";
+
+//#endregion
+export { REACT_ICONS_SPRITE_URL_PLACEHOLDER as t };

package/dist/vite/plugin.mjs

@@ -1,4 +1,5 @@
-import { i as transformModule, n as buildSprite, r as createCollector, t as PLACEHOLDER } from "../core-CcX_8jJU.mjs";
+import { t as REACT_ICONS_SPRITE_URL_PLACEHOLDER } from "../src-Bf4uZBwp.mjs";
+import { i as transformModule, n as buildSprite, r as createCollector, t as DEFAULT_ICON_SOURCES } from "../core-BoovxbBC.mjs";
 import { createHash } from "node:crypto";
 
 //#region src/vite/plugin.ts
@@ -15,11 +16,10 @@ const reactIconsSprite = (options = {}) => {
 		transform(code, id) {
 			const cleanId = id.split("?", 1)[0];
 			if (!/\.(mjs|cjs|js|jsx|ts|tsx)$/.test(cleanId)) return null;
-			if (!/from\s+['"]react-icons\//.test(code)) return null;
 			try {
 				const { code: next, map, anyReplacements } = transformModule(code, id, (pack, exportName) => {
 					collector.add(pack, exportName);
-				});
+				}, DEFAULT_ICON_SOURCES);
 				if (!anyReplacements) return null;
 				return {
 					code: next,
@@ -35,14 +35,13 @@ const reactIconsSprite = (options = {}) => {
 			const generatedHash = createHash("sha256").update(spriteXml).digest("hex").slice(0, 8);
 			const emitFileOptions = {
 				type: "asset",
-				source: spriteXml
+				source: spriteXml,
+				fileName: fileName ? fileName : `react-icons-sprite-${generatedHash}.svg`
 			};
-			if (fileName) emitFileOptions.fileName = fileName;
-			else emitFileOptions.name = "react-icons-sprite.svg";
 			const assetId = this.emitFile(emitFileOptions);
-			const finalUrl = `/${this.getFileName(assetId)}?v=${encodeURIComponent(generatedHash)}`;
+			const finalUrl = `/${this.getFileName(assetId)}`;
 			for (const [, item] of Object.entries(bundle)) if (item.type === "chunk" && typeof item.code === "string") {
-				if (item.code.includes(PLACEHOLDER)) item.code = item.code.replaceAll(PLACEHOLDER, finalUrl);
+				if (item.code.includes(REACT_ICONS_SPRITE_URL_PLACEHOLDER)) item.code = item.code.replaceAll(REACT_ICONS_SPRITE_URL_PLACEHOLDER, finalUrl);
 			}
 		}
 	};

package/dist/webpack/loader.mjs

@@ -1,5 +1,5 @@
-import { i as transformModule } from "../core-CcX_8jJU.mjs";
-import { t as collector } from "../collector-CbA7qCnf.mjs";
+import { i as transformModule } from "../core-BoovxbBC.mjs";
+import { t as collector } from "../collector-DrPR8kXO.mjs";
 
 //#region src/webpack/loader.ts
 const reactIconsSpriteLoader = async function(source) {

package/dist/webpack/plugin.d.mts

@@ -4,7 +4,7 @@ import { Compiler, WebpackPluginInstance } from "webpack";
 type ReactIconsSpriteWebpackPluginOptions = {
   /**
    * If passed, this exact string will be used for the emitted file name.
-   * If fileName is omitted, name will be generated as `react-icons-sprite.svg`.
+   * If fileName is omitted, name will be generated as `react-icons-sprite-[hash].svg`.
    * This is useful when, for example, multiple sprite sheets are generated during client and server builds.
    */
   fileName?: string;

package/dist/webpack/plugin.mjs

@@ -1,5 +1,6 @@
-import { n as buildSprite, t as PLACEHOLDER } from "../core-CcX_8jJU.mjs";
-import { t as collector } from "../collector-CbA7qCnf.mjs";
+import { t as REACT_ICONS_SPRITE_URL_PLACEHOLDER } from "../src-Bf4uZBwp.mjs";
+import { n as buildSprite } from "../core-BoovxbBC.mjs";
+import { t as collector } from "../collector-DrPR8kXO.mjs";
 import { createHash } from "node:crypto";
 
 //#region src/webpack/plugin.ts
@@ -19,7 +20,7 @@ var ReactIconsSpriteWebpackPlugin = class {
 			}, async () => {
 				const spriteXml = await buildSprite(collector.toList());
 				const generatedHash = createHash("sha256").update(spriteXml).digest("hex").slice(0, 8);
-				const name = this.fileName ?? "react-icons-sprite.svg";
+				const name = this.fileName ?? `react-icons-sprite-${generatedHash}.svg`;
 				const RawSource = compiler.webpack?.sources?.RawSource;
 				if (!RawSource) throw new Error("[react-icons-sprite] Unable to access webpack RawSource");
 				compilation.emitAsset(name, new RawSource(spriteXml));
@@ -27,14 +28,14 @@ var ReactIconsSpriteWebpackPlugin = class {
 				let base = "";
 				if (typeof outputPublicPath === "string" && outputPublicPath !== "auto") base = outputPublicPath.endsWith("/") ? outputPublicPath : `${outputPublicPath}/`;
 				else base = "/";
-				const finalUrl = `${base}${name}?v=${encodeURIComponent(generatedHash)}`;
+				const finalUrl = `${base}${name}`;
 				for (const asset of compilation.getAssets()) {
 					const filename = asset.name;
 					if (!/\.(js|mjs|cjs)$/i.test(filename)) continue;
 					const src = asset.source.source();
 					if (typeof src !== "string") continue;
-					if (!src.includes(PLACEHOLDER)) continue;
-					const next = src.replaceAll(PLACEHOLDER, finalUrl);
+					if (!src.includes(REACT_ICONS_SPRITE_URL_PLACEHOLDER)) continue;
+					const next = src.replaceAll(REACT_ICONS_SPRITE_URL_PLACEHOLDER, finalUrl);
 					compilation.updateAsset(filename, new RawSource(next));
 				}
 			});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-icons-sprite",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "description": "",
@@ -11,9 +11,9 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/icon.d.mts",
-      "import": "./dist/icon.mjs",
-      "default": "./dist/icon.mjs"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
     },
     "./vite": {
       "types": "./dist/vite/plugin.d.mts",
@@ -29,11 +29,6 @@
       "types": "./dist/webpack/loader.d.mts",
       "import": "./dist/webpack/loader.mjs",
       "default": "./dist/webpack/loader.mjs"
-    },
-    "./turbopack": {
-      "types": "./dist/turbopack/plugin.d.mts",
-      "import": "./dist/turbopack/plugin.mjs",
-      "default": "./dist/turbopack/plugin.mjs"
     }
   },
   "publishConfig": {
@@ -52,9 +47,12 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "format": "biome format . --write",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint . --write",
+    "format": "biome format --no-errors-on-unmatched",
+    "format:fix": "biome format --write --no-errors-on-unmatched",
+    "lint": "biome lint  --no-errors-on-unmatched",
+    "lint:fix": "biome lint --write  --no-errors-on-unmatched",
+    "type-check": "tsgo",
+    "test": "vitest run",
     "prepublishOnly": "npm run build",
     "release": "npm publish --access public"
   },
@@ -68,18 +66,20 @@
     "@babel/parser": "7.28.5",
     "@babel/traverse": "7.28.5",
     "@babel/types": "7.28.5",
-    "@biomejs/biome": "2.3.5",
+    "@biomejs/biome": "2.3.8",
     "@types/babel__generator": "7.27.0",
     "@types/babel__traverse": "7.28.0",
-    "@types/node": "24.9.1",
+    "@types/node": "24.10.2",
     "@types/react-dom": "19.2.3",
-    "react": "19.2.0",
-    "react-dom": "19.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20251210.1",
+    "react": "19.2.1",
+    "react-dom": "19.2.1",
     "react-icons": "5.5.0",
-    "tsdown": "0.16.3",
+    "tsdown": "0.17.2",
     "typescript": "5.9.3",
-    "vite": "7.2.2",
-    "webpack": "5.102.1"
+    "vite": "7.2.7",
+    "vitest": "4.0.15",
+    "webpack": "5.103.0"
   },
   "keywords": [
     "vite",

package/dist/collector-CbA7qCnf.mjs

@@ -1,7 +0,0 @@
-import { r as createCollector } from "./core-CcX_8jJU.mjs";
-
-//#region src/collector.ts
-const collector = createCollector();
-
-//#endregion
-export { collector as t };