svghub

v0.1.4

Published

2 days ago

Cross-framework SVG icon library — one source of truth, native rendering for web (Custom Element), React Native, LynxJS, and VS Code.

0High
0Medium
0Low

bastndev

icons svg icon-library react-native lynxjs web-components

A tiny, framework-agnostic SVG icon library. One source of truth for your icon set: a typed JavaScript registry, standalone SVG files, and a native web component — with a build pipeline ready for React Native, LynxJS, and VS Code.

npm i svghub

✨ Why Svghub?

Most icon libraries force you to choose between a giant React-only package, hand-copied SVGs, or a runtime that downloads icons over the network. Svghub takes a different approach:

Framework-agnostic core — icons live as plain data (name, viewBox, paths) in src/core/icons.gen.ts.
Native web component — drop in <svghub-icon name="github"> anywhere HTML runs. No framework needed.
Typed API — IconName, IconData, and getIcon() are fully typed out of the box.
Standalone SVGs — every icon is also published under svg/<name>.svg for design tools or static sites.
Build-once pipeline — add an SVG to icons/<category>/ and bun run build regenerates everything.

📦 Installation

# npm
npm i svghub

# yarn
yarn add svghub

# pnpm
pnpm add svghub

# bun
bun add svghub

🚀 Quick Start

Web Component (no framework)

Import the component once to register <svghub-icon>:

import 'svghub/web';

Then use it anywhere in your HTML or JSX:

<svghub-icon name="github" size="32" color="#C49A6C" stroke-width="1.5"></svghub-icon>

JavaScript / TypeScript API

import { icons, getIcon, type IconName, type IconData } from 'svghub';

const github = getIcon('github');
// {
//   name: 'github',
//   category: 'social',
//   viewBox: '0 0 24 24',
//   paths: [ ... ]
// }

const names: IconName[] = Object.keys(icons) as IconName[];

Static SVG files

<img src="node_modules/svghub/svg/github.svg" alt="GitHub" width="24" />

🧩 Web Component API

The <svghub-icon> custom element is registered automatically when you import svghub/web.

| Attribute | Default | Description | | -------------- | -------------- | ------------------------------------------------------------- | | name | — | Icon identifier (e.g. github, x, instagram). | | size | 24 | Width and height of the rendered SVG. | | color | currentColor | Stroke or fill color. | | stroke-width | 2 | Stroke width for outline icons. |

Manual registration

If you need a different tag name, import the element class and register it yourself:

import { SvghubIconElement, register } from 'svghub/web';

register('my-icon'); // now use <my-icon name="github">

🎨 Framework examples

React

import 'svghub/web';

export const SocialLinks = () => (
  <a href="https://github.com/bastndev/svghub">
    <svghub-icon name="github" size="24" />
  </a>
);

Vue

<script setup>
import 'svghub/web';
</script>

<template>
  <svghub-icon name="github" size="24" />
</template>

Svelte

<script>
  import 'svghub/web';
</script>

<svghub-icon name="github" size="24" />

Vanilla JS

<!doctype html>
<html>
  <head>
    <script type="module">
      import 'svghub/web';
    </script>
  </head>
  <body>
    <svghub-icon name="github"></svghub-icon>
  </body>
</html>

🗂️ Available icons

All icons are grouped by category. The current set lives under icons/social/ and icons/bottom-bar/:

| Icon | Name | Category | | --------------- | ------------------- | ---------- | | Facebook | facebook | social | | GitHub | github | social | | Instagram | instagram | social | | LinkedIn | linkedin | social | | TikTok | tiktok | social | | X (Twitter) | x | social | | YouTube | youtube | social | | - | - | - | | Home outline | home-outline | bottom-bar | | Home solid | home-solid | bottom-bar | | Message outline | message-outline | bottom-bar | | Message solid | message-solid | bottom-bar | | Plus | plus | bottom-bar | | User outline | user-outline | bottom-bar | | User solid | user-solid | bottom-bar | | Wallet outline | wallet-outline | bottom-bar | | Wallet solid | wallet-solid | bottom-bar |

New categories are created automatically by adding a subfolder under icons/.

🛠️ Development

Scripts

# Generate icon data from icons/ into src/core/icons.gen.ts and svg/
bun run build:icons

# Full build: icons + TypeScript bundles (ESM + CJS + types)
bun run build

# Clean generated files
bun run clean

# Run smoke tests
bun run test

Project structure

svghub/
├── icons/                  # Source of truth — add .svg files here
│   └── social/
│       ├── github.svg
│       └── ...
├── src/
│   ├── core/
│   │   ├── types.ts        # IconData interface
│   │   ├── icons.gen.ts    # Generated icon registry
│   │   └── index.ts        # Core API: getIcon, icons, types
│   └── web/
│       ├── icon-element.ts # <svghub-icon> custom element
│       └── index.ts        # Web entry + auto-registration
├── svg/                    # Generated standalone SVG files
├── scripts/
│   └── build-icons.ts      # Icon generator
└── test/
    └── smoke.mjs           # ESM/CJS smoke tests

Adding a new icon

Drop an SVG into icons/<category>/<name>.svg.
Make sure it has a viewBox attribute.
Run bun run build.
Verify the output in src/core/icons.gen.ts and svg/.

The generator reads viewBox, <path d="...">, and root-level fill mode. Outline presentation is normalized, while fill="currentColor" and an optional fill-rule="evenodd" preserve solid icons.

See icons/icons.md for the full contributor guide.

📤 Publishing

bun run build
npm version <patch|minor|major>
npm publish

prepublishOnly runs the full build automatically.

🧪 Testing

Svghub ships with a small smoke test suite that verifies:

The icon registry is non-empty.
Specific icons are present.
Dead canvas-bounds paths are stripped.
Both ESM and CJS builds expose the same API.

bun run test