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

# React + Webpack 5

[← Back to home](../../README.md)

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

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

## 2. Create the sprite directory

```text
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

```ts
// 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:

```ts
// 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](reference.md#unified-configuration).

## 4. Add generation to package.json

```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:

```bash
npm run sprite:file-manager
```

## 5. Use the component

```tsx
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:

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

Types, rendering methods, and color controls are described in the [technical reference](reference.md#react-component-and-typescript).

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:

```tsx
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](next-app.md) and [Pages Router](next-pages.md) guides.