Busque em todas as páginas da documentação
Todo backend Node.js acaba dependendo de pacotes que ele não escreveu, e a pergunta que realmente importa não é "existe uma biblioteca para isso" - quase sempre existe - mas sim onde as dependências pertencem, o que um número de versão realmente promete a você, e o que você está assumindo toda vez que adiciona uma.
Esta página é o raciocínio por trás das escolhas documentadas em outras partes desta seção. Noções Básicas de Bibliotecas Essenciais mostra a pilha padrão concreta em torno da qual este cookbook é construído - zod, pino, got / axios, date-fns / Luxon, bullmq / ioredis - e cada uma dessas páginas assume o modelo descrito aqui.
Alguns runtimes enviam "baterias incluídas" - uma grande biblioteca padrão que cobre servidores HTTP, JSON, criptografia, testes e mais como um todo coeso. O Node.js deliberadamente não seguiu esse caminho.
Os módulos core do Node.js (node:fs, node:http, node:crypto, node:test, e outros) são compilados no próprio binário, não precisam de instalação e são mantidos como parte do runtime. Mas o core para bem aquém do que um backend real precisa: não há validação de esquema, nem logger estruturado, nem cliente HTTP com retentativas, nem fila de jobs. Essa lacuna é preenchida pelo userland - o enorme ecossistema de pacotes publicados no npm, instalados em node_modules, e versionados independentemente do próprio Node.
Uma forma útil de visualizar: o core do Node.js é a estrutura, a fundação e a fiação de uma casa - sólida, que suporta carga, improvável de mudar - enquanto o userland é tudo que você escolhe instalar dentro dela: os aparelhos hidráulicos, os eletrodomésticos, os móveis. Tecnicamente, você poderia construir seu próprio de qualquer um desses, mas quase ninguém o faz, porque o mercado já produziu opções bem testadas e bem mantidas para as mais comuns.
import { readFile } from 'node:fs/promises'; // core: sem instalação, vem com o Node
import { z } from 'zod'; // userland: escolhido, instalado, versionadoEssa divisão é o motivo pelo qual "bibliotecas essenciais" é um assunto próprio - a lista de dependências de um backend não é um acidente do que foi instalado ao longo do caminho, é um conjunto de escolhas deliberadas sobre quais lacunas no core valem a pena preencher, e com o quê.
A pergunta de maior alavancagem ao escolher onde a responsabilidade de uma dependência deve começar e terminar é: isso é um limite (boundary) ou é lógica de domínio?
Um limite é qualquer ponto onde os dados cruzam do exterior do controle do seu programa para dentro dele - um corpo de requisição HTTP, uma variável de ambiente, uma mensagem retirada de uma fila, uma resposta de API de terceiros. Limites são exatamente onde bibliotecas de validação, parsing e defensivas como zod mostram seu valor, porque formas não confiáveis e valores não confiáveis chegam lá primeiro. A lógica de negócios/domínio, por outro lado, opera em dados que você já validou e normalizou - geralmente não deve precisar reimportar uma biblioteca de validação ou adivinhar a forma de um payload, porque esse trabalho já aconteceu na borda.
// Limite: valide uma vez, na borda, antes que qualquer outra coisa toque nos dados
const OrderInput = z.object({ sku: z.string(), qty: z.number().int().positive() });
function handleCreateOrder(body: unknown) {
const input = OrderInput.parse(body); // lança exceção em entrada inválida - falha rápido, na borda
return createOrder(input); // a lógica de domínio recebe um valor confiável e tipado
}Esse mesmo instinto de limite se aplica a logging (estruturado, adjacente ao limite - veja pino), requisições HTTP de saída (política de retentativa/timeout pertence ao limite do cliente - veja got / axios), e payloads de fila (valide na entrada, o mesmo que um corpo HTTP).
Por baixo de cada npm install, o versionamento semântico é o contrato que torna um grafo de dependência em constante crescimento gerenciável: uma string de versão MAJOR.MINOR.PATCH promete que releases de patch corrigem bugs sem mudar o comportamento, releases menores adicionam capacidade sem quebrar o uso existente, e apenas um release major tem permissão para quebrar algo. package.json registra um intervalo aceito (^7.2.0); o lockfile (package-lock.json ou equivalente) fixa o grafo exato resolvido que foi realmente instalado e testado - veja Lockfiles & Instalações Reproduzíveis para como esse pinning realmente funciona. Semver é uma promessa que um mantenedor faz sobre seu próprio pacote, no entanto - não é algo que o npm verifica para eles, e um release mal rotulado pode violá-lo.
Cada dependência que você adiciona também adiciona superfície de cadeia de suprimentos (supply chain): código que você não escreveu e não revisa linha por linha, rodando com os mesmos privilégios do seu próprio código, puxado transitivamente por pacotes que você escolheu deliberadamente. Um único npm install pode facilmente resolver para centenas de pacotes transitivos em vários níveis de profundidade - Cadeia de Suprimentos: npm audit & Socket cobre a auditoria desse grafo diretamente; a decisão de bibliotecas essenciais sobre a qual esta página trata está a montante disso - menos dependências diretas, e melhor escolhidas, significam um grafo menor para auditar em primeiro lugar.
O próprio runtime tem estreitado essa lacuna ao longo do tempo: o Node absorveu fetch, um test runner embutido (node:test) e (a partir de linhas LTS recentes) node:sqlite, cada um removendo uma categoria que costumava exigir um pacote de terceiros por padrão. Essa é uma tendência real que vale a pena acompanhar - a resposta padrão correta para "preciso de uma biblioteca para isso" muda à medida que o core absorve mais das solicitações mais comuns do userland, então uma pilha que fazia sentido em uma linha LTS mais antiga vale a pena revisitar periodicamente em vez de assumir como permanente.
Nem toda decisão de "adicionar uma dependência" se parece igual. Uma biblioteca de propósito único e bem definida (zod para validação) é uma aposta muito diferente de um framework grande que agrupa suas próprias opiniões sobre roteamento, DI e configuração (NestJS) - o caso do framework troca mais controle por mais estrutura, e é uma decisão geralmente tomada uma vez no início de um serviço, em vez de incrementalmente.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Apenas core do Node | Zero instalação, zero risco de terceiros, sempre disponível | Falta validação, logging estruturado, retentativas e mais - lacunas reais para preencher você mesmo | Pequenos scripts, ferramentas sem superfície de produção real |
| Biblioteca de propósito único | Pegada pequena, um trabalho claro, fácil de trocar depois | Você mesmo monta e conecta vários deles | A maioria dos serviços de produção - a postura padrão que esta seção documenta |
| Framework empacotado (ex: NestJS) | Convenções consistentes em uma equipe grande, menos conexão individual | Pegada maior, mais difícil trocar uma peça depois, curva de aprendizado mais íngreme | Equipes maiores que valorizam a consistência sobre a flexibilidade incremental |
| Criar sua própria | Exatamente o comportamento que você precisa, sem dependência de manutenção externa | Agora você é responsável por testes, casos extremos e revisão de segurança para sempre | Problemas genuinamente novos sem pacote existente bem mantido |
Ambientes sensíveis a "cold start" (funções serverless, runtimes de edge) adicionam outro eixo: o tamanho de instalação e o custo de importação de uma dependência importam lá de uma forma que não importam para um processo de servidor de longa duração, que é mais um motivo pelo qual "isso precisa de uma biblioteca" vale a pena perguntar antes de "qual biblioteca".
package.json é o mesmo que instalações reproduzíveis." package.json registra um intervalo aceito; apenas o lockfile fixa o grafo de dependência exato resolvido que foi realmente instalado e testado - sem ele, duas instalações do "mesmo" package.json podem resolver de forma diferente.fetch embutido do Node removeu a necessidade de uma biblioteca cliente HTTP." Ele substituiu a necessidade de uma requisição HTTP crua em muitos casos, mas bibliotecas como got ou axios ainda adicionam política de retentativa, interceptadores e modelagem de requisição/resposta que fetch intencionalmente deixa de fora - veja got / axios.Módulos core (node:fs, node:http, e similares) são compilados no binário do Node e não precisam de instalação. Pacotes userland são publicados no npm, instalados em node_modules, e versionados independentemente do próprio Node - a maior parte da capacidade real de um backend vive aqui.
O Node.js manteve deliberadamente seu core pequeno e estável em vez de "baterias incluídas", deixando preocupações de rápida evolução como validação e logging para um ecossistema que pode iterar independentemente do próprio ciclo de lançamento do Node. Ele absorveu algumas das necessidades mais universais ao longo do tempo (fetch, node:test), mas a lacuna de propósito geral permanece intencional.
Pergunte se o problema está em um limite genuíno - entrada não confiável, um sistema externo, uma preocupação transversal como logging - versus ser lógica de negócios interna que uma dependência bem escolhida no limite já deveria ter tornado segura para trabalhar.
Significa validar e normalizar dados uma vez, na borda onde entram no seu programa (um corpo HTTP, uma variável de ambiente, uma mensagem de fila), para que tudo a jusante possa confiar em sua forma em vez de rechecá-la. zod é a ferramenta padrão deste cookbook para essa borda.
Uma versão MAJOR.MINOR.PATCH implica: releases de patch corrigem bugs sem mudança de comportamento, releases menores adicionam capacidade sem quebrar o uso existente, e apenas um release major pode quebrar algo. É uma convenção que os mantenedores optam por seguir, não uma garantia que o npm verifica mecanicamente.
package.json registra um intervalo aceito para cada dependência; o lockfile fixa as versões exatas de todo o grafo de dependência que foi realmente instalado e testado. Sem o lockfile, o mesmo package.json pode resolver para um grafo diferente em uma instalação diferente.
É o conjunto completo de pacotes - diretos e transitivos - que acabam rodando dentro do seu processo como resultado de suas escolhas. Uma única dependência direta pode puxar dezenas de outras que você nunca escolheu explicitamente, cada uma agora parte da sua superfície de segurança e manutenção.
Não totalmente - fetch cobre bem o caso básico de requisição/resposta, mas bibliotecas como got e axios ainda adicionam políticas de retentativa, timeouts ajustados para chamadas de serviço internas e ganchos de interceptação que fetch deixa para você construir.
Quando uma equipe maior se beneficia mais de convenções compartilhadas e impostas (roteamento, injeção de dependência, estrutura de módulos) do que da flexibilidade de escolher e trocar cada peça independentemente - é um compromisso mais pesado, geralmente feito uma vez perto da concepção de um serviço.
Sim, mas raramente - principalmente quando o problema é genuinamente novo e nenhum pacote bem mantido se encaixa, já que criar sua própria solução significa que você agora é responsável por testes, casos extremos e revisão de segurança indefinidamente, trabalho que a comunidade de uma biblioteca mantida já faz.
Em um processo de servidor de longa duração, o custo de importação de uma dependência é pago uma vez na inicialização e amortizado ao longo de um longo tempo de atividade. Em funções serverless ou de edge, esse custo pode ser pago em cada "cold start", tornando o tamanho do pacote e o peso da importação uma preocupação de desempenho muito mais direta.
Popularidade é um sinal, não uma garantia - vale a pena verificar separadamente a atividade de manutenção, a rapidez com que os avisos de segurança são corrigidos e quantos mantenedores um projeto realmente tem antes de tratá-lo como um padrão seguro.
fetch sozinho não cobreVersões da Pilha: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, e TypeScript 5.6+.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026