Balzer Icon

Biblioteca oficial de ícones React do ecossistema Balzer.

Compatível com React 18+, SVG otimizado, tree-shakable, build em ESModule e UMD, com documentação automática via GitHub Pages.

Os SVGs da biblioteca devem usar currentColor em fill e/ou stroke para responder corretamente à prop color do componente Icon.

Homepage: https://cesarbalzer.github.io/balzer-icon/

Package NPM: https://www.npmjs.com/package/balzer-icon/

Instalação

yarn add balzer-icon

ou

npm install balzer-icon

Uso

import { Icon } from 'balzer-icon';

export default function Example() {
  return (
    <Icon name="home" size={24} color="#000" />
  );
}

Estrutura do projeto

balzer-icon/
├── lib/                # Componentes principais
│   └── Icon.tsx
├── lib/svg/           # SVGs base e índice gerado
├── utils/
│   └── generateNames.js  # Script de geração automática
├── docs/              # Documentação (GitHub Pages)
├── dist/              # Build publicado no npm
├── vite.config.ts
├── vite.config.docs.ts
├── package.json

Como adicionar um novo ícone

1. Adicionar o SVG

Coloque o arquivo em:

lib/svg/

Exemplo:

lib/svg/user.svg

Importante:

<path fill="currentColor" />

ou

<path stroke="currentColor" />

Evite cores fixas como fill="#000" ou stroke="#000", porque isso impede que a prop color do componente altere a cor do ícone.

2. Gerar o mapeamento

yarn names

Esse comando atualiza automaticamente a lista de ícones.

3. Testar localmente

yarn dev

Ou visualizar docs:

yarn preview:docs

Build

Build da biblioteca:

yarn build

Output:

dist/

Build da documentação:

yarn build:docs

Output:

docs/

Deploy

Deploy automático ocorre em:

• push na branch main
• criação de release
• execução manual do workflow

Versionamento

Este projeto usa Conventional Commits.

feat

Nova funcionalidade

git commit -m "feat: add new icons"

fix

Correção

git commit -m "fix: correct icon rendering"

chore

Manutenção

git commit -m "chore: update dependencies"

docs

Documentação

git commit -m "docs: update readme"

refactor

Refatoração

git commit -m "refactor: improve icon loader"

breaking change

git commit -m "feat!: change icon API"

Fluxo completo

# adicionar ícone
lib/svg/new-icon.svg

# gerar nomes
yarn names

# testar
yarn dev

# commit
git add .
git commit -m "feat: add new icon"

# push
git push origin main

Desenvolvimento local

yarn install
yarn dev

Arquitetura interna

A biblioteca é construída usando:

• Vite (build tool)
• TypeScript
• Rollup (via Vite)
• SVG como fonte primária
• geração automática de tipos
• output em ESModule e UMD

Fluxo interno:

SVG → generateNames → Icon component → Vite build → dist → npm publish

React é definido como peerDependency para evitar duplicação.

Contribuição

Passos:

git clone https://github.com/CesarBalzer/balzer-icon
cd balzer-icon

yarn install

Criar branch:

git checkout -b feat/new-icons

Adicionar ícones e gerar nomes:

yarn names

Commit:

git commit -m "feat: add new icons"

Push:

git push origin feat/new-icons

Criar Pull Request.

Licença

MIT

Autor: Cesar Balzer