🔗 Quick Links

• 📍 O que é o projeto
• ⚙️ Instalação
• 🚀 Como rodar localmente
• 🧪 Como testar
• 🧪 Testando o Pacote Localmente
• 📦 Deploy no NPM
• 🤝 Contribuindo

📍 O que é o projeto

Turbo-UI é uma biblioteca de componentes de interface de usuário (UI) desenvolvida especificamente para simplificar a construção e personalização de interfaces. A biblioteca fornece uma coleção abrangente de componentes React baseados em Material-UI, oferecendo uma experiência robusta e interativa.

Características principais

• ⚙️ Componentes customizados baseados no MUI/Material
• 🔩 TypeScript para segurança de tipos e manutenibilidade
• 🧩 Modularidade com componentes React reutilizáveis
• 🧪 Testes com Vitest e Testing Library
• ⚡️ Performance otimizada com Vite
• 📚 Storybook para documentação e visualização de componentes

⚙️ Instalação

1. Instalar o pacote

Na sua aplicação React, instale a dependência:

npm install @rede-ancora/turbo-ui

2. Configurar os Providers

Após instalar, configure os Providers necessários na sua aplicação:

// App.tsx
import { ProviderComponent } from '@rede-ancora/turbo-ui'
import { ToastProvider } from '@rede-ancora/turbo-ui'

return (
    <ProviderComponent theme={themeShell}>
        <ToastProvider>
            {children}
        </ToastProvider>
    </ProviderComponent>
)

3. Usar os componentes

import { Button } from '@rede-ancora/turbo-ui'

export default function Example() {
    return (
        <Button>Clique aqui</Button>
    )
}

🚀 Como rodar localmente

Para desenvolver e visualizar os componentes localmente, utilize o Storybook:

Pré-requisitos

• Node.js (versão 10 ou superior)
• npm ou yarn

Executar o Storybook

npm install
npm run storybook

O Storybook estará disponível em http://localhost:6006

Build do Storybook

Para gerar uma build estática do Storybook:

npm run build-storybook

🧪 Como testar

Execute os testes unitários do projeto:

npm test

Executar lint

Verifique o código com ESLint:

npm run lint

Build do projeto

Para gerar a build de produção:

npm run build

🧪 Testando o Pacote Localmente

Antes de publicar alterações no NPM, é essencial testar o pacote localmente. Existem duas formas principais:

🔗 Método 1: Usando npm link (Recomendado para desenvolvimento contínuo)

Este método cria um link simbólico entre o pacote local e o projeto que o utiliza, permitindo testar alterações em tempo real.

Passo 1: Criar o link no pacote turbo-ui

No diretório raiz do projeto turbo-ui:

npm link

Passo 2: Linkar no projeto de teste

No diretório do projeto onde você deseja testar:

npm link @rede-ancora/turbo-ui

Passo 3: Remover o link (quando terminar)

No projeto de teste:

npm unlink @rede-ancora/turbo-ui
npm install @rede-ancora/turbo-ui

No diretório do turbo-ui (opcional):

npm unlink

📦 Método 2: Usando npm pack (Recomendado para testes finais)

Este método cria um arquivo .tgz que simula exatamente como o pacote será publicado no NPM.

Passo 1: Criar o pacote

No diretório raiz do projeto turbo-ui:

npm pack

Isso criará um arquivo .tgz (ex: rede-ancora-turbo-ui-4.0.0.tgz).

Passo 2: Instalar no projeto de teste

npm install /caminho/para/turbo-ui/rede-ancora-turbo-ui-4.0.0.tgz

Ou usando caminho relativo:

npm install ../turbo-ui/rede-ancora-turbo-ui-4.0.0.tgz

Passo 3: Limpar após os testes

npm uninstall @rede-ancora/turbo-ui
npm install @rede-ancora/turbo-ui

E delete o arquivo .tgz criado.

📝 Qual método usar?

• npm link: Use quando estiver desenvolvendo ativamente e precisar ver alterações em tempo real
• npm pack: Use para um teste final antes de publicar, pois simula exatamente como o pacote será instalado do NPM

📦 Deploy no NPM

Esta seção descreve o processo de publicação do pacote @rede-ancora/turbo-ui no NPM.

🔹 Versão v3

Para atualizar componentes da versão v3:

1. Trabalhe na branch correta:

   git checkout turbo-ui-v3

2. Faça suas alterações e teste localmente

3. Publique no NPM:

   npm run publish_v3

4. Instalação: Para instalar a versão v3:

   npm i @rede-ancora/turbo-ui@3

🔹 Versão v4

Para atualizar componentes da versão v4 (versão principal):

1. Trabalhe na branch principal:

   git checkout main

2. Faça suas alterações e teste localmente

3. Escolha o comando de publicação apropriado:

   • Correções de bugs:

     npm run publish_bug

   • Novas funcionalidades e melhorias:

     npm run publish_feature

   • Nova versão:

     npm run publish_version

   • Versão beta:

     npm run publish_beta

4. Instalação: Para instalar a versão v4:

   npm i @rede-ancora/turbo-ui

   ou

   npm i @rede-ancora/turbo-ui@latest

⚠️ Notas Importantes

• ⚠️ Sempre verifique a branch correta antes de fazer alterações e publicar
• ⚠️ Teste localmente antes de publicar no NPM (veja seção acima)
• ⚠️ Use o comando apropriado conforme o tipo de alteração
• ⚠️ Versão v3 utiliza a branch turbo-ui-v3 e o comando publish_v3
• ⚠️ Versão v4 utiliza a branch main e os comandos específicos conforme o tipo de publicação

🤝 Contribuindo

Contribuições são bem-vindas! Para contribuir:

1. Faça um Fork do repositório

2. Clone localmente:

3. Crie uma nova branch:

   git checkout -b new-feature-x

4. Faça suas alterações e teste localmente

5. Faça o commit usando Conventional Commits:

   git commit -m 'TSTO32@fix: add turbo-ui package'

6. Push para o repositório:

   git push origin new-feature-x

7. Envie um Pull Request descrevendo claramente as alterações

Após a aprovação do PR, consulte a seção 📦 Deploy no NPM para publicar as alterações.

👏 Desenvolvido por

• Mauri Costa
• Gabriel Aquino

Voltar ao topo