mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
style: Синхронизировать английскую документацию
This commit is contained in:
@@ -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)
|
||||
|
||||
99
docs/en/configuration.md
Normal file
99
docs/en/configuration.md
Normal file
@@ -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).
|
||||
@@ -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 (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
<AppIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Done"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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 <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
```
|
||||
|
||||
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 <IconsViewer />
|
||||
import { SvgSpriteViewer } from './SvgSpriteViewer'
|
||||
|
||||
export default function SvgSpritePage() {
|
||||
if (process.env.NODE_ENV !== 'development') notFound()
|
||||
|
||||
return <SvgSpriteViewer />
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@@ -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 (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
<AppIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Done"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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 <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
```
|
||||
|
||||
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 <IconsViewer />
|
||||
import { SvgSpriteViewer } from './SvgSpriteViewer'
|
||||
|
||||
export default function SvgSpritePage() {
|
||||
if (process.env.NODE_ENV !== 'development') notFound()
|
||||
|
||||
return <SvgSpriteViewer />
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@@ -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 (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
<AppIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Done"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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 <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
|
||||
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.
|
||||
|
||||
@@ -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 (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
<AppIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Done"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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 <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
|
||||
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.
|
||||
|
||||
@@ -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 (
|
||||
<main>
|
||||
<IconsIcon icon="check" width={24} height={24} aria-label="Complete" />
|
||||
<small>{iconsIconNames.length} icons available</small>
|
||||
</main>
|
||||
<AppIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Done"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
`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
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Project icons</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- React root for debugging and previewing the SVG sprite in Viewer -->
|
||||
<div id="svg-sprite-viewer"></div>
|
||||
|
||||
<!-- Load the debug script created below -->
|
||||
<script type="module" src="/src/svg-sprite-debug.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
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 <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
createRoot(document.getElementById('svg-sprite-viewer')!).render(
|
||||
<SpriteViewer sources={sources} title="Project icons" />,
|
||||
)
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@@ -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 (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<small>{iconsIconNames.length} icons available</small>
|
||||
</main>
|
||||
<AppIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Done"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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 <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
const container = document.createElement('div')
|
||||
document.body.append(container)
|
||||
|
||||
createRoot(container).render(
|
||||
<SpriteViewer sources={sources} title="Project icons" />,
|
||||
)
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@@ -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 `<app-icon>` element.
|
||||
|
||||
### Production usage
|
||||
|
||||
Register the generated element once, then use `<icons-icon>`:
|
||||
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
|
||||
<icons-icon icon="check" role="img" aria-label="Complete"></icons-icon>
|
||||
<app-icon icon="check" role="img" aria-label="Done"></app-icon>
|
||||
```
|
||||
|
||||
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
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Project icons</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- Viewer component for debugging and previewing the SVG sprite -->
|
||||
<gromlab-sprite-viewer viewer-title="Project icons"></gromlab-sprite-viewer>
|
||||
|
||||
<!-- Load the debug script created below -->
|
||||
<script type="module" src="/src/svg-sprite-debug.ts"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
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<HTMLDivElement>('#debug')!.innerHTML = `
|
||||
<gromlab-sprite-viewer viewer-title="Project icons"></gromlab-sprite-viewer>
|
||||
`
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('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 `<app-icon>` and is not imported by the application's main code.
|
||||
|
||||
@@ -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 `<app-icon>` element.
|
||||
|
||||
### Production usage
|
||||
|
||||
Register the generated element once, then use `<icons-icon>`:
|
||||
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
|
||||
<icons-icon
|
||||
icon="check"
|
||||
role="img"
|
||||
aria-label="Complete"
|
||||
style="font-size:24px;color:#16a34a;--icon-color-1:#16a34a"
|
||||
></icons-icon>
|
||||
<app-icon icon="check" role="img" aria-label="Done"></app-icon>
|
||||
```
|
||||
|
||||
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<HTMLDivElement>('#debug')!.innerHTML = `
|
||||
<gromlab-sprite-viewer viewer-title="Project icons"></gromlab-sprite-viewer>
|
||||
`
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('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.
|
||||
|
||||
@@ -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
|
||||
<svg width="24" height="24" role="img" aria-label="Complete">
|
||||
<use href="/assets/icons.svg#check"></use>
|
||||
<svg
|
||||
width="24"
|
||||
height="24"
|
||||
aria-label="Done"
|
||||
>
|
||||
<use href="./assets/app-icons/.svg-sprite/sprite.svg#check"></use>
|
||||
</svg>
|
||||
```
|
||||
|
||||
Safe icon names normally match their fragment IDs. Names containing spaces or other SVG-ID-unsafe characters receive a generated ID; read that icon's `id` from `icons.manifest.json` instead of constructing the fragment yourself.
|
||||
The icon from `check.svg` is available as `#check`.
|
||||
|
||||
## 2. Debug and preview
|
||||
## Debug and preview
|
||||
|
||||
This section is optional. Only install the package locally if you need the debug Viewer or an icon preview:
|
||||
`sprite.svg` is a technical file, not an icon gallery. Opening it does not provide a convenient view of the whole set. Gradients, masks, filters, and references to internal `id` values may also render with artifacts.
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
Use the official Viewer for visual checks. It displays every icon in the sprite and helps you verify its colors and rendering.
|
||||
|
||||
Without a bundler, self-host the browser bundle by copying it from `node_modules` into the deploy output:
|
||||
Viewer is optional and intended only for development. You do not need to install the package through npm.
|
||||
|
||||
```bash
|
||||
cp node_modules/@gromlab/svg-sprites/dist/viewer-element.js public/debug/viewer-element.js
|
||||
```
|
||||
Viewer works directly with files from `.svg-sprite`. Nothing needs to be copied.
|
||||
|
||||
Then provide both public asset URLs through HTML attributes:
|
||||
### Add Viewer to the page
|
||||
|
||||
```html
|
||||
<script type="module" src="/debug/viewer-element.js"></script>
|
||||
|
||||
<gromlab-sprite-viewer
|
||||
viewer-title="Project icons"
|
||||
manifest-url="/assets/icons.manifest.json"
|
||||
sprite-url="/assets/icons.svg"
|
||||
></gromlab-sprite-viewer>
|
||||
```
|
||||
|
||||
For a quick preview, a pinned CDN file can replace the self-hosted script:
|
||||
Add a module script to `index.html` and provide paths to the generated manifest and sprite:
|
||||
|
||||
```html
|
||||
<script
|
||||
type="module"
|
||||
src="https://unpkg.com/@gromlab/svg-sprites@1.1.5/dist/viewer-element.js"
|
||||
src="https://cdn.jsdelivr.net/npm/@gromlab/svg-sprites/dist/viewer-element.js"
|
||||
></script>
|
||||
|
||||
<gromlab-sprite-viewer
|
||||
viewer-title="Project icons"
|
||||
manifest-url="./assets/app-icons/.svg-sprite/svg-sprite.manifest.json"
|
||||
sprite-url="./assets/app-icons/.svg-sprite/sprite.svg"
|
||||
></gromlab-sprite-viewer>
|
||||
```
|
||||
|
||||
Self-host the file for controlled environments and pin the CDN version if you use the alternative. Viewer is optional tooling, not part of the production icon runtime.
|
||||
|
||||
## 3. Type the config
|
||||
|
||||
This guide uses a JSON config, which works without TypeScript types. If config autocomplete is needed, replace `svg-sprite.config.json` with `svg-sprite.config.ts` and choose one of these approaches.
|
||||
|
||||
### 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',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
You can alternatively import `type SpriteConfig` and apply `satisfies SpriteConfig`.
|
||||
|
||||
### Without the package
|
||||
|
||||
Keep a narrow local type directly in the config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'standalone'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'standalone',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
You can move Viewer to a separate HTML file in the site root used only for development and icon checks.
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
# Next.js App Router Guides Moved
|
||||
|
||||
- [App Router + Turbopack](guides/next-app-turbopack.md)
|
||||
- [App Router + Webpack](guides/next-app-webpack.md)
|
||||
@@ -1,4 +0,0 @@
|
||||
# Next.js Pages Router Guides Moved
|
||||
|
||||
- [Pages Router + Turbopack](guides/next-pages-turbopack.md)
|
||||
- [Pages Router + Webpack](guides/next-pages-webpack.md)
|
||||
@@ -1,3 +0,0 @@
|
||||
# Programmatic API Moved
|
||||
|
||||
The canonical document is now the [programmatic API](reference/programmatic-api.md).
|
||||
@@ -1,3 +0,0 @@
|
||||
# React + Vite Guide Moved
|
||||
|
||||
The canonical guide is now [React + Vite](guides/react-vite.md).
|
||||
@@ -1,3 +0,0 @@
|
||||
# React + Webpack Guide Moved
|
||||
|
||||
The canonical guide is now [React + Webpack](guides/react-webpack.md).
|
||||
@@ -1,3 +0,0 @@
|
||||
# Technical Reference Moved
|
||||
|
||||
The canonical document is now the [technical reference](reference/technical.md).
|
||||
@@ -14,6 +14,24 @@ const result = await generateSprite(
|
||||
)
|
||||
```
|
||||
|
||||
The result contains the sprite name, exact mode, mode-specific asset target, icon count, and absolute filesystem paths:
|
||||
|
||||
```ts
|
||||
result.name
|
||||
result.mode
|
||||
result.target
|
||||
result.iconCount
|
||||
result.rootDir
|
||||
result.generatedDir
|
||||
result.spritePath
|
||||
result.manifestPath
|
||||
```
|
||||
|
||||
Next.js modes additionally return `router` and `bundler`.
|
||||
For bare `standalone`, `target` is `static`; standalone bundler and React modes
|
||||
return `vite` or `webpack`; Next.js modes return their full exact mode as the
|
||||
target.
|
||||
|
||||
For static standalone mode, use `result.spritePath` in a build script to publish the
|
||||
SVG under an application URL:
|
||||
|
||||
@@ -29,7 +47,7 @@ await copyFile(result.spritePath, 'dist/app-icons/sprite.svg')
|
||||
`spritePath` is a filesystem path, not a browser URL. A deployment-neutral JSON
|
||||
manifest is available through `result.manifestPath` and is copied independently.
|
||||
|
||||
The first argument accepts the full path to an explicitly selected `.ts`, `.js`, or `.json` config file with any name. Passing a directory enables config-less mode and uses that directory as the sprite module root.
|
||||
The first argument accepts an absolute or relative path to an explicitly selected `.ts`, `.js`, or `.json` config file with any name. Passing a directory enables config-less mode and uses that directory as the sprite module root.
|
||||
|
||||
The second argument contains optional overrides and always takes precedence over the config:
|
||||
|
||||
@@ -51,7 +69,7 @@ Configuration is resolved in this order:
|
||||
defaults → config → API overrides
|
||||
```
|
||||
|
||||
For fully programmatic generation, pass a directory and provide the required settings as overrides:
|
||||
For fully programmatic generation, pass a directory and provide the required `mode` and any other settings as overrides. `name` is optional: when omitted, it is inferred in kebab-case from the directory name, or from the parent directory when the module directory is named `svg-sprite` or `svg-sprites`:
|
||||
|
||||
```ts
|
||||
await generateSprite('src/ui/file-manager/svg-sprite', {
|
||||
@@ -107,13 +125,17 @@ An explicitly supplied target overrides `mode` from the file. Prefer `generateSp
|
||||
|
||||
```ts
|
||||
import {
|
||||
isSpriteMode,
|
||||
loadSpriteConfig,
|
||||
resolveSpriteConfig,
|
||||
resolveSpriteConfigSource,
|
||||
validateSpriteConfig,
|
||||
} from '@gromlab/svg-sprites'
|
||||
```
|
||||
|
||||
- `isSpriteMode(value)` checks whether a value is a supported exact mode.
|
||||
- `loadSpriteConfig(file)` loads an explicitly selected `.ts`, `.js`, or `.json` file.
|
||||
- `resolveSpriteConfigSource(source)` resolves a path as either a config file or a config-less directory.
|
||||
- `validateSpriteConfig(value)` performs runtime validation.
|
||||
- `resolveSpriteConfig(root, config, overrides)` merges values, applies defaults, and resolves paths relative to `root`.
|
||||
|
||||
@@ -138,6 +160,22 @@ import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
|
||||
The browser entry registers `<gromlab-sprite-viewer>`. Bare standalone can also load the self-contained `dist/viewer-element.js` without a bundler.
|
||||
|
||||
For manual registration, import the runtime without the auto-register entry:
|
||||
|
||||
```ts
|
||||
import { defineSpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
|
||||
defineSpriteViewerElement()
|
||||
```
|
||||
|
||||
Both Viewer entries export the registration function and the same public types:
|
||||
`SpriteViewerColorTheme`, `SpriteViewerElement`, `SpriteViewerManifest`,
|
||||
`SpriteViewerManifestColor`, `SpriteViewerManifestIcon`,
|
||||
`SpriteViewerManifestLoader`, `SpriteViewerManifestModule`,
|
||||
`SpriteViewerManifestUsage`, `SpriteViewerRemoteSource`, `SpriteViewerSource`,
|
||||
and `SpriteViewerSources`. Only `@gromlab/svg-sprites/viewer/element` registers the
|
||||
element as an import side effect.
|
||||
|
||||
The React bridge keeps the component API:
|
||||
|
||||
```tsx
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
[Documentation index](../README.md)
|
||||
|
||||
[JSON, JavaScript, and TypeScript configuration](../configuration.md)
|
||||
|
||||
Reference for the configuration, generated API, and behavior of `@gromlab/svg-sprites`. For step-by-step setup instructions, see the guide for your stack:
|
||||
|
||||
- [Bare standalone](../guides/standalone.md)
|
||||
@@ -24,7 +26,7 @@ Reference for the configuration, generated API, and behavior of `@gromlab/svg-sp
|
||||
Generation does not require a project dependency. Run the CLI through `npx`:
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites path/to/svg-sprite.config.ts
|
||||
npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.json
|
||||
```
|
||||
|
||||
Install the package as a development dependency only when the project needs the
|
||||
@@ -54,11 +56,11 @@ svg-sprites [options] <config-file-or-directory>
|
||||
| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
|
||||
| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
|
||||
|
||||
The config file may have any name and use the `.ts`, `.js`, or `.json` extension. The CLI does not discover it by convention: pass the file explicitly. The guides use `svg-sprite.config.ts` as the recommended name.
|
||||
The config file may have any name and use the `.ts`, `.js`, or `.json` extension. The CLI does not discover it by convention: pass the file explicitly. The recommended name is `svg-sprite.config.json`.
|
||||
|
||||
When a directory is passed, all settings come from CLI options. When a config file is passed, CLI options override the file. The full order is `defaults → config → CLI`.
|
||||
|
||||
Available options are `--mode`, `--name`, `--description`, repeatable `--input <path-or-glob>`, plus the `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition`, and `--generated-notice`/`--no-generated-notice` pairs. Transform flags override individual fields, while supplying at least one `--input` replaces the complete config `input` value.
|
||||
`--help` and `-h` print usage information without requiring a path. Generation options are `--mode`, `--name`, `--description`, repeatable `--input <path-or-glob>`, plus the `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition`, and `--generated-notice`/`--no-generated-notice` pairs. Transform flags override individual fields, while supplying at least one `--input` replaces the complete config `input` value.
|
||||
|
||||
Quote CLI glob patterns with single quotes so the shell does not expand them before the generator receives them:
|
||||
|
||||
@@ -96,7 +98,7 @@ export default defineSpriteConfig({
|
||||
| Option | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `mode` | `SpriteMode` | None | Generation mode; may be supplied by CLI/API |
|
||||
| `name` | `string` | Derived from the directory | Name of the sprite, component, and public types |
|
||||
| `name` | `string` | Derived from the directory | Sprite name; in modes with a component, it also determines the component and public type names |
|
||||
| `description` | `string` | None | Description for types and the debug manifest |
|
||||
| `input` | `string \| string[]` | `./icons` | SVG folders, files, and glob patterns relative to the config directory |
|
||||
| `transform` | `TransformOptions` | All enabled | SVG preparation settings |
|
||||
@@ -111,7 +113,7 @@ app → AppIcon
|
||||
file-manager → FileManagerIcon
|
||||
```
|
||||
|
||||
If `name` is omitted, the generator derives it from the directory. For a directory named `svg-sprite` or `svg-sprites`, the parent directory's name is used.
|
||||
If `name` is omitted, the generator converts the directory name to kebab-case. For a directory named `svg-sprite` or `svg-sprites`, the parent directory's name is used.
|
||||
|
||||
### Icon sources
|
||||
|
||||
@@ -141,7 +143,7 @@ After generation, a React or Next.js sprite directory looks like this:
|
||||
```text
|
||||
app-icons/
|
||||
├── .gitignore
|
||||
├── svg-sprite.config.ts
|
||||
├── svg-sprite.config.json
|
||||
├── index.ts # optional user-owned barrel
|
||||
└── .svg-sprite/
|
||||
├── index.js
|
||||
@@ -183,10 +185,10 @@ runtime asset and deployment-neutral manifest data:
|
||||
native generated Web Component with no external runtime dependencies. Bare
|
||||
`standalone` intentionally does not generate a JavaScript component.
|
||||
|
||||
The generator overwrites and deletes only files that contain its marker. If a user file occupies a managed path, generation fails. The root `index.ts` is user-owned; create a barrel when needed:
|
||||
The generator fully manages `.svg-sprite` and replaces the whole directory on every generation through a staged write with rollback on replacement failure. Any files added inside it are deleted during the next generation. Keep user-owned files alongside it, for example in a root `index.ts` barrel:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite'
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
## Standalone Web Component and TypeScript
|
||||
@@ -308,7 +310,7 @@ The component does not add accessibility semantics automatically. Pass appropria
|
||||
|
||||
## Multiple sprites
|
||||
|
||||
Each directory with a configuration creates an independent component, types, manifest, and SVG asset:
|
||||
Each directory with a configuration creates an independent mode-specific contract. React and Next.js modes generate a React component and types, `standalone@vite` and `standalone@webpack` generate a Web Component and types, and bare `standalone` generates an SVG and JSON manifest:
|
||||
|
||||
```text
|
||||
app-icons → AppIcon → shared icons
|
||||
@@ -354,7 +356,7 @@ Static HTML after the application publishes `.svg-sprite/sprite.svg`:
|
||||
</svg>
|
||||
```
|
||||
|
||||
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 `<svg><use>` or the generated component and check `replaceColors`.
|
||||
- Webpack emits an incorrect URL: check Asset Modules, `output.publicPath`, and SVG loaders.
|
||||
- Static sprite returns 404: check the post-generation copy or server alias, and do not put a filesystem `spritePath` into HTML.
|
||||
- The Viewer cannot find the sprite: check the path to `.svg-sprite/svg-sprite.manifest.js` and run generation before starting the application.
|
||||
- The Viewer cannot find the sprite: in bundler modes, check the path to `.svg-sprite/svg-sprite.manifest.js`; for bare `standalone`, check the published `svg-sprite.manifest.json` and `sprite.svg` URLs. Run generation before starting the application.
|
||||
- Build and mode do not match: use the target that corresponds to the actual bundler.
|
||||
|
||||
For custom orchestration and low-level compilation, see the [Programmatic API](programmatic-api.md).
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
@@ -66,7 +66,13 @@ export function SaveIcon() {
|
||||
|
||||
Свойство `icon` принимает имена исходных SVG без расширения. Монохромная иконка наследует `color`, а цвета многоцветной переопределяются через `--icon-color-N`.
|
||||
|
||||
Компонент использует CSS Modules. Если проект ещё не обрабатывает их с default export, добавьте правило в `webpack.config.js`:
|
||||
Компонент использует CSS Modules. Если проект ещё не обрабатывает их, установите loaders:
|
||||
|
||||
```bash
|
||||
npm install --save-dev style-loader css-loader
|
||||
```
|
||||
|
||||
Затем добавьте правило с default export в `webpack.config.js`:
|
||||
|
||||
```js
|
||||
{
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG находятся в `assets/svg-icons`.
|
||||
Выберите папку для спрайта. В примере используется `assets/app-icons`, а исходные SVG, включая используемый ниже `check.svg`, находятся в `assets/svg-icons`.
|
||||
|
||||
Создайте конфиг `assets/app-icons/svg-sprite.config.json`:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user