mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
sync
This commit is contained in:
11
docs/en/guides/README.md
Normal file
11
docs/en/guides/README.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# Quick Start Guides
|
||||
|
||||
- `standalone`: [bare standalone](standalone.md)
|
||||
- `standalone@vite`: [standalone with Vite](standalone-vite.md)
|
||||
- `standalone@webpack`: [standalone with Webpack](standalone-webpack.md)
|
||||
- `react@vite`: [React with Vite](react-vite.md)
|
||||
- `react@webpack`: [React with Webpack](react-webpack.md)
|
||||
- `next@app/turbopack`: [App Router with Turbopack](next-app-turbopack.md)
|
||||
- `next@app/webpack`: [App Router with Webpack](next-app-webpack.md)
|
||||
- `next@pages/turbopack`: [Pages Router with Turbopack](next-pages-turbopack.md)
|
||||
- `next@pages/webpack`: [Pages Router with Webpack](next-pages-webpack.md)
|
||||
153
docs/en/guides/next-app-turbopack.md
Normal file
153
docs/en/guides/next-app-turbopack.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Next.js App Router Turbopack SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `next@app/turbopack`: a generated typed React icon for the Next.js App Router and Turbopack.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config and source icons together:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
The generated icon has no `'use client'` directive and is Server Component-compatible. Import it directly in an App Router page or layout:
|
||||
|
||||
```tsx
|
||||
// src/app/page.tsx
|
||||
import {
|
||||
IconsIcon,
|
||||
iconsIconNames,
|
||||
} from '../ui/icons/.svg-sprite/index.js'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Viewer is interactive, so place the React bridge in a separate Client Component:
|
||||
|
||||
```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'),
|
||||
]
|
||||
|
||||
export function IconsViewer() {
|
||||
return <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
```
|
||||
|
||||
Render it from the route's Server Component:
|
||||
|
||||
```tsx
|
||||
// src/app/icon-debug/page.tsx
|
||||
import { IconsViewer } from './IconsViewer'
|
||||
|
||||
export default function IconDebugPage() {
|
||||
return <IconsViewer />
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
153
docs/en/guides/next-app-webpack.md
Normal file
153
docs/en/guides/next-app-webpack.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Next.js App Router Webpack SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `next@app/webpack`: a generated typed React icon for the Next.js App Router and Webpack 5.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config adjacent to its source icons:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
The generated icon has no `'use client'` directive and is Server Component-compatible. Import it directly in an App Router page or layout:
|
||||
|
||||
```tsx
|
||||
// src/app/page.tsx
|
||||
import {
|
||||
IconsIcon,
|
||||
iconsIconNames,
|
||||
} from '../ui/icons/.svg-sprite/index.js'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Viewer is interactive, so place the React bridge in a separate Client Component:
|
||||
|
||||
```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'),
|
||||
]
|
||||
|
||||
export function IconsViewer() {
|
||||
return <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
```
|
||||
|
||||
Render it from the route's Server Component:
|
||||
|
||||
```tsx
|
||||
// src/app/icon-debug/page.tsx
|
||||
import { IconsViewer } from './IconsViewer'
|
||||
|
||||
export default function IconDebugPage() {
|
||||
return <IconsViewer />
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
140
docs/en/guides/next-pages-turbopack.md
Normal file
140
docs/en/guides/next-pages-turbopack.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Next.js Pages Router Turbopack SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `next@pages/turbopack`: a generated typed React icon for the Next.js Pages Router and Turbopack.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config and source icons together:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
Import the generated component and icon-name list into a Pages Router page:
|
||||
|
||||
```tsx
|
||||
// src/pages/index.tsx
|
||||
import {
|
||||
IconsIcon,
|
||||
iconsIconNames,
|
||||
} from '../ui/icons/.svg-sprite/index.js'
|
||||
|
||||
export default function HomePage() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```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:
|
||||
|
||||
```tsx
|
||||
// src/pages/icon-debug.tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../ui/icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export default function IconDebugPage() {
|
||||
return <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
140
docs/en/guides/next-pages-webpack.md
Normal file
140
docs/en/guides/next-pages-webpack.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Next.js Pages Router Webpack SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `next@pages/webpack`: a generated typed React icon for the Next.js Pages Router and Webpack 5.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config adjacent to its source icons:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
Import the generated component and icon-name list into a Pages Router page:
|
||||
|
||||
```tsx
|
||||
// src/pages/index.tsx
|
||||
import {
|
||||
IconsIcon,
|
||||
iconsIconNames,
|
||||
} from '../ui/icons/.svg-sprite/index.js'
|
||||
|
||||
export default function HomePage() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<p>{iconsIconNames.length} icons available</p>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```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:
|
||||
|
||||
```tsx
|
||||
// src/pages/icon-debug.tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../ui/icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export default function IconDebugPage() {
|
||||
return <SpriteViewer sources={sources} title="Project icons" />
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
148
docs/en/guides/react-vite.md
Normal file
148
docs/en/guides/react-vite.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# React Vite SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `react@vite`: a generated typed React component with a Vite-managed SVG asset.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config and source icons together:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
Import the generated component and icon-name list directly:
|
||||
|
||||
```tsx
|
||||
// src/App.tsx
|
||||
import {
|
||||
IconsIcon,
|
||||
iconsIconNames,
|
||||
} from './ui/icons/.svg-sprite/index.js'
|
||||
|
||||
export function App() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon icon="check" width={24} height={24} aria-label="Complete" />
|
||||
<small>{iconsIconNames.length} icons available</small>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
`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:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"types": ["vite/client"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```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:
|
||||
|
||||
```tsx
|
||||
// src/IconsDebugPage.tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('./ui/icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export function IconsDebugPage() {
|
||||
return <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.
|
||||
|
||||
## 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
|
||||
```
|
||||
156
docs/en/guides/react-webpack.md
Normal file
156
docs/en/guides/react-webpack.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# React Webpack SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `react@webpack`: a generated typed React component using Webpack 5 Asset Modules and CSS Modules.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config adjacent to its source icons:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
Import the generated component and icon-name list directly:
|
||||
|
||||
```tsx
|
||||
// src/App.tsx
|
||||
import {
|
||||
IconsIcon,
|
||||
iconsIconNames,
|
||||
} from './ui/icons/.svg-sprite/index.js'
|
||||
|
||||
export function App() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon icon="folder" width={24} height={24} aria-label="Files" />
|
||||
<small>{iconsIconNames.length} icons available</small>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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 generated component also imports `react-component.module.css`. Configure `.module.css` through `css-loader` with modules enabled, plus `style-loader` or `MiniCssExtractPlugin`:
|
||||
|
||||
```js
|
||||
// webpack.config.js (relevant rule)
|
||||
export default {
|
||||
module: {
|
||||
rules: [
|
||||
{
|
||||
test: /\.module\.css$/i,
|
||||
use: ['style-loader', { loader: 'css-loader', options: { modules: true } }],
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```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:
|
||||
|
||||
```tsx
|
||||
// src/IconsDebugPage.tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('./ui/icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export function IconsDebugPage() {
|
||||
return <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.
|
||||
|
||||
## 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',
|
||||
})
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
156
docs/en/guides/standalone-vite.md
Normal file
156
docs/en/guides/standalone-vite.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Standalone Vite SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `standalone@vite`: a native generated Web Component with Vite-managed SVG assets.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config and source icons together:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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`.
|
||||
|
||||
### Production usage
|
||||
|
||||
Register the generated element once, then use `<icons-icon>`:
|
||||
|
||||
```ts
|
||||
// src/main.ts
|
||||
import {
|
||||
defineIconsIconElement,
|
||||
iconsIconNames,
|
||||
} from './ui/icons/.svg-sprite/index.js'
|
||||
|
||||
defineIconsIconElement()
|
||||
console.log('Available icons:', iconsIconNames)
|
||||
```
|
||||
|
||||
```html
|
||||
<icons-icon icon="check" role="img" aria-label="Complete"></icons-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`:
|
||||
|
||||
```css
|
||||
icons-icon {
|
||||
font-size: 24px;
|
||||
color: #2563eb;
|
||||
--icon-color-2: #dbeafe;
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"types": ["vite/client"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Register the Viewer element, import its type, and assign the generated JavaScript manifest to `sources`:
|
||||
|
||||
```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>
|
||||
`
|
||||
|
||||
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.
|
||||
|
||||
## 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
|
||||
```
|
||||
143
docs/en/guides/standalone-webpack.md
Normal file
143
docs/en/guides/standalone-webpack.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Standalone Webpack SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `standalone@webpack`: a native generated Web Component using Webpack 5 Asset Modules.
|
||||
|
||||
## 1. 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`.
|
||||
|
||||
Keep the config adjacent to its source icons:
|
||||
|
||||
```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',
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not add `predev` or `prebuild` hooks to these scripts; that would run generation twice. In CI, replace `latest` with an exact package version.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
Register the generated element once, then use `<icons-icon>`:
|
||||
|
||||
```ts
|
||||
// src/main.ts
|
||||
import {
|
||||
defineIconsIconElement,
|
||||
iconsIconNames,
|
||||
} from './ui/icons/.svg-sprite/index.js'
|
||||
|
||||
defineIconsIconElement()
|
||||
console.log('Available icons:', iconsIconNames)
|
||||
```
|
||||
|
||||
```html
|
||||
<icons-icon
|
||||
icon="check"
|
||||
role="img"
|
||||
aria-label="Complete"
|
||||
style="font-size:24px;color:#16a34a;--icon-color-1:#16a34a"
|
||||
></icons-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.
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only users who need the Viewer or icon previews should install:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Register the Viewer element, import its type, and assign the generated JavaScript manifest to `sources`:
|
||||
|
||||
```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>
|
||||
`
|
||||
|
||||
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.
|
||||
|
||||
## 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',
|
||||
})
|
||||
```
|
||||
|
||||
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@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
|
||||
```
|
||||
171
docs/en/guides/standalone.md
Normal file
171
docs/en/guides/standalone.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Standalone SVG Sprite Quick Start
|
||||
|
||||
This guide targets the exact mode key `standalone`: static HTML or a custom asset pipeline with no generated JavaScript facade.
|
||||
|
||||
## 1. 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.
|
||||
|
||||
Keep the config next to its source icons:
|
||||
|
||||
```text
|
||||
src/ui/icons/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── folder.svg
|
||||
└── svg-sprite.config.json
|
||||
```
|
||||
|
||||
Create a JSON config:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "standalone",
|
||||
"name": "icons"
|
||||
}
|
||||
```
|
||||
|
||||
When `input` is omitted, the generator reads `./icons` next to the config.
|
||||
|
||||
To include SVG files from nested directories, set one glob pattern:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "standalone",
|
||||
"name": "icons",
|
||||
"input": "../assets/icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
An array can mix folders, individual SVG files, and glob patterns:
|
||||
|
||||
```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:
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.json
|
||||
```
|
||||
|
||||
For repeatable local commands, the same temporary CLI can be used from a script:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/ui/icons/svg-sprite.config.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.
|
||||
|
||||
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.
|
||||
|
||||
### Production usage
|
||||
|
||||
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:
|
||||
|
||||
```html
|
||||
<svg width="24" height="24" role="img" aria-label="Complete">
|
||||
<use href="/assets/icons.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.
|
||||
|
||||
## 2. Debug and preview
|
||||
|
||||
This section is optional. Only install the package locally if you need the debug Viewer or an icon preview:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Without a bundler, self-host the browser bundle by copying it from `node_modules` into the deploy output:
|
||||
|
||||
```bash
|
||||
cp node_modules/@gromlab/svg-sprites/dist/viewer-element.js public/debug/viewer-element.js
|
||||
```
|
||||
|
||||
Then provide both public asset URLs through HTML attributes:
|
||||
|
||||
```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:
|
||||
|
||||
```html
|
||||
<script
|
||||
type="module"
|
||||
src="https://unpkg.com/@gromlab/svg-sprites@1.1.5/dist/viewer-element.js"
|
||||
></script>
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user