Configuration

Each config file describes one independent sprite. The CLI does not discover config files automatically, so always pass the path explicitly:

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:

{
  "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:

{
  "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:

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:

export default {
  mode: 'react@vite',
  name: 'icons',
  input: './icons',
}

Pass the path to the .js file to the CLI just like a JSON file:

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:

npm install --save-dev @gromlab/svg-sprites

Use defineSpriteConfig:

import { defineSpriteConfig } from '@gromlab/svg-sprites'

export default defineSpriteConfig({
  mode: 'react@vite',
  name: 'icons',
  input: './icons',
})

Alternatively, use satisfies with a type-only import:

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:

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.

3.6 KiB Raw Permalink Blame History