rspack-plugin-svg-sprite 1.3.0 → 1.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 Yichen Zhu
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -7,16 +7,25 @@
 [![npm version](https://img.shields.io/npm/v/rspack-plugin-svg-sprite)](https://www.npmjs.com/package/rspack-plugin-svg-sprite)
 [![npm downloads](https://img.shields.io/npm/dm/rspack-plugin-svg-sprite)](https://www.npmjs.com/package/rspack-plugin-svg-sprite)
 [![license](https://img.shields.io/github/license/yichenzhu1337/rspack-plugin-svg-sprite)](https://github.com/yichenzhu1337/rspack-plugin-svg-sprite/blob/main/LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/rspack-plugin-svg-sprite)](https://bundlephobia.com/package/rspack-plugin-svg-sprite)
 
-**[Live Demo](https://yichenzhu1337.github.io/rspack-plugin-svg-sprite/)**
+**[Live Demo](https://yichenzhu1337.github.io/rspack-plugin-svg-sprite/)** | **[npm](https://www.npmjs.com/package/rspack-plugin-svg-sprite)** | **[npm trends](https://npmtrends.com/rspack-plugin-svg-sprite-vs-svg-sprite-loader)**
+
+```bash
+npm install rspack-plugin-svg-sprite -D
+```
 
 ---
 
+## Why SVG sprites?
+
+Individual SVG files mean one HTTP request per icon — 50 icons = 50 requests. Inlining SVGs directly into JSX bloats your bundle with duplicated markup. SVG sprites solve both problems: all icons are combined into a single file (or a single hidden DOM element), and each icon is referenced by `<use href="#id" />` — one request, zero duplication, full CSS styling support, and resolution-independent rendering at any size.
+
 ## What is this?
 
 `rspack-plugin-svg-sprite` lets you import `.svg` files in your Rspack (or Webpack 5) project and automatically combine them into an SVG sprite sheet — either inlined in the DOM or extracted as an external `.svg` file.
 
-It was created because the popular [`svg-sprite-loader`](https://github.com/JetBrains/svg-sprite-loader) depends on internal Webpack APIs (`NormalModule.getCompilationHooks`, `compilation.hooks.additionalAssets`, etc.) that do not exist in Rspack. This package reimplements the same functionality using Rspack-compatible APIs while keeping the exact same exported symbol shape (`id`, `viewBox`, `url`, `content`), so your existing component code works without changes.
+It was created because the popular [`svg-sprite-loader`](https://github.com/JetBrains/svg-sprite-loader) depends on internal Webpack APIs (`NormalModule.getCompilationHooks`, `compilation.hooks.additionalAssets`, etc.) that do not exist in Rspack ([rspack#11609](https://github.com/web-infra-dev/rspack/issues/11609)). This package reimplements the same functionality using Rspack-compatible APIs while keeping the exact same exported symbol shape (`id`, `viewBox`, `url`, `content`), so your existing component code works without changes.
 
 ## Features
 
@@ -34,6 +43,10 @@ It was created because the popular [`svg-sprite-loader`](https://github.com/JetB
 
 ```bash
 npm install rspack-plugin-svg-sprite -D
+# or
+pnpm add rspack-plugin-svg-sprite -D
+# or
+yarn add rspack-plugin-svg-sprite -D
 ```
 
 ### Configure (inline mode)
@@ -74,6 +87,42 @@ import logo from './logo.svg';
 
 That's it. Every imported SVG is automatically registered as a `<symbol>` in a hidden sprite and referenced by `#id`.
 
+### TypeScript
+
+This package ships with a client type declaration. Add it to your `tsconfig.json` so `import icon from './icon.svg'` is fully typed:
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["rspack-plugin-svg-sprite/client"],
+  },
+}
+```
+
+This gives you autocompletion for `id`, `viewBox`, `url`, and `content` on every SVG import.
+
+<details>
+<summary>Alternative: manual declaration file</summary>
+
+If you prefer, create a `svg.d.ts` file instead:
+
+```ts
+declare module '*.svg' {
+  const symbol: {
+    id: string;
+    viewBox: string;
+    url: string;
+    content: string;
+  };
+  export default symbol;
+}
+```
+
+Make sure this file is included by your `tsconfig.json` (e.g., in the `include` array or alongside your source files).
+
+</details>
+
 ## Extract Mode
 
 To emit SVGs as an external `.svg` sprite file instead of inlining them, enable extract mode and add the plugin:
@@ -151,6 +200,86 @@ Every `import icon from './icon.svg'` returns an object with:
 
 This matches `svg-sprite-loader`'s export shape exactly, so migrating requires no component changes.
 
+## Rsbuild Integration
+
+If you're using [Rsbuild](https://rsbuild.dev/), use the built-in Rsbuild plugin for one-line setup:
+
+```js
+// rsbuild.config.js
+const { pluginSvgSprite } = require('rspack-plugin-svg-sprite/rsbuild');
+
+module.exports = {
+  plugins: [
+    pluginSvgSprite({
+      symbolId: 'icon-[name]',
+      extract: true,
+      spriteFilename: 'sprites/icons.svg',
+    }),
+  ],
+};
+```
+
+The Rsbuild plugin handles the loader rule, `type: 'javascript/auto'`, and the `SvgSpritePlugin` automatically.
+
+## Framework Recipes
+
+### Next.js (with next-rspack)
+
+```js
+// next.config.js
+const { SvgSpritePlugin } = require('rspack-plugin-svg-sprite');
+
+module.exports = {
+  webpack(config) {
+    // Remove Next.js default SVG handling
+    const fileLoaderRule = config.module.rules.find((rule) => rule.test?.test?.('.svg'));
+    if (fileLoaderRule) fileLoaderRule.exclude = /\.svg$/;
+
+    config.module.rules.push({
+      test: /\.svg$/,
+      type: 'javascript/auto',
+      loader: 'rspack-plugin-svg-sprite/loader',
+      options: { symbolId: 'icon-[name]', extract: true },
+    });
+
+    config.plugins.push(new SvgSpritePlugin({ plainSprite: true }));
+    return config;
+  },
+};
+```
+
+### Vue + Rspack
+
+```js
+// rspack.config.js
+const { SvgSpritePlugin } = require('rspack-plugin-svg-sprite');
+
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.svg$/,
+        type: 'javascript/auto',
+        loader: 'rspack-plugin-svg-sprite/loader',
+        options: { symbolId: '[name]' },
+      },
+    ],
+  },
+};
+```
+
+```vue
+<template>
+  <svg :viewBox="icon.viewBox">
+    <use :href="icon.url" />
+  </svg>
+</template>
+
+<script setup>
+import icon from './icon.svg';
+</script>
+```
+
 ## Migrating from svg-sprite-loader
 
 ```diff
@@ -236,6 +365,25 @@ module.exports = {
 2. During Rspack's `processAssets` stage, the plugin collects all registered symbols and emits a combined `.svg` sprite file.
 3. The exported JS module contains the external file URL (e.g., `/sprites/icons.svg#symbolId`).
 
+## Alternatives & Comparison
+
+Looking for the right SVG solution for Rspack? Here's how the options compare:
+
+| Feature               | rspack-plugin-svg-sprite | svg-sprite-loader           | @svgr/webpack    | @rsbuild/plugin-svgr | vite-plugin-svg-icons |
+| --------------------- | ------------------------ | --------------------------- | ---------------- | -------------------- | --------------------- |
+| **Rspack support**    | Native                   | No (uses Webpack internals) | Via config       | Rsbuild only         | No (Vite only)        |
+| **Approach**          | SVG sprites (`<use>`)    | SVG sprites (`<use>`)       | React components | React components     | SVG sprites           |
+| **Inline mode**       | Yes                      | Yes                         | N/A              | N/A                  | Yes                   |
+| **Extract mode**      | Yes                      | Yes                         | N/A              | N/A                  | No                    |
+| **Webpack 5 support** | Yes                      | Yes                         | Yes              | No                   | No                    |
+| **Runtime deps**      | Zero                     | 1                           | Several          | Several              | Several               |
+| **Maintained**        | Yes                      | No (archived)               | Yes              | Yes                  | Yes                   |
+| **Drop-in migration** | —                        | Yes (same API)              | Different API    | Different API        | Different API         |
+
+**When to use SVG sprites** (this plugin): You want icons combined into a single file with `<use href="#id">` references — optimal for large icon sets, full CSS styling control, and caching. Best when migrating from `svg-sprite-loader`.
+
+**When to use SVGR**: You want each SVG as a React component with props for color, size, etc. Better for SVGs that need dynamic manipulation via React props rather than CSS.
+
 ## Compatibility
 
 | Bundler                            | Version  | Status                                   |

package/client.d.ts

@@ -0,0 +1,13 @@
+declare module '*.svg' {
+  const symbol: {
+    /** The symbol ID inside the sprite (e.g., "icon-home") */
+    id: string;
+    /** The original SVG viewBox attribute (e.g., "0 0 24 24") */
+    viewBox: string;
+    /** Fragment reference (inline: "#icon-home") or full URL (extract: "/sprites/icons.svg#icon-home") */
+    url: string;
+    /** Raw `<symbol>` markup */
+    content: string;
+  };
+  export default symbol;
+}

package/dist/rsbuild.d.ts

@@ -0,0 +1,12 @@
+import type { RsbuildPlugin } from '@rsbuild/core';
+export interface SvgSpritePluginOptions {
+    symbolId?: string | ((resourcePath: string) => string);
+    extract?: boolean;
+    esModule?: boolean;
+    spriteFilename?: string;
+    publicPath?: string;
+    plainSprite?: boolean;
+    spriteAttrs?: Record<string, string>;
+}
+export declare function pluginSvgSprite(options?: SvgSpritePluginOptions): RsbuildPlugin;
+//# sourceMappingURL=rsbuild.d.ts.map

package/dist/rsbuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsbuild.d.ts","sourceRoot":"","sources":["../src/rsbuild.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,aAAa,CA6BnF"}

package/dist/rsbuild.js

@@ -0,0 +1,70 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginSvgSprite = pluginSvgSprite;
+const path = __importStar(require("path"));
+const plugin_1 = __importDefault(require("./plugin"));
+function pluginSvgSprite(options = {}) {
+    const { plainSprite, spriteAttrs, ...loaderOptions } = options;
+    return {
+        name: 'rsbuild-plugin-svg-sprite',
+        setup(api) {
+            api.modifyRspackConfig((config) => {
+                config.module = config.module || {};
+                config.module.rules = config.module.rules || [];
+                config.module.rules.push({
+                    test: /\.svg$/,
+                    type: 'javascript/auto',
+                    loader: path.join(__dirname, 'loader.js'),
+                    options: {
+                        symbolId: loaderOptions.symbolId || '[name]',
+                        extract: loaderOptions.extract || false,
+                        esModule: loaderOptions.esModule !== false,
+                        spriteFilename: loaderOptions.spriteFilename || 'sprite.svg',
+                        publicPath: loaderOptions.publicPath || '',
+                    },
+                });
+                if (loaderOptions.extract) {
+                    config.plugins = config.plugins || [];
+                    config.plugins.push(new plugin_1.default({ plainSprite, spriteAttrs }));
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=rsbuild.js.map

package/dist/rsbuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsbuild.js","sourceRoot":"","sources":["../src/rsbuild.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcA,0CA6BC;AA3CD,2CAA6B;AAE7B,sDAAuC;AAYvC,SAAgB,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAE/D,OAAO;QACL,IAAI,EAAE,2BAA2B;QACjC,KAAK,CAAC,GAAG;YACP,GAAG,CAAC,kBAAkB,CAAC,CAAC,MAAM,EAAE,EAAE;gBAChC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;gBACpC,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;gBAChD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;oBACvB,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,iBAA0B;oBAChC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC;oBACzC,OAAO,EAAE;wBACP,QAAQ,EAAE,aAAa,CAAC,QAAQ,IAAI,QAAQ;wBAC5C,OAAO,EAAE,aAAa,CAAC,OAAO,IAAI,KAAK;wBACvC,QAAQ,EAAE,aAAa,CAAC,QAAQ,KAAK,KAAK;wBAC1C,cAAc,EAAE,aAAa,CAAC,cAAc,IAAI,YAAY;wBAC5D,UAAU,EAAE,aAAa,CAAC,UAAU,IAAI,EAAE;qBAC3C;iBACF,CAAC,CAAC;gBAEH,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;oBAC1B,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;oBACtC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,gBAAe,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rspack-plugin-svg-sprite",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SVG sprite loader and plugin for Rspack — drop-in replacement for svg-sprite-loader with inline and extract mode support",
   "author": "Yichen Zhu",
   "license": "MIT",
@@ -16,20 +16,29 @@
     "rspack",
     "rspack-plugin",
     "rspack-loader",
+    "rsbuild",
+    "rsbuild-plugin",
     "svg",
     "svg-sprite",
     "svg-sprite-loader",
     "svg-icon",
+    "svg-icons",
     "sprite",
     "sprite-sheet",
     "icon",
+    "icon-system",
     "loader",
     "plugin",
+    "bundler-plugin",
     "webpack",
     "webpack5",
     "extract",
     "inline",
-    "symbol"
+    "symbol",
+    "react",
+    "vue",
+    "migration",
+    "drop-in"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -53,10 +62,18 @@
     "./runtime/symbol": {
       "types": "./dist/runtime/symbol.d.ts",
       "default": "./dist/runtime/symbol.js"
+    },
+    "./rsbuild": {
+      "types": "./dist/rsbuild.d.ts",
+      "default": "./dist/rsbuild.js"
+    },
+    "./client": {
+      "types": "./client.d.ts"
     }
   },
   "files": [
     "dist/",
+    "client.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -75,11 +92,15 @@
     "prepare": "husky"
   },
   "peerDependencies": {
-    "@rspack/core": ">=0.5.0"
+    "@rspack/core": ">=0.5.0",
+    "@rsbuild/core": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "@rspack/core": {
       "optional": true
+    },
+    "@rsbuild/core": {
+      "optional": true
     }
   },
   "devDependencies": {