Iconora

A lightweight, customizable React icon package built with TypeScript and SVG. Iconora provides reusable icons with a consistent API and built-in CLI tooling for importing, validating, generating, inspecting, and managing icons.

Iconora can derive icons from external icon repositories such as Lucide and convert them into the Iconora architecture.

Features

• ⚛️ Built for React
• 🔷 Written in TypeScript
• 🎨 Customizable color
• 📏 Customizable size
• ✏️ Customizable stroke width
• 🧩 Standard React SVG props
• 🌳 Tree-shakeable
• 📦 Available as an npm package
• 🪶 Lightweight and dependency-friendly
• 🔄 Automated SVG → TSX generation
• 🧪 SVG validation and project testing
• 🗂️ Automatic icon metadata generation
• 🛠️ CLI tools for icon import, generation, deletion, validation, and metadata inspection

Installation

Install Iconora using npm:

npm install iconora

Or using Yarn:

yarn add iconora

Or using pnpm:

pnpm add iconora

Usage

Import an icon from Iconora:

import { Search } from "iconora";

Use it in a React component:

<Search />

Customization

Size

<Search size={24} />
<Search size={48} />

Color

<Search color="red" />
<Search color="#0f95" />

You can also use CSS classes:

<Search className="text-red-500" />

Stroke Width

<Search strokeWidth={3} />

Combining Props

<Search
  size={48}
  color="#0f95"
  strokeWidth={3}
/>

SVG Props

Iconora icons support standard React SVG properties and event handlers where supported by React.

<Search
  size={32}
  className="my-icon"
  aria-label="Search"
  role="img"
  onClick={handleClick}
/>

Common supported props include:

• id
• style
• className
• role
• aria-label
• onClick
• Standard React SVG attributes

TypeScript

Iconora includes TypeScript declarations for type safety and editor autocomplete.

import {
  Search,
  type IconProps,
} from "iconora";

Icon Source and Generation

Iconora uses SVG files as the source of truth.

