# svgworm

> CLI that turns a folder of SVG files into type-safe, content-hashed SVG sprites, a manifest and TypeScript types. A thin React adapter (@svgworm/react) renders icons in Server Components with zero client JavaScript. Status: 0.x on npm since 2026-10-13 (`svgworm`, `@svgworm/react`); flags and output can still change in a minor before 1.0.

Use it when a Next.js App Router (or any) app has its own folder of SVG icons and needs: no client JS, icon names checked at compile time, correct colors per icon (mono follows currentColor, multicolor is kept), gradients/masks/filters that render in Chromium, Firefox and WebKit, and byte-identical output on every OS.

Requires Node ^22.20 || >=24.11. Package manager: pnpm.

## How to use it

Fastest path: `svgworm init --yes` (add `--agents-md` to get a svgworm section in AGENTS.md). It detects React/Next.js or Astro (`--framework <react|astro>` overrides; Astro wins when both are dependencies) and writes `svgworm.config.json`, `predev`/`prebuild` scripts and the component (`components/icon.tsx`, or a React-free `components/Icon.astro` for Astro), prints the install commands, and never overwrites a file that differs. Manual steps:

1. Put SVG files in a folder, for example `icons/`.
2. Run `svgworm --source icons`. It writes `public/icons/icons.<hash>.svg` (and `icons.stack.<hash>.svg` when an icon needs it) and, in `svgworm/`, `icons.js`, `icons.d.ts` and `manifest.json`.
3. In a Server Component file: `export const Icon = createIcon(manifest)` with `import { createIcon } from '@svgworm/react'` and `import { manifest } from '../svgworm/icons.js'`.
4. Render `<Icon name="home" />`. The icon is aria-hidden unless `title` or `label` is passed. An invalid name is a type error.
5. Run `svgworm` in `predev` and `prebuild`. In CI, `svgworm check` exits 1 when the committed output is stale. `svgworm watch` rebuilds on every change.
6. Optional: serve `/icons/:file*` with `Cache-Control: public, max-age=31536000, immutable`. With a Next `basePath`, set `--public-path` to include it.

## Non-interactive use

- Commands: `build` (default), `check` (exit 1 if the committed output is stale, writes nothing), `watch` (rebuild on change), `init` (project setup). All take the config flags below; `init` also takes `--framework <react|astro>`, `--component-file <path>`, `--no-component`, `--no-scripts`, `--agents-md`, `--yes`, and prompts only on an interactive terminal.
- Flags: `--config <file>`, `--source <dir>` (repeatable), `--out-dir <dir>`, `--public-path <path>`, `--module-dir <dir>`, `--flatten`, `--json`. Flags override the config file. `--out-dir` needs `--public-path`.
- `--json` prints one JSON document on stdout and nothing else.
- Exit codes: 0 built or check up to date; 1 invalid SVG, name collision or I/O failure (nothing is written), or stale output from `check`; 2 usage or config error, or no SVG files found.
- Config file `svgworm.config.json` has a JSON Schema: https://unpkg.com/svgworm/svgworm.schema.json (also importable as `svgworm/schema.json`). Use it as `"$schema"` in the config file.

## Docs

The full docs as one text file: [llms-full.txt](https://svgworm.com/llms-full.txt).

- [Website](https://svgworm.com): landing page and docs, rendered with svgworm itself (every icon from one hashed sprite)
- [README](https://github.com/jmlweb/svgworm/blob/main/README.md): overview and get started
- [CLI reference](https://svgworm.com/docs/cli/): commands, flags, exit codes
- [Config reference](https://svgworm.com/docs/config/): `svgworm.config.json` keys
- [Next.js setup](https://svgworm.com/docs/nextjs/): manual steps, caching headers, basePath
- [Astro setup](https://svgworm.com/docs/astro/): the generated Icon.astro, caching headers, base
- [Astro agent skill](https://github.com/jmlweb/svgworm/blob/main/skills/svgworm-astro/SKILL.md): step-by-step setup in an Astro app (install: `npx skills add jmlweb/svgworm --skill svgworm-astro`)
- [Agent skill](https://github.com/jmlweb/svgworm/blob/main/skills/svgworm-nextjs/SKILL.md): step-by-step setup in a Next.js app and a fix for every error code (install: `npx skills add jmlweb/svgworm --skill svgworm-nextjs`)
- [Next.js example](https://github.com/jmlweb/svgworm/tree/main/examples/next-app-router): runnable App Router app with Turbopack and a zero-client-JS check
- [Comparison](https://svgworm.com/docs/comparison/): svgworm vs SVGR, @neodx/svg, vite-plugin-icons-spritesheet, with spike numbers and when each is better
- [Output contract](https://github.com/jmlweb/svgworm/blob/main/docs/output-contract.md): exact shape of the generated files and manifest
- [Vision](https://github.com/jmlweb/svgworm/blob/main/docs/vision.md)
- [Decisions (ADRs)](https://github.com/jmlweb/svgworm/tree/main/docs/adr)

## Not supported yet

Several sprites, inline sprite, frameworks other than React and Astro, and a preload hint for the sprite.