svg-sprites/docs/en/react-webpack.md

React + Webpack 5

← Back to home

A quick guide to installing and using SVG sprites in a React and Webpack 5 project.

The result is a typed React component and a separate SVG asset emitted through Webpack Asset Modules.

1. Install the package

npm install --save-dev @gromlab/svg-sprites

2. Create the sprite directory

src/ui/file-manager/svg-sprite/
├── icons/
│   ├── check.svg
│   └── folder.svg
├── index.ts
└── svg-sprite.config.ts

Place the source SVG files in icons/.

3. Add the configuration

// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
import { defineSpriteConfig } from '@gromlab/svg-sprites'

export default defineSpriteConfig({
  mode: 'react@webpack',
  name: 'file-manager',
  description: 'File manager icons',
})

The root barrel is application-owned and explicitly re-exports the generated API:

// src/ui/file-manager/svg-sprite/index.ts
export * from './.svg-sprite'

By default, SVG files are loaded from ./icons. You can add shared icons from other directories through inputFiles: the directory and file list are combined into a single sprite.

The complete list of options is available under Unified configuration.

4. Add generation to package.json

{
  "scripts": {
    "sprite:file-manager": "svg-sprites src/ui/file-manager/svg-sprite/svg-sprite.config.ts",
    "predev": "npm run sprite:file-manager",
    "prebuild": "npm run sprite:file-manager",
    "pretypecheck": "npm run sprite:file-manager"
  }
}

Generated files are excluded from Git, so generation must run before dev, build, and typecheck.

First run:

npm run sprite:file-manager

5. Use the component

import { FileManagerIcon } from './svg-sprite'

export const OpenFolderButton = () => (
  <button type="button">
    <FileManagerIcon icon="folder" width={24} height={24} />
    Open
  </button>
)

TypeScript checks the icon value against the file names:

<FileManagerIcon icon="folder" />  // valid
<FileManagerIcon icon="missing" /> // TypeScript error

Types, rendering methods, and color controls are described in the technical reference.

Webpack processes the generated new URL('./sprite.svg', import.meta.url) through Asset Modules and emits a separate SVG asset.

If the project already uses a custom SVG loader, make sure it does not intercept the generated sprite.svg instead of Asset Modules.

The generated component imports react/react-component.module.css, so Webpack must process CSS Modules through css-loader and style-loader or MiniCssExtractPlugin. If the TypeScript project does not include a declaration for CSS Modules, add one separately.

6. Add a debug page

Webpack does not support Vite's import.meta.glob API, so provide static loaders:

import { SpriteViewer } from '@gromlab/svg-sprites/react'

const sources = [
  () => import('./ui/file-manager/svg-sprite/.svg-sprite/svg-sprite.manifest.js'),
  () => import('./ui/navigation/svg-sprite/.svg-sprite/svg-sprite.manifest.js'),
]

export const IconsDebugPage = () => (
  <SpriteViewer sources={sources} title="Project icons" />
)

The paths in import() must be string literals. Webpack creates chunks for the manifests and associates them with the SVG assets.

Only include the Viewer on a debug route or in an internal tool.

Troubleshooting

• Missing .svg-sprite/index.js: run npm run sprite:file-manager.
• The Viewer does not load the sprite: check the import() path to .svg-sprite/svg-sprite.manifest.js.
• Incorrect asset URL: check output.publicPath.
• Another loader intercepts the SVG: exclude the generated sprite from the incompatible rule.

For Next.js, use the separate mode keys described in the App Router and Pages Router guides.