gromov/svg-sprites
1
0
Fork 0
mirror of https://github.com/gromlab-ru/svg-sprites.git synced 2026-07-22 04:40:17 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat: добавить локализацию документации и скиллов

Browse Source 
- добавлены английские README и руководства с переключением языка
- сборка скиллов разделена на английскую и русскую версии
- локализованные документы включены в npm-пакет
This commit is contained in:
Сергей Громов
2026-07-11 09:26:43 +03:00
parent 05a0a9f7ed
commit 81df9027cd
56 changed files with 5559 additions and 473 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/en/legacy.md Normal file
View File

@@ -0,0 +1,102 @@
# Legacy mode
[← Back to home](../../README.md)
A quick guide to generating centralized SVG sprites in `symbol` and `stack` formats, with an optional HTML preview.
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
```
## 2. Prepare the icons and config
```text
project/
├── src/assets/icons/
│ ├── check.svg
│ └── folder.svg
└── svg-sprites.config.ts
```
```ts
// svg-sprites.config.ts
import { defineLegacyConfig } from '@gromlab/svg-sprites'
export default defineLegacyConfig({
output: 'public/sprites',
preview: true,
sprites: [
{
name: 'icons',
input: 'src/assets/icons',
format: 'symbol',
},
],
})
```
## 3. Run generation
```bash
npx svg-sprites --mode legacy .
```
Result:
```text
public/sprites/
├── icons.sprite.svg
└── preview.html
```
With `preview: false`, the HTML file is not created. For the `stack` format, specify `format: 'stack'`.
## 4. Use the symbol sprite
```html
<svg width="24" height="24" aria-label="Done">
<use href="/sprites/icons.sprite.svg#check"></use>
</svg>
```
## 5. Add a package script
```json
{
"scripts": {
"sprites": "svg-sprites --mode legacy .",
"prebuild": "npm run sprites"
}
}
```
## Multiple sprites
Add multiple entries to `sprites`:
```ts
sprites: [
{
name: 'icons',
input: 'src/assets/icons',
format: 'symbol',
},
{
name: 'logos',
input: 'src/assets/logos',
format: 'stack',
},
]
```
All output files and the shared `preview.html` will be written to `output`.
## Troubleshooting
- Config not found: make sure `svg-sprites.config.ts` is located in the specified root directory.
- No icons: check `sprites[].input` and the `.svg` extension.
- Preview not needed: set `preview: false`.
For programmatic use, see [`generateLegacy`](programmatic-api.md#generatelegacy).

96
docs/en/migration-1.md Normal file
View File

@@ -0,0 +1,96 @@
# Migrating from 0.1.x to 1.0
[← Back to home](../../README.md)
Version 1.0 separates local generation for React and Next.js from the centralized legacy mode. The old config cannot be mixed with the new API in a single CLI invocation.
## CLI
The CLI now always requires an explicit `--mode` and a path to the configuration directory:
```text
svg-sprites
→ svg-sprites --mode <mode> <path>
```
Choose a mode based on your environment:
| Environment | Mode |
|---|---|
| React + Vite | `react@vite` |
| React + Webpack 5 | `react@webpack` |
| Next.js App Router + Turbopack | `next@app/turbopack` |
| Next.js App Router + Webpack 5 | `next@app/webpack` |
| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
| Centralized legacy setup | `legacy` |
## React and Next.js
Instead of a root-level `svg-sprites.config.ts`, create a local `svg-sprite.config.ts` next to the icon set:
```ts
import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
export default defineNextSpriteConfig({
name: 'global',
inputFolder: './icons',
})
```
For regular React, use `defineReactSpriteConfig`. A folder and an explicit list of shared SVG files can be combined using `inputFolder` and `inputFiles`.
The old `publicPath` and `react` options are no longer needed. The generated module is created next to the config and adds its own `.gitignore`, while Vite, Webpack, or Next.js emits the SVG as a separate asset with a content hash.
The `<SvgSprite icon="..." />` component is replaced by a component whose name is derived from `name`:
```tsx
<GlobalIcon icon="check" />
```
To browse the icons, add `<SpriteViewer>` as a debug page in the application. A separate `preview.html` is available only in legacy mode.
## Legacy mode
If you need to preserve the centralized structure, rename the helper and the format fields:
```ts
import { defineLegacyConfig } from '@gromlab/svg-sprites'
export default defineLegacyConfig({
output: 'public/sprites',
preview: true,
sprites: [
{
name: 'icons',
input: 'src/assets/icons',
format: 'stack',
},
],
})
```
- `defineConfig` has been replaced with `defineLegacyConfig`;
- `sprites[].mode` has been renamed to `sprites[].format`;
- `generate` has been replaced with `generateLegacy`;
- `loadConfig` has been replaced with `loadLegacyConfig`;
- `publicPath` and generation of the old shared React component have been removed.
Run:
```bash
svg-sprites --mode legacy .
```
## Programmatic API
The package is distributed as ESM only. Replace `require()` with `import`.
`compileSpriteContent` now returns `Promise<Uint8Array>` so that the public declarations do not require `@types/node` to be installed. In Node.js, the actual result is compatible with APIs that accept `Uint8Array`.
## After migration
1. Remove the old generated files and rules that ignored the entire directory containing the source icons.
2. Add an explicit generation command before `dev`, `build`, and `typecheck`.
3. Run generation and type checking.
4. Check all icons and color variables using `SpriteViewer` or the legacy `preview.html`.

102
docs/en/next-app.md Normal file
View File

@@ -0,0 +1,102 @@
# Next.js App Router
[← Back to home](../../README.md)
Two explicit modes are supported:
| Bundler | Mode key | Next.js version |
|---|---|---|
| Turbopack | `next@app/turbopack` | 16.2+ |
| Webpack 5 | `next@app/webpack` | 13.4+ |
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
```
## 2. Create a sprite module
```text
src/ui/file-manager/svg-sprite/
├── icons/
│ ├── check.svg
│ └── folder.svg
└── svg-sprite.config.ts
```
```ts
// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
export default defineNextSpriteConfig({
name: 'file-manager',
description: 'File manager icons',
})
```
## 3. Add generation
For Turbopack:
```json
{
"scripts": {
"sprite:file-manager": "svg-sprites --mode next@app/turbopack src/ui/file-manager/svg-sprite",
"predev": "npm run sprite:file-manager",
"prebuild": "npm run sprite:file-manager"
}
}
```
For Webpack, replace the mode key with `next@app/webpack`. In Next 13–15, Webpack is used with the regular `next build` command; in Next 16, use `next build --webpack`.
## 4. Use it in a Server Component
The generated component does not contain `'use client'`, so it can be imported directly into `page.tsx` or `layout.tsx`:
```tsx
import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
export default function Page() {
return (
<main>
<FileManagerIcon icon="folder" width={24} height={24} />
</main>
)
}
```
Next.js emits a separate SVG asset with a content hash. The same generated code is used during SSR and in the browser, with no URL mismatch.
## 5. Add SpriteViewer
The viewer is interactive, so it requires a separate Client Component boundary:
```tsx
'use client'
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
() => import('@/ui/file-manager/svg-sprite/manifest'),
]
export default function SpritesPage() {
return <SpriteViewer sources={sources} />
}
```
## Verify the bundler
```bash
# Turbopack
npx next build --turbopack
# Webpack 5
npx next build --webpack
```
For Next 13–15 with Webpack, use `npx next build` without the flag.
The Next.js command and the generator mode key must target the same bundler.

