Melhores Práticas para Frameworks Leves
Um resumo condensado das 25 práticas mais importantes para frameworks leves - extraídas de todas as páginas desta seção.
//
Busque em todas as páginas da documentação
Um resumo condensado das 25 práticas mais importantes para frameworks leves - extraídas de todas as páginas desta seção.
Use Hono por padrão para novos trabalhos leves: Ecossistema ativo, portável para edge - Noções Básicas de Hono.
Não inicie novos projetos Koa: Mantenha os existentes; migre na reescrita - Koa & Polka.
Use o padrão de fábrica createApp(): Compartilhado entre os pontos de entrada Node e edge.
Entrada Node via @hono/node-server: Não um wrapper node:http bruto.
Valide com Zod nas fronteiras: @hono/zod-validator para entrada tipada.
Centralize app.onError(): JSON de erro consistente.
Use HTTPException para erros operacionais: 404, 401, 422 com códigos de status.
Variáveis de contexto tipadas: c.set() / c.get() com genéricos.
Agrupe rotas antes do arquivo monolítico: app.route("/users", usersApp).
Middleware integrado primeiro: hono/cors, hono/secure-headers, hono/logger.
Abstraia APIs exclusivas do Node: Sem node:fs no código do app compartilhado - Hono no Node vs Edge.
Drivers de DB baseados em HTTP na edge: Neon serverless, Supabase, Prisma Accelerate.
Teste com app.request(): Nenhuma vinculação de porta necessária.
Configuração de ambiente via parâmetro da fábrica: Não process.env no código compartilhado.
Polka apenas para micro-sidecars internos: < 5 endpoints, sem autenticação.
Adicione estrutura antes de 200 linhas: Divida em módulos de rota cedo.
Execute o checklist de seleção de framework: Antes de confirmar - Checklist de Seleção de Framework.
Registre o ADR com data de revisão: 12 meses ou em carga 10x.
Não misture frameworks em um único serviço: Um framework HTTP por implantação.
Perfure antes de reivindicar vitórias de tamanho: I/O geralmente domina sobre a escolha do framework.
OpenAPI via @hono/zod-openapi: Documentação contract-first.
Origens explícitas de CORS: Nunca wildcard com credenciais.
Mantenha os manipuladores enxutos: Lógica de negócios em funções de serviço separadas.
Planeje a migração de Koa como um sprint: Não incremental; reescreva as rotas.
Edge para latência; Node para complexidade: Divida os serviços por necessidade de runtime, não por ideologia.
Hono para novos projetos. Fastify se você precisar de vazão máxima do Node. Express se a familiaridade da equipe for primordial.
Na próxima reescrita principal, sim. Para aplicativos estáveis com pouca rotatividade, o custo de migração pode não valer a pena.
Abaixo de 3 endpoints em uma porta interna: HTTP bruto está bom. Acima de 5: use Hono no mínimo.
Hono e Fastify podem. Nessa escala, considere NestJS para limites de módulos ou imponha convenções rigorosas de arquivos de rota.
Grupos de rotas, camada de serviço, validação Zod e manipulador de erros desde o primeiro dia. Adicione estrutura no endpoint 10, não no endpoint 50.
Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026