Skip to content

Commit 71a8a78

Browse files
Austin1serbAustin1serb
committed
add readme
1 parent 1355cf4 commit 71a8a78

File tree

1 file changed

+199
-0
lines changed

1 file changed

+199
-0
lines changed

‎README.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
<div align="center">
2+
3+
# @react-zero-ui/icon-sprite
4+
5+
</div>
6+
7+
> [!NOTE]
8+
> **Automatically generates an SVG sprite containing only the icons you used in development** - Lucide + custom SVGs.
9+
10+
> **Zero-runtime icon sprites for React.** using Lucide icons and custom SVGs - optimized for dev experience and production performance. Part of the [React Zero-UI](https://github.com/react-zero-ui) ecosystem.
11+
12+
13+
---
14+
15+
## 🧠 What This Library Does
16+
17+
This package gives you:
18+
19+
1. **Full Lucide-React DX in development**
20+
Easy Imports, Instant updates, hot-reloading, JSX props, no caching issues. Use Just like Lucid but import the icon from `@react-zero-ui/icon-sprite` instead of `lucide-react`.
21+
22+
2. **Zero-runtime SVG sprite usage in production**
23+
Replaces every icon component with a `<use href="/icons.svg#id" />` element at build time.
24+
25+
3. **Tree-shaking via static analysis**
26+
Icons are only included in the final sprite if your app actually uses them.
27+
28+
## 🙏 Custom icon support
29+
Just drop SVGs into `app/zero-ui-icons/`, and use the `<CustomIcon/>` component. set the `name` prop to the name of the icon file want to use.
30+
31+
> [!TIP]
32+
>```txt
33+
>📁/public/zero-ui-icons/
34+
> └── dog.svg
35+
>```
36+
>```tsx
37+
>import { CustomIcon } from "@react-zero-ui/icon-sprite";
38+
>//❗The name MUST match the name of the icon file - .svg extension is not needed.
39+
><CustomIcon name="dog" size={24} />
40+
>```
41+
42+
<small>This command builds the icons sprite for production</small>
43+
44+
---
45+
46+
## 📦 Installation
47+
48+
```bash
49+
npm install @react-zero-ui/icon-sprite
50+
```
51+
52+
---
53+
54+
## ❗ Build Command
55+
> [!CAUTION]
56+
> You must run this command before building your app, for `zero-svg` to work properly.
57+
>```bash
58+
>npx zero-svg
59+
>```
60+
61+
---
62+
63+
## 🔨 Usage
64+
65+
### For Lucide Icons:
66+
67+
```tsx
68+
import { ArrowRight, Mail } from "@react-zero-ui/icon-sprite";
69+
70+
<ArrowRight size={24} className="text-gray-600" />
71+
```
72+
73+
### For Custom Icons:
74+
75+
```tsx
76+
import { CustomIcon } from "@react-zero-ui/icon-sprite";
77+
78+
<CustomIcon name="dog" size={32} />
79+
```
80+
---
81+
82+
## 🧪 How It Works (Under the Hood)
83+
84+
### ✅ Development Mode: DX First
85+
86+
In dev, each icon wrapper looks like this:
87+
88+
```tsx
89+
import { ArrowRight as DevIcon } from "lucide-react";
90+
91+
export const ArrowRight = (props) =>
92+
process.env.NODE_ENV === "development" ? (
93+
<DevIcon {...props} />
94+
) : (
95+
<svg {...props}>
96+
<use href={`/icons.svg#arrow-right`} />
97+
</svg>
98+
);
99+
```
100+
101+
This ensures:
102+
103+
* Dev uses Lucide's real React components (`lucide-react`)
104+
* Full props support (e.g. `strokeWidth`, `className`)
105+
* No caching issues from SVG sprites
106+
* No FOUC (Flash of Unstyled Content)
107+
108+
### ⚙️ Production Mode: Minimal Runtime, Maximum Speed
109+
110+
At build time:
111+
112+
1. We scan your codebase for all icons statically using Babel + AST traversal
113+
2. We generate a single SVG sprite sheet (`public/icons.svg`)
114+
3. The wrapper components switch to `<use href="/icons.svg#icon-id" />`
115+
116+
---
117+
118+
## ⚡️ Tooling
119+
120+
To generate everything:
121+
122+
```bash
123+
npx zero-svg
124+
```
125+
126+
This runs the full pipeline:
127+
128+
| Script | Purpose |
129+
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
130+
| `scan-icons.js` | Parse your codebase for used icons (`Icon` usage or named imports) |
131+
| `used-icons.js` | Collects a list of unique icon names |
132+
| `build-sprite.js` | Uses [`svgstore`](https://github.com/DIYgod/svgstore) to generate `icons.svg` from used Lucide + custom SVGs |
133+
| `gen-wrappers.js` | Writes individual `.tsx` wrappers per icon to `src/icons/` |
134+
| `gen-dist.js` | Emits d.ts/types/index.js for publishing |
135+
| `config.js` | Loads your `zero-ui.config.js` if present |
136+
137+
138+
---
139+
<!--
140+
## 📁 Directory Structure
141+
142+
```txt
143+
📂 icon-sprite/
144+
├── 📂 dist/
145+
│ ├── 📂 icons/ # Generated Lucide icon wrappers (TSX)
146+
│ ├── config.js # Final resolved config
147+
│ ├── index.js # Entrypoint (exports Icon components)
148+
├── 📂 scripts/
149+
│ ├── scan-icons.js # AST parser → finds used icons
150+
│ ├── used-icons.js # Stores collected icon names
151+
│ ├── build-sprite.js # Creates the sprite from Lucide + custom
152+
│ ├── gen-wrappers.js # Creates TSX files for icons
153+
│ ├── gen-dist.js # Prepares the package for publishing
154+
├── 📂 src/
155+
│ ├── 📂 icons/ # Same as dist, before compile
156+
│ ├── config.ts # Default + user config merge
157+
├── 📄 README.md
158+
├── 📄 package.json
159+
└── 📄 tsconfig.json
160+
```
161+
162+
--- -->
163+
164+
## ✨ Why This Is Better
165+
166+
* **DX-first**: No flicker. No sprite caching. Live updates.
167+
* **Runtime-free in production**: Sprites are native, fast, lightweight.
168+
* **Built for Next.js / Vite**: No plugin overhead.
169+
* **Minimal install**: No runtime dependency tree. Just React + Lucide.
170+
171+
---
172+
173+
## 🔧 Configuration (`zero-ui.config.js`)
174+
175+
You can override defaults with a root config file:
176+
177+
```ts
178+
// zero-ui.config.js
179+
export default {
180+
ROOT_DIR: "src", // where to scan for custom icon usage (default: "")
181+
SPRITE_PATH: "icons.svg", // public output path
182+
CUSTOM_SVG_DIR: "zero-ui-icons", // folder for your custom SVGs
183+
}
184+
```
185+
186+
---
187+
188+
## 🧠 Final Thoughts
189+
190+
This is one of the **most optimized** icon systems for serious frontends:
191+
192+
* First-class developer experience (DX) with Lucide's React components.
193+
* Production builds with **zero JavaScript**, just SVGs.
194+
* Custom icon support out-of-the-box.
195+
* Strict static analysis = smallest possible bundle.
196+
* Fully compatible with Next.js 15+, Vite, or any modern React stack.
197+
198+
---
199+

0 commit comments

Comments
 (0)