mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
140 lines
3.6 KiB
Markdown
140 lines
3.6 KiB
Markdown
# 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 |
|
|
| `source` | `local` | `local` for source SVG files or `remote` for a `standalone@server` manifest |
|
|
| `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.
|
|
|
|
## Remotely built sprite
|
|
|
|
A consumer config for a server manifest only contains the mode, source, and input:
|
|
|
|
```json
|
|
{
|
|
"mode": "react@vite",
|
|
"source": "remote",
|
|
"input": "https://assets.example/releases/app/svg-sprite.manifest.json"
|
|
}
|
|
```
|
|
|
|
`input` accepts one HTTP(S) URL or local manifest path. The name, description,
|
|
transforms, and generated notice come from the manifest. The generator downloads
|
|
and verifies the matching SVG profile before the adapter creates its normal local
|
|
components, types, and bundler asset.
|
|
|
|
## Server build
|
|
|
|
`standalone@server` combines local paths/globs with HTTP(S) SVG descriptors:
|
|
|
|
```js
|
|
export default {
|
|
mode: 'standalone@server',
|
|
name: 'app',
|
|
input: [
|
|
'./icons/**/*.svg',
|
|
{
|
|
name: 'remote-logo',
|
|
url: 'https://assets.example/logo.svg',
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
The mode creates two content-addressed SVG profiles and `svg-sprite.manifest.json`.
|
|
`sha256` is optional for HTTP inputs; when present, it must be the expected 64-character
|
|
hexadecimal SHA-256 digest and the build verifies the received bytes.
|
|
|
|
## 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).
|