Proposta de Nova Biblioteca
Este documento serve como template obrigatório para propor a inclusão de uma nova biblioteca no projeto Smart NX Frontend.
Toda dependência deve passar por esta análise antes de ser adicionada ao repositório principal.
💡 Objetivo: garantir decisões informadas, seguras e sustentáveis sobre bibliotecas externas, considerando aspectos técnicos, estratégicos e legais.
1. Identificação
| Campo | Valor |
|---|---|
| Biblioteca | ex: lodash / dayjs / react-hook-form |
| Versão proposta | ex: 5.3.0 |
| Proponente | ex: Matheus Telles |
| Data | dd/mm/aaaa |
| Tipo de biblioteca | ☐ Utilitária ☐ UI ☐ Network ☐ Observabilidade ☐ Build ☐ Outras: ______ |
2. Contexto e Motivação
Explique por que esta biblioteca é necessária.
- Qual problema ela resolve?
- Por que o código atual não atende de forma eficiente?
- Quais alternativas foram consideradas (nativas ou internas)?
- Qual o impacto esperado em produtividade, qualidade ou manutenibilidade?
Exemplo:
Necessidade de manipulação imutável de objetos complexos com performance previsível.
Alternativas comostructuredClonenão atendem casos com propriedades não enumeráveis.
3. Avaliação Técnica
| Critério | Descrição | Avaliação |
|---|---|---|
| Tamanho (min+gzip) | Impacto estimado no bundle (use bundlephobia.com) | ex: 8.3 kB |
| Tree-shaking | Suporta importações parciais e eliminação de código morto? | ✅ Sim / ❌ Não |
| Atividade recente | Último commit, releases e frequência de manutenção | ex: ativo há 2 semanas |
| Popularidade e comunidade | NPM downloads, GitHub stars, suporte em fóruns | ex: 3M downloads/semana |
| Compatibilidade | Funciona com React/TypeScript/Vite? | ✅ Sim / ❌ Não |
| Segurança | Vulnerabilidades conhecidas (npm audit, snyk) | ✅ Sem riscos / ⚠️ Revisar CVE |
| Licença | Tipo e restrições (MIT, Apache, BSD, etc.) | ex: MIT |
| Alternativas | Outras libs ou soluções próprias | ex: date-fns, luxon, Intl.DateTimeFormat |
4. Análise de Risco
Descreva os principais riscos e mitigações associados à inclusão.
| Tipo | Risco Potencial | Mitigação |
|---|---|---|
| Segurança | Vulnerabilidade futura no pacote | Monitoramento com npm audit no CI/CD |
| Manutenção | Projeto com poucos mantenedores | Revisão periódica e fallback interno |
| Compatibilidade | Conflito com Vite/SSR | Teste piloto antes de merge |
| Performance | Bundle inflado | Importações específicas e lazy load |
5. Plano de Teste e Integração
Descreva como a biblioteca será avaliada e testada antes da adoção definitiva.
- Ambiente de teste / branch de experimentação
- Medição de impacto no bundle (
vite-bundle-visualizer,webpack-bundle-analyzer) - Casos de uso simulados e métricas observadas
- Critérios de aprovação (ex: tempo de build, FPS, tamanho final)
6. Plano de Remoção (Fallback)
Como o projeto se comportará caso a biblioteca precise ser removida?
- Existe plano de fallback (ex.: API nativa ou módulo interno)?
- O código ficará isolado em camada de abstração (
@core/@utils)? - Quais módulos seriam afetados pela remoção?
7. Conclusão e Recomendação
Resumo da decisão proposta:
- ✅ Aprovada para uso em produção
- ⚙️ Aprovada em caráter experimental (feature flag)
- ❌ Rejeitada (não atende critérios técnicos)
Explique brevemente a decisão final e próximos passos (ex.: PR de integração, versão de lançamento, revisão futura).
8. Aprovação
| Responsável | Cargo / Função | Data | Assinatura |
|---|---|---|---|
| Proponente | |||
| Tech Lead / Arquiteto | |||
| Gestão Técnica (opcional) |
Histórico de Revisões
| Data | Autor | Alteração |
|---|---|---|
| 29/10/2025 | @Matheus Telles | Criação do template oficial para propostas de novas bibliotecas. |