icons/*.svg
     │
     ▼
npm run validate
     │
     ▼
npm run generate
     │
     ├── TSX icons
     ├── index.ts
     └── metadata
     │
     ▼
npm run check
     │
     ├── typecheck
     ├── tests
     └── build
     │
     ▼
Iconora

Generated files should normally not be edited manually. Changes should be made to the SVG source files and then regenerated.

Importing Icons from Lucide

Iconora includes a CLI command for importing and deriving SVG icons from the Lucide GitHub repository:

npm run import:lucide

The command imports the Lucide SVG sources into:

icons/

It does not directly create the final React components.

Lucide Import Workflow

npm run import:lucide
npm run validate
npm run generate
npm run check

The responsibilities are:

| Command | Responsibility | |---|---| | npm run import:lucide | Import and derive Lucide SVG sources into Iconora | | npm run validate | Validate Iconora SVG sources | | npm run generate | Convert SVG sources into React/TypeScript components | | npm run check | Run type checking, tests, and production build |

This keeps external icon acquisition separate from Iconora's React component generation.

Adding Icons

Add an SVG to:

icons/

For example:

icons/
├── search.svg
├── x.svg
└── home.svg

The filename determines the generated component name:

search.svg       → Search
x.svg            → X
home.svg         → Home
arrow-left.svg   → ArrowLeft
chevron-down.svg → ChevronDown

1. Validate

npm run validate

2. Generate

npm run generate

This generates the corresponding React/TypeScript component and updates:

src/icons/
src/index.ts
src/metadata/icons.json

For example:

icons/home.svg
     ↓
src/icons/Home.tsx

3. Verify

npm run check

The check command runs:

npm run typecheck
npm run test:run
npm run build

Do not manually edit generated files:

src/icons/
src/index.ts
src/metadata/icons.json

If an icon needs to change, update its SVG source and run npm run generate again.

Icon Metadata

Iconora provides metadata inspection through the getMetadata CLI.

Single Icon

npm run getMetadata -- Search

Icon names are case-insensitive:

npm run getMetadata -- Search
npm run getMetadata -- search
npm run getMetadata -- SEARCH

Multiple Icons

npm run getMetadata -- Search X Home

You can also use:

npm run getMetadata -- --Search --X --Home

All Icons

npm run getMetadata -- --all

Metadata is read from:

src/metadata/icons.json

The command is read-only and does not modify the icon collection.

Removing Icons

Remove an Icon Completely

npm run delete -- Search

This removes the SVG source, generated component, export, and metadata entry for the icon.

Icon names are case-insensitive.

Selective Deletion

Delete only the SVG:

npm run delete -- --Search svg

Delete only the generated TSX:

npm run delete -- --Search tsx

Delete only metadata:

npm run delete -- --Search metadata

Delete multiple parts:

npm run delete -- --Search svg tsx

Selective deletion can leave generated files out of sync. For normal icon removal, use the full deletion command.

Development

Clone the repository:

git clone <repository-url>
cd iconora

Install dependencies:

npm install

Development Commands

Import Lucide Icons

npm run import:lucide

Validate Icons

npm run validate

Generate Icons

npm run generate

Delete an Icon

npm run delete -- IconName

Get Icon Metadata

npm run getMetadata -- IconName

Run Full Project Check

npm run check

Typecheck

npm run typecheck

Run Tests Once

npm run test:run

Run Tests in Development Mode

npm run test

Run Tests in Watch Mode

npm run test:watch

Build the Package

npm run build

For detailed command documentation, see:

docs/commands.md

Project Structure

iconora/
├── icons/
│   ├── search.svg
│   └── x.svg
│
├── src/
│   ├── components/
│   │   └── IconBase.tsx
│   ├── icons/
│   │   ├── Search.tsx
│   │   └── X.tsx
│   ├── metadata/
│   │   ├── icons.json
│   │   └── types.ts
│   ├── types.ts
│   └── index.ts
│
├── scripts/
│   ├── check.ts
│   ├── delete-icons.ts
│   ├── generate-icons.ts
│   ├── get-metadata.ts
│   └── validate-icons.ts
│
├── tests/
│   ├── icons.test.tsx
│   └── setup.ts
│
├── docs/
│   └── commands.md
│
├── .gitignore
├── LICENSE
├── README.md
├── package.json
├── package-lock.json
├── tsconfig.json
└── tsup.config.ts

Production Verification

Before publishing a new version:

npm run validate
npm run generate
npm run check

All commands should complete successfully before publishing.

Roadmap

• [x] Initial npm package setup
• [x] TypeScript support
• [x] React support
• [x] SVG icon architecture
• [x] Initial icons
• [x] Local package testing
• [x] Automated SVG validation
• [x] Automated SVG → TSX generation
• [x] Automatic icon exports
• [x] Automatic icon metadata generation
• [x] Aggregated icon tests
• [x] Type checking
• [x] ESM build
• [x] CommonJS build
• [x] Type declaration generation
• [x] Icon deletion CLI
• [x] Metadata inspection CLI
• [x] Project verification CLI
• [x] Command documentation
• [ ] Expand icon collection
• [ ] Add continuous integration
• [ ] Improve package tooling
• [ ] Expand documentation
• [ ] Build Iconora documentation website

Contributing

Contributions, suggestions, bug reports, and new icon ideas are welcome.

To contribute a new icon:

1. Add the SVG to icons/.
2. Run npm run validate.
3. Run npm run generate.
4. Run npm run check.
5. Submit your changes.

Please do not manually edit generated icon files unless you are working on the generation system itself.

Documentation

Detailed CLI documentation is available in:

docs/commands.md

It covers:

• SVG validation
• Icon generation
• Icon deletion
• Metadata generation
• Metadata inspection
• Project verification
• Type checking
• Testing
• Test watch mode
• Production builds
• Development workflows

License

Iconora is released under the MIT License.

See the LICENSE file for the complete license text.

External Sources

Iconora can derive icon sources from external open-source icon repositories such as Lucide. The licensing and attribution requirements of each upstream source apply to its respective assets.

Made with ❤️ for React developers.

Iconora — Simple icons. Your way.