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 <code>-y</code> , pois o padrão já te poupa prompts à toa). O resultado: seu <code>package.json</code> pronto para nascer limpo e sob controle.

Estrutura mínima: Pastas e setup do projeto

Com <code>package.json</code> criado, crie a pasta <code>source</code> 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 <code>tsx</code> 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 <code>tsconfig-paths</code> e realocações limpas de arquivos, fugindo de importações quebradas.

tsconfig.json: Referencie e customize como um profissional

Chame <code>pnpm tsc --init</code> : isso cria um <code>tsconfig.json</code> 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: <code>@/*</code> para <code>source/*</code> ) na seção <code>paths</code> .

Scripts de dev e produção: automatize execução e builds

Monte scripts no <code>package.json</code> para acelerar seu fluxo. No modo dev: <code>tsx watch source/server.ts</code> . No build, compile para <code>dist</code> e rode via <code>node dist/server.js</code> . 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 <code>server.ts</code> 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 <code>.env</code> para variáveis sensíveis desde o primeiro commit. Configure o TSX para ler automaticamente seu <code>.env</code> , prevenindo exposição de dados críticos no versionamento.

Biome: lint e format em segundos, sem dor

Configure Biome com <code>biome init</code> 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 <code>package.json</code> , crie um script <code>format</code> utilizando <code>biome format . --write</code> 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: <code>@fastify/cors</code> para habilitar CORS, <code>@fastify/swagger</code> para gerar documentação OpenAPI, <code>zod</code> para validação e <code>fastify-type-provider-zod</code> 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 <code>server.ts</code> , registre cada plugin: Cors (permitindo <code>origin: true</code> ), Swagger com informações personalizadas e <code>jsonSchemaTransform</code> , Scalar UI com o prefix <code>/docs</code> . 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 <code>credentials: true</code> 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 <code>/docs</code> 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