svg-sprites/docs/en/guides/standalone-vite.md

# SVG Sprite for Vite Without a Framework

A quick guide to creating an SVG sprite in a Vite application without a framework.

## Generate the sprite

Choose a directory for the future SVG sprite, for example `assets/app-icons`, and create `svg-sprite.config.json` inside it. In `input`, specify the path to existing SVG files relative to the configuration file. There is no need to move or copy the icons.

Example configuration:

```json
{
  "mode": "standalone@vite",
  "name": "app",
  "input": "../svg-icons/**/*.svg"
}
```

The package does not need to be a project dependency: generation runs through `npx`.

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 @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
    "predev": "npm run sprites",
    "dev": "vite",
    "prebuild": "npm run sprites",
    "build": "vite build"
  }
}
```

## Use the sprite

The value `name: "app"` creates the `<app-icon>` element.

Create the entry point `assets/app-icons/index.ts`:

```ts
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
<app-icon icon="icon-name" role="img" aria-label="Done"></app-icon>
```

The `icon` value is the source SVG filename without the extension. Set its size and colors with CSS:

```css
app-icon {
  font-size: 24px;
  color: #334155;
  --icon-color-2: #f59e0b;
}
```

A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`. Viewer shows the variables you need.

Vite automatically adds `sprite.svg` to the production build. You do not need to copy it to `public`.

## 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 and is installed separately:

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

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 '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'

const viewer = document.querySelector<SpriteViewerElement>('gromlab-sprite-viewer')!
viewer.sources = [spriteManifest]
```

Run `npm run dev` and open `/svg-sprite.html`.

Viewer is not required for `<app-icon>` and is not imported by the application's main code.
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`# SVG Sprite for Vite Without a Framework`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`A quick guide to creating an SVG sprite in a Vite application without a framework.`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`## Generate the sprite`
sync 2026-07-14 16:11:39 +03:00
feat: добавить поддержку 20 framework exact modes Добавлены exact modes: - vue@vite и vue@webpack - nuxt@vite и nuxt@webpack - svelte@vite, svelte@webpack и sveltekit@vite - angular@application и angular@webpack - astro@vite - solid@vite, solid@webpack и solid-start@vite - preact@vite и preact@webpack - qwik@vite - lit@vite и lit@webpack - alpine@vite и alpine@webpack Для каждого mode реализованы изолированный adapter, нативный framework-компонент, declarations, manifest, CSS и внешний asset URL. Добавлены production integration-стенды с генерацией, typecheck, сборкой и Playwright-проверкой рендера спрайта и Viewer. Обновлены Viewer, RU/EN-гайды, README, technical reference и AI skills. Итоговая матрица включает 29 exact modes. Проверки: - 48 unit-тестов - 29 integration E2E-тестов 2026-07-15 16:56:44 +03:00			Choose a directory for the future SVG sprite, for example `assets/app-icons`, and create `svg-sprite.config.json` inside it. In `input`, specify the path to existing SVG files relative to the configuration file. There is no need to move or copy the icons.
sync 2026-07-14 16:11:39 +03:00
feat: добавить поддержку 20 framework exact modes Добавлены exact modes: - vue@vite и vue@webpack - nuxt@vite и nuxt@webpack - svelte@vite, svelte@webpack и sveltekit@vite - angular@application и angular@webpack - astro@vite - solid@vite, solid@webpack и solid-start@vite - preact@vite и preact@webpack - qwik@vite - lit@vite и lit@webpack - alpine@vite и alpine@webpack Для каждого mode реализованы изолированный adapter, нативный framework-компонент, declarations, manifest, CSS и внешний asset URL. Добавлены production integration-стенды с генерацией, typecheck, сборкой и Playwright-проверкой рендера спрайта и Viewer. Обновлены Viewer, RU/EN-гайды, README, technical reference и AI skills. Итоговая матрица включает 29 exact modes. Проверки: - 48 unit-тестов - 29 integration E2E-тестов 2026-07-15 16:56:44 +03:00			`Example configuration:`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			```json
			`{`
			`"mode": "standalone@vite",`
			`"name": "app",`
			`"input": "../svg-icons/*/.svg"`
sync 2026-07-14 16:11:39 +03:00			`}`
			```

