Sprite

Simple tool to create SVG sprite sheet from SVG icons

[!NOTE] This project is still in active development.

Getting started

Installation

The installation process is pretty much the same as another library, whether you use npm, pnpm, yarn, or bun.

npm i @oviirup/sprite -D

It will install the package with binary sprite

Setup a sprite project

You can initiate a simple project with init command,

npm sprite init

You can also manually create a entry file with .yaml or .json REF as follows ...

{
  "$schema": "https://unpkg.com/@oviirup/sprite/schema.json",
  "name": "lucide-icons",
  "output": "icons.sprite.svg",
  "icons": {
    "home": {
      "content": "<path d='M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8'/><path d='M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 5.999A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z'/>",
      "attributes": {
        "viewBox": "0 0 24 24",
        "fill": "none",
        "stroke": "currentcolor",
        "stroke-linecap": "round",
        "stroke-linejoin": "round",
        "stroke-width": "2"
      }
    }
  }
}

If you want you could also initiate a project with a .yaml file with --yaml flag.

When using the json entry you can use the json schema https://unpkg.com/@oviirup/sprite/schema.json as follows

// icons.json
{
  "$schema": "https://unpkg.com/@oviirup/sprite/schema.json",
  "name": "icon"
}

And you are all ready to go. Now while you are building you can reference the file.

You can also set the entry points in package.json REF as follows...

{
  "sprite": ["icons.sprite.yaml"]
}

Learn more about configuration.

Usage

If you installed it use ...

npm sprite build icons.sprite.yaml

The CLI can pickup configuration from package.json, so you don't need to use any entry point in the CLI. Any entry point defined in the CLI will overwrite the config.

npm sprite build

Or, you can directly use the CLI without installing with npx

npx @oviirup/sprite build icons.yaml

Configuration

You can define the root configuration in package.json with an object of sprite.

Sprite base config

• entries: String | String[] *
  Entries for sprite record (path or glob pattern, relative to cwd)
• watch: Boolean
  Enable watch mode
• cwd: String
  Working directory (default: process.cwd())

Sprite record config

• name: String *
  Name of the sprite project
• output: String *
  Output file without extension, relative to cwd
• prefix: String
  Prefix for icon names, with no empty space
• icons: Record<string,Icon> *
  Icon sets configuration

Icon config

• content: String *
  Inner content of the svg icon
• attributes: Record<string,string>
  SVG attributes
• tags: String[]
  Tags for the icon for search

TypeSafe Icon names

The icon names can be typesafe with a simple trick of typescript.

import type Sprite from './icons.sprite.json';

type IconNames = keyof (typeof IconsSprite)['icons'];

NOTE: This can only be achieved using .json entry.

Contributing & Development

You are welcome to contribute to the project. Please follow the contributing guidelines before making any contribution.

• Fork & clone to local machine
  Fork the repo from GitHub by clicking the fork button at the top-right and clone it...

  git clone https://github.com/username/sprite.git

• Create a new branch
  Please make sure you are not on the main branch before making any changes.

  git checkout -b my-new-branch

• Install dependencies
  This project uses bun.js, although any other package manager can be used as well.

  bun install