diff --git a/README.md b/README.md
index ab4a13a..22f9bcb 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# @gromlab/svg-sprites
-🇬🇧 English | [🇷🇺 Русский](README_RU.md)
+🇬🇧 English | [🇷🇺 Русский](https://github.com/gromlab-ru/svg-sprites/blob/master/README_RU.md)
 
@@ -24,20 +24,6 @@ The component accepts familiar SVG attributes: dimensions, `color`, `className`,
You do not have to work with the sprite directly in your application. Use it like a regular SVG icon while benefiting from a single component, autocomplete, and TypeScript validation for every name.
-In `standalone@vite` and `standalone@webpack`, the same approach works without React:
-
-```ts
-import { defineAppIconElement } from './app-icons'
-
-defineAppIconElement()
-```
-
-```html
-
-```
-
-Bare `standalone` remains minimal and generates only an SVG asset and JSON manifest, with no JavaScript runtime.
-
## AI-friendly out of the box
`@gromlab/svg-sprites` is designed to work with AI agents from the start. Add the ready-made skill and ask an agent to configure, migrate, or troubleshoot the package without lengthy instructions or manual documentation research.
@@ -46,62 +32,55 @@ Bare `standalone` remains minimal and generates only an SVG asset and JSON manif
[🇷🇺 Download AI skill (Russian)](https://github.com/gromlab-ru/svg-sprites/releases/latest/download/svg-sprites-ru.zip)
-## From SVG to component in four steps
+## From SVG to component in three steps
The main example uses the Next.js App Router and Turbopack.
-### 1. Generate without installing the package
+### 1. Specify the icons you need
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites --help
-```
-
-`npx` downloads the CLI temporarily. It does not add `@gromlab/svg-sprites` to
-`package.json`, and the generated production runtime does not import the package.
-
-### 2. Specify the icons you need
-
-SVG files can remain in your project's existing structure:
+Create directories for the source icons and the sprite:
```text
-src/
-├── assets/icons/
-│ ├── search.svg
-│ └── settings.svg
-├── features/profile/
-│ └── user.svg
-└── ui/app-icons/
- └── svg-sprite.config.ts
+assets/
+├── app-icons/
+│ └── svg-sprite.config.json
+└── svg-icons/
+ ├── search.svg
+ └── settings.svg
```
Create the sprite configuration:
-```ts
-// src/ui/app-icons/svg-sprite.config.ts
-export default {
- mode: 'next@app/turbopack',
- name: 'app',
- input: [
- '../../assets/icons/search.svg',
- '../../assets/icons/settings.svg',
- '../../features/profile/user.svg',
- ],
+```json
+{
+ "mode": "next@app/turbopack",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-### 3. Add generation
+`input` supports directory paths, individual SVG files, and glob patterns.
+
+### 2. Add a generation script
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/app-icons/svg-sprite.config.ts",
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
"predev": "npm run sprites",
"prebuild": "npm run sprites"
}
}
```
-Run it for the first time:
+Create an entry point for the generated API:
+
+```ts
+// assets/app-icons/index.ts
+export * from './.svg-sprite/index.js'
+```
+
+First run:
```bash
npm run sprites
@@ -109,10 +88,11 @@ npm run sprites
The package will generate `AppIcon`, TypeScript types, and a separate SVG sprite.
-### 4. Use it like a regular icon
+### 3. Use it like a regular icon
```tsx
-import { AppIcon } from '@/ui/app-icons'
+// app/page.tsx
+import { AppIcon } from '../assets/app-icons'
export default function SearchButton() {
return (
@@ -240,7 +220,7 @@ It also provides ready-to-use integration examples for:
The Viewer is added only to an internal debug page and does not become part of the generated icon components.
-Bare standalone loads the Viewer as a browser script and HTML element; bundler modes use the npm entry, while React and Next.js import `SpriteViewer` from `@gromlab/svg-sprites/react`.
+With bare standalone, the application loads the Viewer as a browser script and HTML element; bundler modes use the npm entry, while React and Next.js import `SpriteViewer` from `@gromlab/svg-sprites/react`.
## Standalone, React, and Next.js
@@ -277,6 +257,7 @@ This README introduces the project's capabilities and demonstrates the primary u
### Technical resources
- [Documentation index](docs/en/README.md)
+- [Configuration](docs/en/configuration.md)
- [Technical reference](docs/en/reference/technical.md)
- [Programmatic API](docs/en/reference/programmatic-api.md)
diff --git a/docs/en/README.md b/docs/en/README.md
index 23519ca..4adf85e 100644
--- a/docs/en/README.md
+++ b/docs/en/README.md
@@ -3,6 +3,8 @@
Choose one exact mode guide for setup. The guides are standalone documents and
can also be used unchanged by AI skills.
+The common format for JSON, JavaScript, and TypeScript config files is described in the [configuration guide](configuration.md).
+
## Quick Start Guides
| Project | Exact mode | Guide |
@@ -20,10 +22,11 @@ can also be used unchanged by AI skills.
Every guide follows the same order:
1. Generate the sprite through `npx` without adding the package to the project.
-2. Optionally install and connect the debug Viewer.
-3. Optionally type the config through the package or a local copy-paste type.
+2. Use the sprite in the application.
+3. Optionally add the Viewer for debugging and previews.
## Reference
+- [Configuration](configuration.md)
- [Technical reference](reference/technical.md)
- [Programmatic API](reference/programmatic-api.md)
diff --git a/docs/en/configuration.md b/docs/en/configuration.md
new file mode 100644
index 0000000..1c4e847
--- /dev/null
+++ b/docs/en/configuration.md
@@ -0,0 +1,99 @@
+# Configuration
+
+Each config file describes one independent sprite. The CLI does not discover config files automatically, so always pass the path explicitly:
+
+```bash
+npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.json
+```
+
+## JSON
+
+JSON works for most projects and does not require installing the package locally:
+
+```json
+{
+ "mode": "next@app/turbopack",
+ "name": "app",
+ "description": "Shared application icons",
+ "input": [
+ "./icons",
+ "../../assets/icons/**/*.svg",
+ "!../../assets/icons/deprecated-*.svg"
+ ],
+ "transform": {
+ "removeSize": true,
+ "replaceColors": true,
+ "addTransition": true
+ },
+ "generatedNotice": true
+}
+```
+
+| Field | Default | Purpose |
+|---|---|---|
+| `mode` | None | Exact mode matching the framework and bundler |
+| `name` | Kebab-case module directory name; for `svg-sprite` and `svg-sprites`, the parent directory name | Sprite name; in modes with a component, it also determines the component and type names |
+| `description` | None | Description used in types and the Viewer |
+| `input` | `./icons` | Directory, SVG file, glob pattern, or array of sources |
+| `transform` | All enabled | SVG preparation options |
+| `generatedNotice` | `true` | Full or compact warning in generated files |
+
+Paths and glob patterns in `input` are resolved relative to the config file's directory. A pattern prefixed with `!` excludes matches.
+
+## JavaScript
+
+A JavaScript config default-exports a plain object:
+
+```js
+export default {
+ mode: 'react@vite',
+ name: 'icons',
+ input: './icons',
+}
+```
+
+Pass the path to the `.js` file to the CLI just like a JSON file:
+
+```bash
+npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.js
+```
+
+## TypeScript
+
+To type-check a TypeScript config, install the package as a development dependency:
+
+```bash
+npm install --save-dev @gromlab/svg-sprites
+```
+
+Use `defineSpriteConfig`:
+
+```ts
+import { defineSpriteConfig } from '@gromlab/svg-sprites'
+
+export default defineSpriteConfig({
+ mode: 'react@vite',
+ name: 'icons',
+ input: './icons',
+})
+```
+
+Alternatively, use `satisfies` with a type-only import:
+
+```ts
+import type { SpriteConfig } from '@gromlab/svg-sprites'
+
+export default {
+ mode: 'react@vite',
+ name: 'icons',
+ input: './icons',
+} satisfies SpriteConfig
+```
+
+The CLI loads `.ts` config files directly:
+
+```bash
+npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.ts
+```
+
+For the complete list of modes, CLI flags, naming rules, and transform options, see the [technical reference](reference/technical.md).
diff --git a/docs/en/guides/next-app-turbopack.md b/docs/en/guides/next-app-turbopack.md
index aaef31a..964be0b 100644
--- a/docs/en/guides/next-app-turbopack.md
+++ b/docs/en/guides/next-app-turbopack.md
@@ -1,153 +1,108 @@
-# Next.js App Router Turbopack SVG Sprite Quick Start
+# SVG Sprite for Next.js App Router with Turbopack
-This guide targets the exact mode key `next@app/turbopack`: a generated typed React icon for the Next.js App Router and Turbopack.
+A quick guide to creating an SVG sprite in a Next.js application using App Router and Turbopack.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config and source icons together:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'next@app/turbopack',
- name: 'icons',
+```json
+{
+ "mode": "next@app/turbopack",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Generate once per invocation and keep the exact Turbopack flags on both commands:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && next dev --turbopack",
- "build": "npm run sprites && next build --turbopack"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "next dev --turbopack",
+ "prebuild": "npm run sprites",
+ "build": "next build --turbopack"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. Generated declarations are self-contained and do not require the package.
+The value `name: "app"` creates the React component `AppIcon`.
-### Production usage
+Create the entry point `assets/app-icons/index.ts`:
-The generated icon has no `'use client'` directive and is Server Component-compatible. Import it directly in an App Router page or layout:
+```ts
+export * from './.svg-sprite/index.js'
+```
+
+Use the component in a Server Component:
```tsx
-// src/app/page.tsx
-import {
- IconsIcon,
- iconsIconNames,
-} from '../ui/icons/.svg-sprite/index.js'
+// app/page.tsx
+import { AppIcon } from '../assets/app-icons'
export default function Page() {
return (
-
-
-
{iconsIconNames.length} icons available
-
+
)
}
```
-Turbopack resolves the generated `new URL('../sprite.svg', import.meta.url)` and CSS Module, emitting a separate SVG asset. Keep the mode and the `--turbopack` dev/build flags aligned.
+`AppIcon` does not need `'use client'`. Turbopack automatically adds `sprite.svg` to the production build, so you do not need to move it to `public`.
-## 2. Debug and preview
+## Debug and preview
-This section is optional. Only users who need the Viewer or icon previews should install:
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Viewer is interactive, so place the React bridge in a separate Client Component:
+Create the Client Component `app/svg-sprite/SvgSpriteViewer.tsx`:
```tsx
-// src/app/icon-debug/IconsViewer.tsx
'use client'
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
- () => import('../../ui/icons/.svg-sprite/svg-sprite.manifest.js'),
-]
+ () => import('../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
+] as const
-export function IconsViewer() {
+export function SvgSpriteViewer() {
return
}
```
-Render it from the route's Server Component:
+Create the route `app/svg-sprite/page.tsx`:
```tsx
-// src/app/icon-debug/page.tsx
-import { IconsViewer } from './IconsViewer'
+import { notFound } from 'next/navigation'
-export default function IconDebugPage() {
- return
+import { SvgSpriteViewer } from './SvgSpriteViewer'
+
+export default function SvgSpritePage() {
+ if (process.env.NODE_ENV !== 'development') notFound()
+
+ return
}
```
-Keep the route internal or development-only. Viewer is not part of the production icon runtime.
-
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'next@app/turbopack',
- name: 'icons',
-})
-```
-
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
-
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'next@app/turbopack'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'next@app/turbopack',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+Run `npm run dev` and open `/svg-sprite`. In production, the route returns 404.
diff --git a/docs/en/guides/next-app-webpack.md b/docs/en/guides/next-app-webpack.md
index 08ac234..c2b91b6 100644
--- a/docs/en/guides/next-app-webpack.md
+++ b/docs/en/guides/next-app-webpack.md
@@ -1,153 +1,108 @@
-# Next.js App Router Webpack SVG Sprite Quick Start
+# SVG Sprite for Next.js App Router with Webpack
-This guide targets the exact mode key `next@app/webpack`: a generated typed React icon for the Next.js App Router and Webpack 5.
+A quick guide to creating an SVG sprite in a Next.js application using App Router and Webpack.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config adjacent to its source icons:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'next@app/webpack',
- name: 'icons',
+```json
+{
+ "mode": "next@app/webpack",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Generate once per invocation and keep the exact Webpack flags on both commands:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && next dev --webpack",
- "build": "npm run sprites && next build --webpack"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "next dev --webpack",
+ "prebuild": "npm run sprites",
+ "build": "next build --webpack"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. Generated declarations are self-contained and do not require the package.
+The value `name: "app"` creates the React component `AppIcon`.
-### Production usage
+Create the entry point `assets/app-icons/index.ts`:
-The generated icon has no `'use client'` directive and is Server Component-compatible. Import it directly in an App Router page or layout:
+```ts
+export * from './.svg-sprite/index.js'
+```
+
+Use the component in a Server Component:
```tsx
-// src/app/page.tsx
-import {
- IconsIcon,
- iconsIconNames,
-} from '../ui/icons/.svg-sprite/index.js'
+// app/page.tsx
+import { AppIcon } from '../assets/app-icons'
export default function Page() {
return (
-
-
-
{iconsIconNames.length} icons available
-
+
)
}
```
-Webpack resolves the generated `new URL('../sprite.svg', import.meta.url)` and CSS Module, emitting a separate SVG asset. Keep the mode and the `--webpack` dev/build flags aligned. If custom Next.js webpack rules process SVG through SVGR, exclude `.svg-sprite/sprite.svg` from those rules.
+`AppIcon` does not need `'use client'`. Next.js automatically adds `sprite.svg` to the production build, so you do not need to move it to `public`.
-## 2. Debug and preview
+## Debug and preview
-This section is optional. Only users who need the Viewer or icon previews should install:
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Viewer is interactive, so place the React bridge in a separate Client Component:
+Create the Client Component `app/svg-sprite/SvgSpriteViewer.tsx`:
```tsx
-// src/app/icon-debug/IconsViewer.tsx
'use client'
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
- () => import('../../ui/icons/.svg-sprite/svg-sprite.manifest.js'),
-]
+ () => import('../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
+] as const
-export function IconsViewer() {
+export function SvgSpriteViewer() {
return
}
```
-Render it from the route's Server Component:
+Create the route `app/svg-sprite/page.tsx`:
```tsx
-// src/app/icon-debug/page.tsx
-import { IconsViewer } from './IconsViewer'
+import { notFound } from 'next/navigation'
-export default function IconDebugPage() {
- return
+import { SvgSpriteViewer } from './SvgSpriteViewer'
+
+export default function SvgSpritePage() {
+ if (process.env.NODE_ENV !== 'development') notFound()
+
+ return
}
```
-Keep the route internal or development-only. Viewer is not part of the production icon runtime.
-
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'next@app/webpack',
- name: 'icons',
-})
-```
-
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
-
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'next@app/webpack'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'next@app/webpack',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+Run `npm run dev` and open `/svg-sprite`. In production, the route returns 404.
diff --git a/docs/en/guides/next-pages-turbopack.md b/docs/en/guides/next-pages-turbopack.md
index a1e53d3..3f0163b 100644
--- a/docs/en/guides/next-pages-turbopack.md
+++ b/docs/en/guides/next-pages-turbopack.md
@@ -1,140 +1,98 @@
-# Next.js Pages Router Turbopack SVG Sprite Quick Start
+# SVG Sprite for Next.js Pages Router with Turbopack
-This guide targets the exact mode key `next@pages/turbopack`: a generated typed React icon for the Next.js Pages Router and Turbopack.
+A quick guide to creating an SVG sprite in a Next.js application using Pages Router and Turbopack.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config and source icons together:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'next@pages/turbopack',
- name: 'icons',
+```json
+{
+ "mode": "next@pages/turbopack",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Generate once per invocation and keep the exact Turbopack flags on both commands:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && next dev --turbopack",
- "build": "npm run sprites && next build --turbopack"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "next dev --turbopack",
+ "prebuild": "npm run sprites",
+ "build": "next build --turbopack"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. Generated declarations are self-contained and do not require the package.
+The value `name: "app"` creates the React component `AppIcon`.
-### Production usage
+Create the entry point `assets/app-icons/index.ts`:
-Import the generated component and icon-name list into a Pages Router page:
+```ts
+export * from './.svg-sprite/index.js'
+```
+
+Use the component on a page:
```tsx
-// src/pages/index.tsx
-import {
- IconsIcon,
- iconsIconNames,
-} from '../ui/icons/.svg-sprite/index.js'
+// pages/index.tsx
+import { AppIcon } from '../assets/app-icons'
-export default function HomePage() {
+export default function Page() {
return (
-
-
-
{iconsIconNames.length} icons available
-
+
)
}
```
-The component works with SSR, SSG, and client-side navigation. Turbopack resolves the generated SVG URL and CSS Module and emits a separate asset. Keep the mode and the `--turbopack` dev/build flags aligned.
+The component works with SSR, SSG, and client-side navigation. Turbopack automatically adds `sprite.svg` to the production build, so you do not need to move it to `public`.
-## 2. Debug and preview
+## Debug and preview
-This section is optional. Only users who need the Viewer or icon previews should install:
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Pages Router does not require an App Router Client Component boundary. Use the React bridge directly in a page with a static loader array:
+Create the page `pages/svg-sprite.tsx`:
```tsx
-// src/pages/icon-debug.tsx
+import type { GetStaticProps } from 'next'
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
- () => import('../ui/icons/.svg-sprite/svg-sprite.manifest.js'),
-]
+ () => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
+] as const
-export default function IconDebugPage() {
+export default function SvgSpritePage() {
return
}
+
+export const getStaticProps: GetStaticProps = () =>
+ process.env.NODE_ENV === 'development'
+ ? { props: {} }
+ : { notFound: true }
```
-Keep the page internal or development-only. Viewer is not part of the production icon runtime.
-
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'next@pages/turbopack',
- name: 'icons',
-})
-```
-
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
-
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'next@pages/turbopack'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'next@pages/turbopack',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+Run `npm run dev` and open `/svg-sprite`. In production, the route returns 404.
diff --git a/docs/en/guides/next-pages-webpack.md b/docs/en/guides/next-pages-webpack.md
index 32a97b2..5c19d93 100644
--- a/docs/en/guides/next-pages-webpack.md
+++ b/docs/en/guides/next-pages-webpack.md
@@ -1,140 +1,98 @@
-# Next.js Pages Router Webpack SVG Sprite Quick Start
+# SVG Sprite for Next.js Pages Router with Webpack
-This guide targets the exact mode key `next@pages/webpack`: a generated typed React icon for the Next.js Pages Router and Webpack 5.
+A quick guide to creating an SVG sprite in a Next.js application using Pages Router and Webpack.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config adjacent to its source icons:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'next@pages/webpack',
- name: 'icons',
+```json
+{
+ "mode": "next@pages/webpack",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Generate once per invocation and keep the exact Webpack flags on both commands:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && next dev --webpack",
- "build": "npm run sprites && next build --webpack"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "next dev --webpack",
+ "prebuild": "npm run sprites",
+ "build": "next build --webpack"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. Generated declarations are self-contained and do not require the package.
+The value `name: "app"` creates the React component `AppIcon`.
-### Production usage
+Create the entry point `assets/app-icons/index.ts`:
-Import the generated component and icon-name list into a Pages Router page:
+```ts
+export * from './.svg-sprite/index.js'
+```
+
+Use the component on a page:
```tsx
-// src/pages/index.tsx
-import {
- IconsIcon,
- iconsIconNames,
-} from '../ui/icons/.svg-sprite/index.js'
+// pages/index.tsx
+import { AppIcon } from '../assets/app-icons'
-export default function HomePage() {
+export default function Page() {
return (
-
-
-
{iconsIconNames.length} icons available
-
+
)
}
```
-The component works with SSR, SSG, and client-side navigation. Webpack resolves the generated SVG URL and CSS Module and emits a separate asset. Keep the mode and the `--webpack` dev/build flags aligned. If custom Next.js webpack rules process SVG through SVGR, exclude `.svg-sprite/sprite.svg` from those rules.
+The component works with SSR, SSG, and client-side navigation. Next.js automatically adds `sprite.svg` to the production build, so you do not need to move it to `public`.
-## 2. Debug and preview
+## Debug and preview
-This section is optional. Only users who need the Viewer or icon previews should install:
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Pages Router does not require an App Router Client Component boundary. Use the React bridge directly in a page with a static loader array:
+Create the page `pages/svg-sprite.tsx`:
```tsx
-// src/pages/icon-debug.tsx
+import type { GetStaticProps } from 'next'
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
- () => import('../ui/icons/.svg-sprite/svg-sprite.manifest.js'),
-]
+ () => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
+] as const
-export default function IconDebugPage() {
+export default function SvgSpritePage() {
return
}
+
+export const getStaticProps: GetStaticProps = () =>
+ process.env.NODE_ENV === 'development'
+ ? { props: {} }
+ : { notFound: true }
```
-Keep the page internal or development-only. Viewer is not part of the production icon runtime.
-
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'next@pages/webpack',
- name: 'icons',
-})
-```
-
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
-
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'next@pages/webpack'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'next@pages/webpack',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+Run `npm run dev` and open `/svg-sprite`. In production, the route returns 404.
diff --git a/docs/en/guides/react-vite.md b/docs/en/guides/react-vite.md
index 96ed9ea..d51cf11 100644
--- a/docs/en/guides/react-vite.md
+++ b/docs/en/guides/react-vite.md
@@ -1,148 +1,115 @@
-# React Vite SVG Sprite Quick Start
+# SVG Sprite for React with Vite
-This guide targets the exact mode key `react@vite`: a generated typed React component with a Vite-managed SVG asset.
+A quick guide to creating an SVG sprite in a React application built with Vite.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config and source icons together:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'react@vite',
- name: 'icons',
+```json
+{
+ "mode": "react@vite",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Use the exact Vite dev/build commands and generate once per invocation:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && vite",
- "build": "npm run sprites && tsc --noEmit && vite build"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "vite",
+ "prebuild": "npm run sprites",
+ "build": "tsc --noEmit && vite build"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. Generated declarations are self-contained and do not require the package.
+The value `name: "app"` creates the React component `AppIcon`.
-### Production usage
+Create the entry point `assets/app-icons/index.ts`:
-Import the generated component and icon-name list directly:
+```ts
+export * from './.svg-sprite/index.js'
+```
+
+Use the component in your application:
```tsx
-// src/App.tsx
-import {
- IconsIcon,
- iconsIconNames,
-} from './ui/icons/.svg-sprite/index.js'
+import { AppIcon } from '../assets/app-icons'
-export function App() {
+export function SaveIcon() {
return (
-
-
- {iconsIconNames.length} icons available
-
+
)
}
```
-`icon` is a generated union of SVG file names. Vite automatically handles the generated CSS Module and the `sprite.svg?no-inline` import, emitting the sprite as a separate asset. If your own TypeScript source imports Vite query assets, include Vite's ambient types:
+The `icon` prop accepts source SVG file names without the extension. A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`.
-```json
-{
- "compilerOptions": {
- "types": ["vite/client"]
- }
-}
-```
+Vite automatically includes the component styles and adds `sprite.svg` to the production build.
-## 2. Debug and preview
+## Debug and preview
-This section is optional. Only users who need the Viewer or icon previews should install:
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Use the React `SpriteViewer` bridge with a static loader array. Keep every `import()` path a string literal:
+Create `svg-sprite.html` in the project root:
+
+```html
+
+
+
+
+ Project icons
+
+
+
+
+
+
+
+
+
+```
+
+Create `src/svg-sprite-debug.tsx`:
```tsx
-// src/IconsDebugPage.tsx
+import { createRoot } from 'react-dom/client'
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
- () => import('./ui/icons/.svg-sprite/svg-sprite.manifest.js'),
-]
+ () => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
+] as const
-export function IconsDebugPage() {
- return
-}
+createRoot(document.getElementById('svg-sprite-viewer')!).render(
+ ,
+)
```
-Keep this component on a debug route or in an internal tool. Viewer is not part of the production icon runtime.
+Run `npm run dev` and open `/svg-sprite.html`.
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'react@vite',
- name: 'icons',
-})
-```
-
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
-
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'react@vite'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'react@vite',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+The standard Vite production build uses only `index.html` and does not include the Viewer page.
diff --git a/docs/en/guides/react-webpack.md b/docs/en/guides/react-webpack.md
index 31a83fd..9153adb 100644
--- a/docs/en/guides/react-webpack.md
+++ b/docs/en/guides/react-webpack.md
@@ -1,156 +1,132 @@
-# React Webpack SVG Sprite Quick Start
+# SVG Sprite for React with Webpack 5
-This guide targets the exact mode key `react@webpack`: a generated typed React component using Webpack 5 Asset Modules and CSS Modules.
+A quick guide to creating an SVG sprite in a React application built with Webpack 5.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config adjacent to its source icons:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'react@webpack',
- name: 'icons',
+```json
+{
+ "mode": "react@webpack",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Use the exact Webpack 5 flags and generate once per invocation:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && webpack serve --mode development",
- "build": "npm run sprites && webpack --mode production"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "webpack serve --mode development",
+ "prebuild": "npm run sprites",
+ "build": "webpack --mode production"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. Generated declarations are self-contained and do not require the package.
+The value `name: "app"` creates the React component `AppIcon`.
-### Production usage
+Create the entry point `assets/app-icons/index.ts`:
-Import the generated component and icon-name list directly:
+```ts
+export * from './.svg-sprite/index.js'
+```
+
+Use the component in your application:
```tsx
-// src/App.tsx
-import {
- IconsIcon,
- iconsIconNames,
-} from './ui/icons/.svg-sprite/index.js'
+import { AppIcon } from '../assets/app-icons'
-export function App() {
+export function SaveIcon() {
return (
-
-
- {iconsIconNames.length} icons available
-
+
)
}
```
-The generated component uses `new URL('../sprite.svg', import.meta.url)`, which Webpack 5 processes through Asset Modules and emits as a separate SVG asset. Exclude `.svg-sprite/sprite.svg` from SVG component or SVGR rules so they do not intercept that URL dependency.
+The `icon` prop accepts source SVG file names without the extension. A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`.
-The generated component also imports `react-component.module.css`. Configure `.module.css` through `css-loader` with modules enabled, plus `style-loader` or `MiniCssExtractPlugin`:
+The component uses CSS Modules. If the project does not process them yet, install the loaders:
+
+```bash
+npm install --save-dev style-loader css-loader
+```
+
+Then add a rule with a default export to `webpack.config.js`:
```js
-// webpack.config.js (relevant rule)
-export default {
- module: {
- rules: [
- {
- test: /\.module\.css$/i,
- use: ['style-loader', { loader: 'css-loader', options: { modules: true } }],
- },
- ],
- },
+{
+ test: /\.module\.css$/i,
+ use: [
+ 'style-loader',
+ {
+ loader: 'css-loader',
+ options: { modules: { namedExport: false } },
+ },
+ ],
}
```
-## 2. Debug and preview
+Webpack 5 automatically adds `sprite.svg` to the production build.
-This section is optional. Only users who need the Viewer or icon previews should install:
+## Debug and preview
+
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development.
+
+Install Viewer:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Use the React `SpriteViewer` bridge with a static loader array. Keep every `import()` path a string literal so Webpack can create the chunk:
+Create the entry `src/svg-sprite-debug.tsx`:
```tsx
-// src/IconsDebugPage.tsx
+import { createRoot } from 'react-dom/client'
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
- () => import('./ui/icons/.svg-sprite/svg-sprite.manifest.js'),
-]
+ () => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
+] as const
-export function IconsDebugPage() {
- return
-}
+const container = document.createElement('div')
+document.body.append(container)
+
+createRoot(container).render(
+ ,
+)
```
-Keep this component on a debug route or in an internal tool. Viewer is not part of the production icon runtime.
+Add the script to the main entry only in development mode. Keep the rest of your `webpack.config.js` settings:
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'react@webpack',
- name: 'icons',
+```js
+export default (_env, argv) => ({
+ // Other Webpack settings.
+ entry: [
+ './src/main.tsx',
+ ...(argv.mode === 'development' ? ['./src/svg-sprite-debug.tsx'] : []),
+ ],
})
```
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
-
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'react@webpack'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'react@webpack',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+Run `npm run dev`. Viewer appears on the application's main page and is not included in the production build.
diff --git a/docs/en/guides/standalone-vite.md b/docs/en/guides/standalone-vite.md
index 27f151e..ab46219 100644
--- a/docs/en/guides/standalone-vite.md
+++ b/docs/en/guides/standalone-vite.md
@@ -1,156 +1,114 @@
-# Standalone Vite SVG Sprite Quick Start
+# SVG Sprite for Vite Without a Framework
-This guide targets the exact mode key `standalone@vite`: a native generated Web Component with Vite-managed SVG assets.
+A quick guide to creating an SVG sprite in a Vite application without a framework.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config and source icons together:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'standalone@vite',
- name: 'icons',
+```json
+{
+ "mode": "standalone@vite",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate once directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Use the exact Vite dev/build commands and generate once per invocation:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && vite",
- "build": "npm run sprites && vite build"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "vite",
+ "prebuild": "npm run sprites",
+ "build": "vite build"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. The generated JavaScript and declarations live together, and the declarations are self-contained: they do not require `@gromlab/svg-sprites`.
+The value `name: "app"` creates the `` element.
-### Production usage
-
-Register the generated element once, then use ``:
+Create the entry point `assets/app-icons/index.ts`:
```ts
-// src/main.ts
-import {
- defineIconsIconElement,
- iconsIconNames,
-} from './ui/icons/.svg-sprite/index.js'
-
-defineIconsIconElement()
-console.log('Available icons:', iconsIconNames)
+export * from './.svg-sprite/index.js'
```
+Register the element in `src/main.ts`:
+
+```ts
+import { defineAppIconElement } from '../assets/app-icons'
+import './style.css'
+
+defineAppIconElement()
+```
+
+Use the icon in HTML:
+
```html
-
+
```
-The host is `1em` by `1em`, so `font-size` controls its default size. Transformed colors use `currentColor` and custom properties such as `--icon-color-1`:
+The file `check.svg` is available as `icon="check"`. Set its size and colors with CSS:
```css
-icons-icon {
+app-icon {
font-size: 24px;
- color: #2563eb;
- --icon-color-2: #dbeafe;
+ color: #334155;
+ --icon-color-2: #f59e0b;
}
```
-Vite handles the generated `sprite.svg?no-inline` import automatically and emits a separate asset. If your own TypeScript source imports Vite query assets, include Vite's ambient types:
+A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`. Viewer shows the variables you need.
-```json
-{
- "compilerOptions": {
- "types": ["vite/client"]
- }
-}
-```
+Vite automatically adds `sprite.svg` to the production build. You do not need to copy it to `public`.
-## 2. Debug and preview
+## Debug and preview
-This section is optional. Only users who need the Viewer or icon previews should install:
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Register the Viewer element, import its type, and assign the generated JavaScript manifest to `sources`:
+Create `svg-sprite.html` in the project root:
+
+```html
+
+
+
+
+ Project icons
+
+
+
+
+
+
+
+
+
+```
+
+Create `src/svg-sprite-debug.ts`:
```ts
import '@gromlab/svg-sprites/viewer/element'
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
-import spriteManifest from './ui/icons/.svg-sprite/svg-sprite.manifest.js'
-
-document.querySelector('#debug')!.innerHTML = `
-
-`
+import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
const viewer = document.querySelector('gromlab-sprite-viewer')!
viewer.sources = [spriteManifest]
```
-Keep this code on a debug route or in an internal tool. Viewer is not part of the production icon runtime.
+Run `npm run dev` and open `/svg-sprite.html`.
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'standalone@vite',
- name: 'icons',
-})
-```
-
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
-
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'standalone@vite'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'standalone@vite',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+Viewer is not required for `` and is not imported by the application's main code.
diff --git a/docs/en/guides/standalone-webpack.md b/docs/en/guides/standalone-webpack.md
index 29e477b..94d663d 100644
--- a/docs/en/guides/standalone-webpack.md
+++ b/docs/en/guides/standalone-webpack.md
@@ -1,143 +1,111 @@
-# Standalone Webpack SVG Sprite Quick Start
+# SVG Sprite for Webpack 5 Without a Framework
-This guide targets the exact mode key `standalone@webpack`: a native generated Web Component using Webpack 5 Asset Modules.
+A quick guide to creating an SVG sprite in a Webpack 5 application without a framework.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`.
+Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
-Keep the config adjacent to its source icons:
+Create `assets/app-icons/svg-sprite.config.json`:
-```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-Use a plain default object export with no package import:
-
-```ts
-// src/ui/icons/svg-sprite.config.ts
-export default {
- mode: 'standalone@webpack',
- name: 'icons',
+```json
+{
+ "mode": "standalone@webpack",
+ "name": "app",
+ "input": "../svg-icons/**/*.svg"
}
```
-When `input` is omitted, SVG files are read from `./icons` relative to the config. A `.js` config with a default export and a `.json` config are also supported. Generate directly with:
+The `input` path is relative to the config folder.
-```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts
-```
-
-Use the exact Webpack 5 flags and generate once per invocation:
+Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.ts",
- "dev": "npm run sprites && webpack serve --mode development",
- "build": "npm run sprites && webpack --mode production"
+ "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
+ "predev": "npm run sprites",
+ "dev": "webpack serve --mode development",
+ "prebuild": "npm run sprites",
+ "build": "webpack --mode production"
}
}
```
-Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
+## Use the sprite
-Generation creates a local `.gitignore`; commit that file once, but do not commit `.svg-sprite/`. Generated declarations are self-contained and do not require the package.
+The value `name: "app"` creates the `` element.
-### Production usage
-
-Register the generated element once, then use ``:
+Create the entry point `assets/app-icons/index.ts`:
```ts
-// src/main.ts
-import {
- defineIconsIconElement,
- iconsIconNames,
-} from './ui/icons/.svg-sprite/index.js'
-
-defineIconsIconElement()
-console.log('Available icons:', iconsIconNames)
+export * from './.svg-sprite/index.js'
```
+Register the element in the application's main entry:
+
+```ts
+import { defineAppIconElement } from '../assets/app-icons'
+import './style.css'
+
+defineAppIconElement()
+```
+
+Use the icon in HTML:
+
```html
-
+
```
-The generated facade uses `new URL('./sprite.svg', import.meta.url)`, which Webpack 5 processes through Asset Modules and emits as a separate asset. If the project has SVG-to-component or SVGR rules, exclude `.svg-sprite/sprite.svg` from them so they do not intercept this URL dependency. Check `output.publicPath` if the emitted URL is wrong.
+The file `check.svg` is available as `icon="check"`. Set its size and colors with CSS:
-## 2. Debug and preview
+```css
+app-icon {
+ font-size: 24px;
+ color: #334155;
+ --icon-color-2: #f59e0b;
+}
+```
-This section is optional. Only users who need the Viewer or icon previews should install:
+A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`. Viewer shows the variables you need.
+
+Webpack 5 automatically adds `sprite.svg` to the production build.
+
+## Debug and preview
+
+Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development.
+
+Install Viewer:
```bash
npm install --save-dev @gromlab/svg-sprites
```
-Register the Viewer element, import its type, and assign the generated JavaScript manifest to `sources`:
+Create the entry `src/svg-sprite-debug.ts`:
```ts
import '@gromlab/svg-sprites/viewer/element'
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
-import spriteManifest from './ui/icons/.svg-sprite/svg-sprite.manifest.js'
+import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
-document.querySelector('#debug')!.innerHTML = `
-
-`
-
-const viewer = document.querySelector('gromlab-sprite-viewer')!
+const viewer = document.createElement('gromlab-sprite-viewer') as SpriteViewerElement
+viewer.viewerTitle = 'Project icons'
viewer.sources = [spriteManifest]
+document.body.append(viewer)
```
-Keep this code on a debug route or in an internal tool. Viewer is not part of the production icon runtime.
+Add the script to the main entry only in development mode. Keep the rest of your `webpack.config.js` settings:
-## 3. Type the config
-
-Choose one of these two paths.
-
-### With a local package installation
-
-After installing the package locally, use the helper:
-
-```ts
-import { defineSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineSpriteConfig({
- mode: 'standalone@webpack',
- name: 'icons',
+```js
+export default (_env, argv) => ({
+ // Other Webpack settings.
+ entry: [
+ './src/main.ts',
+ ...(argv.mode === 'development' ? ['./src/svg-sprite-debug.ts'] : []),
+ ],
})
```
-You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
+Run `npm run dev`. Viewer appears on the application's main page.
-### Without the package
-
-Copy a mode-specific type directly into the config:
-
-```ts
-type LocalSpriteConfig = {
- mode: 'standalone@webpack'
- name?: string
- description?: string
- input?: string | string[]
- transform?: {
- removeSize?: boolean
- replaceColors?: boolean
- addTransition?: boolean
- }
- generatedNotice?: boolean
-}
-
-export default {
- mode: 'standalone@webpack',
- name: 'icons',
-} satisfies LocalSpriteConfig
-```
+Viewer is only added to the development build and is not included in production.
diff --git a/docs/en/guides/standalone.md b/docs/en/guides/standalone.md
index 4309921..47b715b 100644
--- a/docs/en/guides/standalone.md
+++ b/docs/en/guides/standalone.md
@@ -1,22 +1,26 @@
-# Standalone SVG Sprite Quick Start
+# SVG Sprite for a Site Without a Bundler
-This guide targets the exact mode key `standalone`: static HTML or a custom asset pipeline with no generated JavaScript facade.
+Combine SVG icons into one file and use them on an HTML page.
-## 1. Generate the sprite
+## Generate the sprite
-No package installation and no `package.json` dependency are needed. `npx` downloads the CLI temporarily, and generated runtime does not import `@gromlab/svg-sprites`; bare `standalone` does not generate a JavaScript runtime at all.
+You do not need to install the package in your project.
-Keep the config next to its source icons:
+This guide uses the following project structure:
```text
-src/ui/icons/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.json
+/
+├── index.html
+└── assets/
+ ├── app-icons/
+ └── svg-icons/
+ ├── check.svg
+ └── warning.svg
```
-Create a JSON config:
+### 1. Create the sprite config
+
+Choose a folder for the sprite. This example uses `assets/app-icons`. Create `svg-sprite.config.json` inside it:
```json
{
@@ -25,147 +29,80 @@ Create a JSON config:
}
```
-When `input` is omitted, the generator reads `./icons` next to the config.
+### 2. Set the icon source
-To include SVG files from nested directories, set one glob pattern:
+`input` can point to a folder, an individual SVG file, or a glob pattern. To use multiple sources, provide an array with any combination of these values:
```json
{
"mode": "standalone",
"name": "icons",
- "input": "../assets/icons/**/*.svg"
+ "input": "../svg-icons/**/*.svg"
}
```
-An array can mix folders, individual SVG files, and glob patterns:
+### 3. Generate the sprite
-```json
-{
- "mode": "standalone",
- "name": "icons",
- "input": [
- "../assets/icons",
- "../features/profile/user.svg",
- "../features/admin/*.svg"
- ]
-}
-```
-
-All relative paths start at the config directory. Pass the config path explicitly:
+Pass the config path to the command:
```bash
-npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.json
+npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json
```
-For repeatable local commands, the same temporary CLI can be used from a script:
+The package collects the icons in a `.svg-sprite` directory next to the config:
-```json
-{
- "scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.json"
- }
-}
+```text
+assets/app-icons/.svg-sprite/
+├── sprite.svg
+└── svg-sprite.manifest.json
```
-Run that script once from your existing dev/build pipeline. If you use a `predev` or `prebuild` hook instead, do not also call `npm run sprites` inside the corresponding script. Bare `standalone` has no bundler-specific dev or build flag. In CI, replace `latest` with an exact package version.
+- `sprite.svg` is the finished sprite for use on the site.
+- `svg-sprite.manifest.json` contains icon data for Viewer.
-Bare `standalone` does not create or modify `.gitignore`; the application decides whether `.svg-sprite/` is committed or ignored. It emits no declarations, facade, or component. Generated declarations in typed modes are self-contained and do not require the package.
+The `.svg-sprite` directory is created automatically and fully replaced on every generation. Do not edit its contents manually.
-### Production usage
+### 4. Use an icon
-The application owns the public URL, versioning, and cache policy. Copy both generated assets into the deploy output:
-
-```bash
-cp src/ui/icons/.svg-sprite/sprite.svg public/assets/icons.svg
-cp src/ui/icons/.svg-sprite/svg-sprite.manifest.json public/assets/icons.manifest.json
-```
-
-Use the published URL manually:
+In `index.html`, point to the generated `sprite.svg`. After `#`, add the icon file name without the `.svg` extension:
```html
-
```
-Standalone Vite/Webpack provides generated `getIconsIconHref()` and an internal ID
+Standalone Vite/Webpack provides generated `getAppIconHref()` and an internal ID
map. Do not construct fragments from unsafe file names manually.
Vite:
@@ -603,7 +605,7 @@ Commit the local `.gitignore` to the repository once. It excludes the other gene
```json
{
"scripts": {
- "sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/app-icons/svg-sprite.config.ts",
+ "sprites": "npx --yes @gromlab/svg-sprites src/ui/app-icons/svg-sprite.config.ts",
"predev": "npm run sprites",
"prebuild": "npm run sprites",
"pretypecheck": "npm run sprites"
@@ -611,22 +613,22 @@ Commit the local `.gitignore` to the repository once. It excludes the other gene
}
```
-CI must run generation before building or type-checking. Replace `latest` with an exact version for reproducibility. A local package installation is not required unless CI also uses the Viewer, package config types, or the programmatic API.
+CI must run generation before building or type-checking. Pin `@gromlab/svg-sprites` to an exact version when the CI toolchain must be reproducible. A local package installation is not required unless CI also uses the Viewer, package config types, or the programmatic API.
-Bare `standalone` does not create or modify `.gitignore`; the application decides whether its `.svg-sprite/` output is committed or ignored. In other modes, the generator will not overwrite a user-created `.gitignore`. It also refuses to overwrite a user-owned file inside `.svg-sprite`. The root `index.ts` remains user-owned and may re-export the generated API.
+Bare `standalone` does not create a `.gitignore` and preserves a user-owned file. If a managed `.gitignore` remains after another mode, bare mode removes it. In every other mode, the generator refuses to overwrite a user-owned `.gitignore` without a generated marker. The root `index.ts` remains user-owned and may re-export the generated API.
## Troubleshooting
-- Missing `.svg-sprite/index.js`: run the generation script before importing the generated module.
+- In every mode except bare `standalone`, missing `.svg-sprite/index.js`: run the generation script before importing the generated module.
- Source not found: pass an existing config file or sprite module directory.
- Mode missing: add `mode` to the config or pass `--mode`.
- Icon missing from the type: check `input`, the `.svg` extension, glob exclusions, and whether nested folders require `**/*.svg`.
- Name conflict: two different SVG files have the same basename; rename one of them.
-- `Refusing to overwrite a user file`: a file without the generated marker occupies a managed path.
+- `Refusing to overwrite a user file`: the sprite module root contains a user-owned `.gitignore` that the generator cannot replace.
- The icon does not change color: use `