# tiny-isprite 2.2.0 — package quick start

The npm package generates SVG sprites and provides a React Icon component.
The separate online editor recolors SVGs and exports optional fill animations.
You can use the package without opening the editor. CLI: Node.js 18+.
React component: React 17, 18 or 19.

## Install and generate

```sh
npm install tiny-isprite@2.2.0
```

Create `icons/star.svg` with a viewBox:

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path fill="currentColor" d="M12 2L22 22H2Z"/>
</svg>
```

From the project root:

```sh
npx build-sprite ./icons ./public/sprite.svg --manifest ./src/generated/sprite.js
```

In a React component saved under `src/`:

```jsx
import { Icon } from "tiny-isprite";
import sprite from "./generated/sprite.js";

export function Star() {
  return (
    <Icon name="star" spriteUrl={sprite.url} prefix={sprite.prefix} size={32} />
  );
}
```

Serve `public/` at your site's root. The generator writes a mutable sprite.svg
alias, a content-hashed SVG and an importable manifest. Use the manifest URL to
pick up regenerated sprites; do not hardcode an old hash. `name` is the source
filename without `.svg` or the symbol prefix. `spriteUrl` enables external mode.

## Choose a color mode

| Goal                                         | CLI options                                                      | Result                                                                                                                      |
| -------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Theme monochrome fills with CSS color        | Default options                                                  | Monochrome explicit fills become currentColor; multicolor icons keep their colors.                                          |
| Keep the original colors                     | --preserve-colored                                               | Preserve monochrome fills too; multicolor icons are already preserved by default.                                           |
| Edit fills and strokes through CSS variables | --use-css-vars (monochrome), or --use-css-vars --all (all icons) | Generate editable named paint variables and a stylesheet. Native currentColor and paint-server references remain unchanged. |

## Useful CLI flags

- `--watch`: regenerate when source SVG files change.
- `--prefix <prefix>`: symbol prefix, default `icon-`.
- `--public-path <url>`: public asset directory, default `/`; end with `/`.
- `--manifest <file>`: location for the generated importable module.
- `--preserve-colored`: preserve original monochrome fills.
- `--use-css-vars`: generate editable variables for monochrome icons.
- `--all`: with `--use-css-vars`, generate variables for all icon colors.
- `--minify`: collapse SVG whitespace.

For example:

```sh
npx build-sprite ./icons ./public/assets/sprite.svg --manifest ./src/generated/sprite.js --public-path /assets/ --use-css-vars --all --minify
```

The manifest gets `cssUrl` when CSS-variable generation is enabled by
`--use-css-vars` or `--all`. Load that stylesheet in your app, for example
`<link rel="stylesheet" href={sprite.cssUrl} />`. Override generated variable
names on the Icon or its wrapper. Native currentColor inherits CSS `color`.

External SVG use must be served from the same origin as the page for reliable
browser support. An asset CDN on another origin may be blocked by the browser;
serve the sprite through your own origin or an origin-preserving proxy.

Icon accepts className, including Tailwind classes for currentColor. The npm
Icon does not accept a style prop; apply CSS variables through a class or styled
wrapper. The editor's standalone generated React component has a separate API.
TypeScript declarations are included; import the exported type with
`import type { IconProps } from 'tiny-isprite'`.

## Browser generation API

```js
import { buildSpriteContent } from "tiny-isprite/browser";
const { sprite, css } = await buildSpriteContent({
  icons: [{ name: "star.svg", content: trustedSvgMarkup }],
  prefix: "icon-",
  useCssVars: true,
});
```

This API returns strings; it does not sanitize untrusted SVG, write files or
provide content-hashed delivery. The caller handles these responsibilities.

## Editor and agent access

[Open the editor](https://tiny-isprite.com/editor/). The editor needs JavaScript. Its WebMCP commands additionally require a compatible
browser/client; a search-only or HTTP-fetch agent cannot execute them. Plain HTTP
readers can use this guide, llms.txt and the normal static homepage. Requests with
`Accept: text/markdown` also receive Markdown on the homepage, documentation,
editor entry and Orbit demo.
The npm Icon API does not include the editor's animation runtime.

- [README for 2.2.0](https://github.com/Dynation/tiny-isprite/blob/v2.2.0/README.md)
- [CHANGELOG for 2.2.0](https://github.com/Dynation/tiny-isprite/blob/v2.2.0/CHANGELOG.md)
- [Editor tool guide](https://tiny-isprite.com/agent-guide.md)
- [Orbit export example](https://tiny-isprite.com/demos/orbit/)
- [Agent index](https://tiny-isprite.com/llms.txt)