Como Criar e Preparar um Backend TypeScript Profissional

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.

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.

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 .

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.

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.

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.

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.

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.

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!

Perguntas frequentes

Setup backend Node.js completo: o mínimo?

HTTP, auth, DB, logs, deploy e testes. O resto é opinião.

Framework?

Fastify/Nest/etc. Escolha e aprofunde.

TypeScript?

Sim se o time for crescer.

Clean architecture?

Quando a complexidade pedir.

Continue explorando