Como Criar e Preparar um Backend TypeScript Profissional com Fastify, Zod e Biome
Aprenda, em um roteiro prático, como configurar um backend robusto, com validação e documentação de API de primeira, usando ferramentas modernas like Fastify, TSX, Zod, Scalar e Biome.
Por que isso é importante
APIs robustas não nascem prontas: elas exigem visão. Se você quer uma base sólida para acelerar entregas e manter qualidade, montar o backend certo desde a primeira linha faz toda a diferença. Com TSX, TypeScript, Fastify, Zod, Biome e Scalar, seu código já nasce escalável, seguro e pronto para documentação automatizada. Você vai entender na prática como transformar decisões técnicas simples em produtividade real.
Comece pelas bases: Initialização de Projeto com pnpm e TypeScript
A pressa normalmente leva ao caos, mas aqui o passo a passo é claro: esqueça iniciar o app web e foque 100% na API. Dentro da pasta da sua API, rode pnpm init (sem -y, pois o padrão já te poupa prompts à toa). O resultado: seu package.json pronto para nascer limpo e sob controle.
ℹ️Atenção
Muitos confundem o -y no init dos gerenciadores de pacotes: o pnpm já assume defaults, diferente do npm que exige essa flag.
Estrutura mínima: Pastas e setup do projeto
Com package.json criado, crie a pasta source para separar sua lógica. Não jogue arquivos soltos na raiz: organização economiza horas no médio prazo.
Escolha do executor: TSX para rodar TypeScript com poder real
Ao invés de contar só com suporte nativo do Node, instale tsx no backend: ele garante features valiosas como aliases e paths inteligentes de importação. Já previne dor de cabeça, pois só com o TSX você usa tsconfig-paths e realocações limpas de arquivos, fugindo de importações quebradas.
⚠️Atenção
Sem o TSX, o Node puro ainda não suporta aliases avançados por tsconfig. Muita import quebrando no futuro.
tsconfig.json: Referencie e customize como um profissional
Chame pnpm tsc --init: isso cria um tsconfig.json inicial. Torne-o robusto copiando bases prontas do repositório oficial no Github (tsconfig-bases). Escolha o preset para sua versão Node, cole o conteúdo, ajuste os aliases (ex: @/* para source/*) na seção paths.
ℹ️Atenção
Aliasing bem feito (@/algo vira source/algo): mantém a escalabilidade e facilita refatorações, principalmente para times grandes.
Scripts de dev e produção: automatize execução e builds
Monte scripts no package.json para acelerar seu fluxo. No modo dev: tsx watch source/server.ts. No build, compile para dist e rode via node dist/server.js. Você isola ambiente de desenvolvimento de produção, prevenindo bugs e confusões.
⚠️Atenção
Separe SEMPRE ambientes dev e prod: rodar TypeScript direto em produção pode deixar sua API lenta e mais vulnerável.
Na raiz da escalabilidade: Fastify, o Server para performance
Instale Fastify e crie seu server.ts expondo a API na porta 3333 e host 0.0.0.0. Esse host permite deploy fácil em plataformas como Railway e amplia compatibilidade. Capriche nos logs de inicialização: exiba a rota principal da API e a URL da documentação.
Variáveis de ambiente: mantenha segredos e configs isolados
Adote um arquivo .env para variáveis sensíveis desde o primeiro commit. Configure o TSX para ler automaticamente seu .env, prevenindo exposição de dados críticos no versionamento.
ℹ️Atenção
NUNCA versionar .env. Adicione logo ao .gitignore.
Biome: lint e format em segundos, sem dor
Configure Biome com biome init para padronizar formatação e estilos no projeto. Prefira espaço sobre tab, 2 espaços de indentação, limite linhas a 80 caracteres, strings simples e pontuação só quando necessário.
⚠️Atenção
Garanta que o Biome esteja integrado ao seu editor (VSCode, Zed, IntelliJ) para salvar e ver seu código limpo em tempo real.
Scripts de formatação: padronização com um comando
No package.json, crie um script format utilizando biome format . --write para uniformizar o código com facilidade a cada commit.
Plug-ins Fastify: CORS, Swagger, Scalar e Validação tipada com Zod
Dê superpoderes ao seu server instalando os plugins oficiais Fastify: @fastify/cors para habilitar CORS, @fastify/swagger para gerar documentação OpenAPI, zod para validação e fastify-type-provider-zod para integrar tipos e validações nativas. Adicione também o Scalar para uma UI de docs free e moderna.
Configurações inteligentes: Integre, customize e valide cada endpoint
No seu server.ts, registre cada plugin: Cors (permitindo origin: true), Swagger com informações personalizadas e jsonSchemaTransform, Scalar UI com o prefix /docs. Use o Type Provider do Zod para tipagem automática e aponte todos os imports necessários.
Autenticação e segurança: preparing para o próximo nível
Antecipe funcionalidades comentando as opções de credentials: true no CORS, preparando para cookies e sessões futuras necessárias em flows autenticados.
ℹ️Atenção
Cookies automáticos via CORS apenas se credentials: true e front+back compartilharem origem. Perigoso para apps públicos sem autenticação forte.
Documentação de API bonita, automática e sempre atualizada
Ao rodar o server, acesse /docs para ver toda documentação via Scalar, já consumindo as configs OpenAPI via Swagger. Cada endpoint será documentado automaticamente, reduzindo bugs em integrações.
✅Atenção
API sem documentação é receita de desastre em times e parcerias. Docs vivas = velocidade na entrega e suporte.
Validação e inferência: Zod como guardião dos dados
Configure o uso do Zod em todas as rotas. Ele valida as entradas e define tipos, garantindo que o payload está correto antes de processar. Isso previne bugs difíceis e aumenta a qualidade.
Pronto para crescer: Invista na cultura de código preparado
Com esse setup, você prepara seu backend para qualquer desafio: produtividade, qualidade, documentação viva e segurança robusta. Invista tempo aqui e ganhe semanas no futuro — e se quiser técnicas avançadas do zero ao produto, confira meu canal para mergulhar fundo na prática real!
ℹ️Atenção
Assista à série completa de backend TypeScript e mais hacks no canal Dev Doido: youtube.com/@DevDoido