feat: добавить поддержку 20 framework exact modes Добавлены exact modes: - vue@vite и vue@webpack - nuxt@vite и nuxt@webpack - svelte@vite, svelte@webpack и sveltekit@vite - angular@application и angular@webpack - astro@vite - solid@vite, solid@webpack и solid-start@vite - preact@vite и preact@webpack - qwik@vite - lit@vite и lit@webpack - alpine@vite и alpine@webpack Для каждого mode реализованы изолированный adapter, нативный framework-компонент, declarations, manifest, CSS и внешний asset URL. Добавлены production integration-стенды с генерацией, typecheck, сборкой и Playwright-проверкой рендера спрайта и Viewer. Обновлены Viewer, RU/EN-гайды, README, technical reference и AI skills. Итоговая матрица включает 29 exact modes. Проверки: - 48 unit-тестов - 29 integration E2E-тестов 2026-07-15 16:56:44 +03:00			The package does not need to be a project dependency: generation runs through `npx`.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			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:
sync 2026-07-14 16:11:39 +03:00
			```json
			`{`
			`"scripts": {`
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`"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"`
sync 2026-07-14 16:11:39 +03:00			`}`
			`}`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`## Use the sprite`

			The value `name: "app"` creates the `<app-icon>` element.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Create the entry point `assets/app-icons/index.ts`:
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			```ts
			`export * from './.svg-sprite/index.js'`
			```
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Register the element in `src/main.ts`:
sync 2026-07-14 16:11:39 +03:00
			```ts
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`import { defineAppIconElement } from '../assets/app-icons'`
			`import './style.css'`

			`defineAppIconElement()`
sync 2026-07-14 16:11:39 +03:00			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`Use the icon in HTML:`

sync 2026-07-14 16:11:39 +03:00			```html
feat: добавить поддержку 20 framework exact modes Добавлены exact modes: - vue@vite и vue@webpack - nuxt@vite и nuxt@webpack - svelte@vite, svelte@webpack и sveltekit@vite - angular@application и angular@webpack - astro@vite - solid@vite, solid@webpack и solid-start@vite - preact@vite и preact@webpack - qwik@vite - lit@vite и lit@webpack - alpine@vite и alpine@webpack Для каждого mode реализованы изолированный adapter, нативный framework-компонент, declarations, manifest, CSS и внешний asset URL. Добавлены production integration-стенды с генерацией, typecheck, сборкой и Playwright-проверкой рендера спрайта и Viewer. Обновлены Viewer, RU/EN-гайды, README, technical reference и AI skills. Итоговая матрица включает 29 exact modes. Проверки: - 48 unit-тестов - 29 integration E2E-тестов 2026-07-15 16:56:44 +03:00			`<app-icon icon="icon-name" role="img" aria-label="Done"></app-icon>`
sync 2026-07-14 16:11:39 +03:00			```

feat: добавить поддержку 20 framework exact modes Добавлены exact modes: - vue@vite и vue@webpack - nuxt@vite и nuxt@webpack - svelte@vite, svelte@webpack и sveltekit@vite - angular@application и angular@webpack - astro@vite - solid@vite, solid@webpack и solid-start@vite - preact@vite и preact@webpack - qwik@vite - lit@vite и lit@webpack - alpine@vite и alpine@webpack Для каждого mode реализованы изолированный adapter, нативный framework-компонент, declarations, manifest, CSS и внешний asset URL. Добавлены production integration-стенды с генерацией, typecheck, сборкой и Playwright-проверкой рендера спрайта и Viewer. Обновлены Viewer, RU/EN-гайды, README, technical reference и AI skills. Итоговая матрица включает 29 exact modes. Проверки: - 48 unit-тестов - 29 integration E2E-тестов 2026-07-15 16:56:44 +03:00			The `icon` value is the source SVG filename without the extension. Set its size and colors with CSS:
sync 2026-07-14 16:11:39 +03:00
			```css
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`app-icon {`
sync 2026-07-14 16:11:39 +03:00			`font-size: 24px;`
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`color: #334155;`
			`--icon-color-2: #f59e0b;`
sync 2026-07-14 16:11:39 +03:00			`}`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`. Viewer shows the variables you need.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Vite automatically adds `sprite.svg` to the production build. You do not need to copy it to `public`.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`## Debug and preview`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`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:`
sync 2026-07-14 16:11:39 +03:00
			```bash
			`npm install --save-dev @gromlab/svg-sprites`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			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`:
sync 2026-07-14 16:11:39 +03:00
			```ts
			`import '@gromlab/svg-sprites/viewer/element'`
			`import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'`
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'`
sync 2026-07-14 16:11:39 +03:00
			`const viewer = document.querySelector<SpriteViewerElement>('gromlab-sprite-viewer')!`
			`viewer.sources = [spriteManifest]`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Run `npm run dev` and open `/svg-sprite.html`.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Viewer is not required for `<app-icon>` and is not imported by the application's main code.