96
docs/en/next-pages.md Normal file
View File

@@ -0,0 +1,96 @@
# Next.js Pages Router
[← Back to home](../../README.md)
Two explicit modes are supported:
| Bundler | Mode key | Next.js version |
|---|---|---|
| Turbopack | `next@pages/turbopack` | 16.2+ |
| Webpack 5 | `next@pages/webpack` | 12.2+ |
Next.js 12.2 requires React 18.
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
```
## 2. Create a sprite module
```text
src/ui/file-manager/svg-sprite/
├── icons/
│ ├── check.svg
│ └── folder.svg
└── svg-sprite.config.ts
```
```ts
// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
export default defineNextSpriteConfig({
name: 'file-manager',
description: 'File manager icons',
})
```
## 3. Add generation
```json
{
"scripts": {
"sprite:file-manager": "svg-sprites --mode next@pages/webpack src/ui/file-manager/svg-sprite",
"predev": "npm run sprite:file-manager",
"prebuild": "npm run sprite:file-manager"
}
}
```
For Next.js 16.2 with Turbopack, replace the mode key with `next@pages/turbopack`.
## 4. Use it on a page
```tsx
import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
export default function FilesPage() {
return <FileManagerIcon icon="folder" width={24} height={24} />
}
export function getServerSideProps() {
return { props: {} }
}
```
The component works the same way with SSR, SSG, and client-side navigation. Next.js emits a separate SVG asset with a content hash.
## 5. Add SpriteViewer
```tsx
import { SpriteViewer } from '@gromlab/svg-sprites/react'
const sources = [
() => import('@/ui/file-manager/svg-sprite/manifest'),
]
export default function SpritesPage() {
return <SpriteViewer sources={sources} />
}
```
## Verify the bundler
```bash
# Turbopack
npx next build --turbopack
# Webpack 5
npx next build --webpack
```
For Next 12–15 with Webpack, use `npx next build` without the flag.
The Next.js command and the generator mode key must target the same bundler.

203
docs/en/programmatic-api.md Normal file
View File

@@ -0,0 +1,203 @@
# Programmatic API
[← Back to home](../../README.md)
The package provides a main Node.js entry point and a separate React runtime entry point. Both are distributed as ESM only and must be loaded with `import`.
To resolve `@gromlab/svg-sprites/react` in TypeScript, use `moduleResolution: "bundler"`, `"node16"`, or `"nodenext"`.
## Main entry point
```ts
import {
defineNextSpriteConfig,
defineReactSpriteConfig,
generateNextSprite,
generateReactSprite,
} from '@gromlab/svg-sprites'
```
The main entry point does not import React and can be used in CLIs, build scripts, and Node.js tools.
## `generateReactSprite`
```ts
import { generateReactSprite } from '@gromlab/svg-sprites'
const result = await generateReactSprite(
'src/ui/file-manager/svg-sprite',
'vite',
)
```
The second argument is required:
```ts
type ReactAssetTarget = 'vite' | 'webpack'
```
Result:
```ts
type ReactSpriteGenerationResult = {
name: string
rootDir: string
generatedDir: string
spritePath: string
manifestPath: string
iconCount: number
target: 'vite' | 'webpack'
}
```
```ts
console.log(result.name)
console.log(result.iconCount)
console.log(result.spritePath)
console.log(result.manifestPath)
```
The function loads `svg-sprite.config.ts` from the specified root, compiles the SVG files, and safely updates managed files.
## `generateNextSprite`
```ts
import { generateNextSprite } from '@gromlab/svg-sprites'
const result = await generateNextSprite(
'src/ui/file-manager/svg-sprite',
{
router: 'app',
bundler: 'turbopack',
},
)
```
Available values:
```ts
type NextSpriteGenerationOptions = {
router: 'app' | 'pages'
bundler: 'turbopack' | 'webpack'
}
```
The result also contains the selected `router`, `bundler`, and the full target in the form `next@app/turbopack`.
## `defineReactSpriteConfig`
```ts
import { defineReactSpriteConfig } from '@gromlab/svg-sprites'
export default defineReactSpriteConfig({
name: 'file-manager',
description: 'File manager icons',
inputFolder: './icons',
inputFiles: [
'../../shared/icons/check.svg',
],
transform: {
removeSize: true,
replaceColors: true,
addTransition: true,
},
generatedNotice: true,
})
```
`inputFolder` and `inputFiles` are combined. The helper returns the configuration without runtime transformations and provides TypeScript autocomplete.
## `defineNextSpriteConfig`
```ts
import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
export default defineNextSpriteConfig({
name: 'file-manager',
description: 'File manager icons',
inputFolder: './icons',
})
```
Next.js uses the same configuration contract as the React presets.
## `generateLegacy`
```ts
import { generateLegacy } from '@gromlab/svg-sprites'
const results = await generateLegacy({
output: 'public/sprites',
preview: false,
sprites: [
{
name: 'icons',
input: 'src/assets/icons',
format: 'symbol',
},
],
})
```
Returns an array:
```ts
type SpriteResult = {
name: string
format: 'symbol' | 'stack'
spritePath: string
iconCount: number
}
```
For details, see [Legacy mode](legacy.md).
## Low-level functions
The main entry point also exports:
```ts
import {
compileSprite,
compileSpriteContent,
createShapeTransform,
generatePreview,
loadLegacyConfig,
loadReactSpriteConfig,
resolveSpriteEntry,
resolveSprites,
} from '@gromlab/svg-sprites'
```
These functions are intended for custom orchestration built on top of the existing compiler and writer. For standard usage, prefer `generateReactSprite` and `generateLegacy`.
## React runtime entry point
```tsx
import { SpriteViewer } from '@gromlab/svg-sprites/react'
```
Types:
```ts
import type {
SpriteManifest,
SpriteManifestColor,
SpriteManifestIcon,
SpriteManifestLoader,
SpriteManifestModule,
SpriteViewerColorTheme,
SpriteViewerProps,
SpriteViewerSource,
SpriteViewerSources,
} from '@gromlab/svg-sprites/react'
```
The React entry point contains `'use client'` and is intended for debug tools. Generated production components are imported from the application's local sprite modules, not from the package's React entry point.
`SpriteViewerProps.colorTheme` accepts `auto | light | dark`. The default is `auto`, which follows `prefers-color-scheme`; to synchronize it with the application theme, pass the computed `light` or `dark` value.
## Related guides
- [React + Vite](react-vite.md)
- [React + Webpack 5](react-webpack.md)

116
docs/en/react-vite.md Normal file
View File

@@ -0,0 +1,116 @@
# React + Vite
[← Back to home](../../README.md)
A quick guide to installing and using SVG sprites in a React and Vite project.
The result is a typed React component and a separate cacheable SVG asset.
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
```
## 2. Create the sprite directory
```text
src/ui/file-manager/svg-sprite/
├── icons/
│ ├── check.svg
│ └── folder.svg
└── 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 { defineReactSpriteConfig } from '@gromlab/svg-sprites'
export default defineReactSpriteConfig({
name: 'file-manager',
description: 'File manager icons',
})
```
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 [Configuration → React](../../README.md#react).
## 4. Add generation to package.json
```json
{
"scripts": {
"sprite:file-manager": "svg-sprites --mode react@vite src/ui/file-manager/svg-sprite",
"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
The name `file-manager` is converted to `FileManagerIcon`:
```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="check" /> // valid
<FileManagerIcon icon="unknown" /> // TypeScript error
```
Types, display methods, and color controls are described in the [main documentation](../../README.md#display-methods).
Vite emits the sprite as a separate file named like `assets/sprite-<hash>.svg`. SVG path data is not included in JavaScript.
## 6. Add a debug page
After integrating the icons, you can display all React sprites with `SpriteViewer`:
```tsx
import { SpriteViewer } from '@gromlab/svg-sprites/react'
import type { SpriteManifestModule } from '@gromlab/svg-sprites/react'
const sources = import.meta.glob<SpriteManifestModule>(
'/src/**/svg-sprite/manifest.ts',
)
export const IconsDebugPage = () => (
<SpriteViewer sources={sources} title="Project icons" />
)
```
Vite automatically finds the generated `manifest.ts` for each React sprite. The `import.meta.glob` pattern must be a string literal, and generation must run before Vite starts.
Only include the Viewer on a debug route or in an internal tool.
## Troubleshooting
- Missing `index.ts`: run `npm run sprite:file-manager`.
- The Viewer cannot find the sprite: check the glob path and make sure `manifest.ts` exists.
- `Refusing to overwrite a user file` error: there is a user file at a generated path.
- The icon does not change color: use `color` or `--icon-color-N`.

118
docs/en/react-webpack.md Normal file
View File

@@ -0,0 +1,118 @@
# 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 @gromlab/svg-sprites
```
## 2. Create the sprite directory
```text
src/ui/file-manager/svg-sprite/
├── icons/
│ ├── check.svg
│ └── folder.svg
└── 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 { defineReactSpriteConfig } from '@gromlab/svg-sprites'
export default defineReactSpriteConfig({
name: 'file-manager',
description: 'File manager icons',
})
```
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 [Configuration → React](../../README.md#react).
## 4. Add generation to package.json
```json
{
"scripts": {
"sprite:file-manager": "svg-sprites --mode react@webpack src/ui/file-manager/svg-sprite",
"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, display methods, and color controls are described in the [main documentation](../../README.md#display-methods).
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.
## 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/manifest'),
() => import('./ui/navigation/svg-sprite/manifest'),
]
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 `index.ts`: run `npm run sprite:file-manager`.
- The Viewer does not load the sprite: check the path in `import()` and make sure `manifest.ts` exists.
- 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.