Como avaliar se uma biblioteca é confiável

Você precisa de uma função de slug, acha um pacote no topo do Google, dá npm install, e em trinta segundos a dependência está em produção. O que você não viu: esse pacote arrasta outros doze, um deles não recebe commit há quatro anos, e o mantenedor tem uma conta sem 2FA esperando para ser sequestrada. A maioria dos incidentes de supply chain dos últimos anos começou exatamente assim — não com um ataque sofisticado, mas com alguém adicionando uma dependência sem olhar para ela.

Este guia é a checagem que eu faço antes de adicionar qualquer biblioteca a um projeto sério. Não é paranoia, é higiene: cinco sinais para avaliar se uma biblioteca é confiável, e a pergunta que vem antes de todas elas.

A pergunta antes da pergunta: você precisa mesmo dela?

Toda dependência é um passivo. Ela é superfície de ataque, é uma coisa a mais para atualizar, e é código que você não controla rodando dentro do seu. Às vezes vinte linhas suas resolvem o que o pacote resolve em duzentos KB — o caso clássico foi o left-pad, onze linhas que derrubaram metade do ecossistema npm quando o autor as removeu.

A regra que uso: se a biblioteca economiza um problema real e difícil (parsing de data com timezone, criptografia, um protocolo complexo), vale. Se ela só embrulha algo que a linguagem já faz, escreva você mesmo. Menos dependências não é pobreza — é uma feature.

Sinal 1: manutenção

Abra o repositório e olhe a data do último release e do último commit. Um pacote sem release há dois anos não é necessariamente ruim (código pequeno e estável existe), mas combinado com issues acumuladas vira bandeira vermelha. Veja a razão entre issues abertas e fechadas, e se os pull requests recebem resposta ou morrem no vácuo.

O fator mais ignorado é o bus factor: quantas pessoas realmente mantêm aquilo? Um único mantenedor cansado é o cenário mais comum de abandono — e de comprometimento, porque uma conta basta para envenenar o pacote inteiro.

Sinal 2: adoção

Downloads semanais e número de dependentes dizem quanta gente já apostou naquele código. Não é prova de qualidade — popularidade não é correção — mas tem um efeito prático: bibliotecas muito usadas têm mais olhos sobre elas, então bugs e vulnerabilidades aparecem e são corrigidos mais rápido. Um pacote com 10 milhões de downloads e um com 200 não merecem o mesmo nível de confiança cega.

Sinal 3: qualidade do código

Aqui vale abrir o capô. Tem testes? Tem CI rodando verde? Tem tipos (ou @types)? Tem changelog de verdade, ou cada versão é um pulo no escuro? Documentação que explica o porquê, não só a API, costuma indicar um mantenedor que pensa no usuário. Para entender o que você está prestes a puxar, o package.json e o lockfile são o mapa — colá-los no formatador de JSON deixa a árvore de dependências e as versões legíveis o suficiente para você ver o que cada install realmente traz.

# o que essa lib arrasta de verdade
npm ls react
# vulnerabilidades conhecidas na árvore inteira
npm audit

Sinal 4: segurança e dependências transitivas

npm audit é o primeiro passo, não o último — ele cruza sua árvore com bancos de CVE conhecidos. Vale checar também OSV ou Snyk para um histórico mais completo. O ponto cego de quase todo mundo são as dependências transitivas: o pacote que você adicionou pode ser impecável, mas ele depende de outros, que dependem de outros, e o seu risco é a soma da árvore inteira, não da raiz.

Some a isso os riscos de supply chain propriamente ditos: typosquatting (o pacote expresss com três esses), pacotes que executam scripts no postinstall, e mantenedores comprometidos publicando uma versão maliciosa. Foi assim com o incidente do xz: meses de engenharia social para inserir um backdoor numa dependência de baixo nível em que todo mundo confiava.

Sinal 5: licença

A parte chata que vira problema jurídico. Uma licença GPL numa lib que você vai linkar a um produto fechado pode te obrigar a abrir seu código; uma licença ausente significa "todos os direitos reservados" por padrão, e não te dá permissão de uso. MIT, Apache-2.0 e BSD são as opções tranquilas para a maioria dos projetos. Cheque antes de integrar, não depois que o jurídico perguntar. Se você quer entender melhor o lado de quem publica esses pacotes — e por que tantos são mantidos por uma pessoa só nas horas vagas —, vale a leitura sobre como contribuir com open source.

Perguntas frequentes

Quantos downloads uma biblioteca precisa ter para eu confiar?

Não existe número mágico. Downloads são um sinal de "muitos olhos", não de qualidade. Use a popularidade como um entre cinco critérios: uma lib com milhões de downloads, manutenção ativa e licença clara é uma aposta segura; uma com muitos downloads mas abandonada há três anos, nem tanto. Pondere o conjunto.

npm audit garante que minha dependência é segura?

Não. Ele só compara sua árvore com vulnerabilidades já conhecidas e publicadas. Um pacote pode ter um zero-day, um backdoor recém-inserido ou um mantenedor comprometido e passar limpo no audit. Trate o resultado como piso, não teto, e combine com OSV/Snyk e com a checagem manual de manutenção.

Vale a pena escrever meu próprio código em vez de usar uma lib?

Quando o problema é pequeno e bem definido, quase sempre sim. Vinte linhas que você entende e mantém valem mais do que um pacote que arrasta uma árvore de transitivas e vira dívida de atualização. Reserve as dependências para problemas genuinamente difíceis: criptografia, datas, parsing complexo.

Como avalio dependências transitivas que eu não escolhi?

Rode npm ls para enxergar a árvore inteira e npm audit para cruzar com CVEs. Lockfiles (package-lock.json, pnpm-lock.yaml) fixam exatamente quais versões transitivas entram, o que torna seus builds reproduzíveis e auditáveis. Sem lockfile, cada install pode trazer uma versão diferente lá no fundo da árvore.

O que levar deste guia

Avaliar uma biblioteca não é desconfiar de tudo — é gastar dez minutos antes de assumir um compromisso de anos. Comece perguntando se você precisa mesmo dela. Depois olhe manutenção, adoção, qualidade do código, segurança (incluindo as transitivas) e licença. Fixe versões com lockfile, rode npm audit no CI e audite antes de adicionar, não depois do incidente. Cada dependência que você não adiciona é uma que nunca vai te acordar às três da manhã.