<\> Casa do Dev
Notícias abrir
Ferramentas abrir
Vagas abrir
Aprender abrir
Comunidade abrir
Guia de Compras abrir

Como organizar um projeto Node.js do zero sem virar bagunça

DA

5 min

Entusiasta das Tecnologias

Como organizar um projeto Node.js do zero sem virar bagunça

Organizar um projeto Node.js do zero leva menos de 1 hora com o mapa certo, e este guia entrega a estrutura por camadas, o papel de cada pasta e as 3 regras que impedem a bagunça de voltar. O objetivo é simples: que qualquer pessoa do time encontre o código sem te ligar.

Neste artigo

Como organizar um projeto Node.js do zero sem virar bagunça

Todo projeto Node.js nasce organizado no primeiro dia, e a bagunça chega na 3ª semana, quando a pasta de utilidades virou lixeira e ninguém sabe mais onde o bug mora. A diferença entre projeto que escala e projeto que vira dor é a estrutura definida antes do primeiro arquivo solto.

Organizar um projeto Node.js do zero leva menos de 1 hora com o mapa certo, e este guia entrega a estrutura por camadas, o papel de cada pasta e as 3 regras que impedem a bagunça de voltar. O objetivo é simples: que qualquer pessoa do time encontre o código sem te ligar.

A estrutura por camadas que escala com o projeto

A organização que funciona para projetos de estudo e para os primeiros anos de produto separa o código pelo papel que ele cumpre, e não pelo tipo de arquivo. Cada pasta tem dono conceitual, e a regra de importação segue um sentido só.

PastaO que mora ali
src/routesA definição dos endpoints e o mapeamento de URLs
src/controllersO recebimento do pedido e a resposta, sem regra de negócio
src/servicesA regra de negócio, o coração do projeto
src/repositoriesO acesso ao banco de dados, isolado do resto
src/configConexões, variáveis de ambiente e inicialização
testsOs testes, espelhando a estrutura do src

O sentido das importações é o que impede a queda de domino: routes chama controllers, controllers chama services, services chama repositories, e o caminho inverso é proibido. Com esse contrato, a troca de banco de dados não toca a regra de negócio, e a mudança de framework web não toca o banco.

As 3 regras que impedem a bagunça de voltar

  • Regra 1, nada solto na raiz: além do package.json e dos arquivos de configuração, a raiz fica vazia. Script de manutenção criado às pressas na raiz hoje é o arquivo órfão de amanhã.
  • Regra 2, o util é a última porta: pasta de helpers só recebe função usada em 2 ou mais lugares, com nome que explica o que faz. Função usada em 1 lugar mora onde ela é usada.
  • Regra 3, o pull request guarda o padrão: código novo que quebra as camadas volta no review com o motivo anotado. Padrão sem fiscalização é sugestão, e sugestão ninguém segue em semana de prazo.

O pull request é o fórum que o time já tem, e o critério do clean code no mundo real vale aqui: PR pequeno, com a mudança legível de ponta a ponta. Estrutura que não passa pelo review vira exceção, e exceção multiplicada é bagunça.

Do zero ao primeiro commit organizado

A sequência de criação economiza retrabalho: inicie o projeto com o manifest, crie a árvore de pastas vazia com os arquivos de índice, configure as variáveis de ambiente com o arquivo de exemplo versionado e só então escreva o primeiro endpoint, já no lugar certo.

Criar a pasta depois do código é o caminho da bagunça: código funcionando nunca quer mudar de endereço, e 2 semanas depois a exceção virou padrão.

O arquivo de variáveis de ambiente nunca vai versionado, e o arquivo de exemplo com os nomes das chaves vai: é ele que permite a outra pessoa subir o projeto sem te chamar.

O passo a passo de subir o projeto no GitHub cobre a publicação, e o README com o comando de subir e 10 linhas de contexto completa o kit que o colega monta em 15 minutos, entre clone, instalação e configuração do arquivo de ambiente.

Por que a estrutura importa na entrevista

A pergunta sobre como o candidato estrutura um projeto aparece em entrevista de backend porque revela quem já manteve código de outra pessoa. A resposta com camadas, sentido de importação e o papel do review mostra prática, e o projeto de estudo com essa estrutura é o portfólio que a conversa pede.

A trilha completa de backend está no roadmap de backend 2026 para a primeira vaga, e as vagas abertas no casado.dev mostram o que as descrições pedem desse repertório.

Perguntas frequentes

Preciso dessa estrutura desde o primeiro dia?

A árvore de pastas sim, porque criar depois custa mais, mas as camadas podem nascer vazias e ser preenchidas conforme o projeto cresce. O que não dá para atrasar é o sentido de importação, porque ele define o desenho do projeto, e reverter um fluxo já escrito em camada errada é o retrabalho caro.

Onde entram os testes nesse desenho?

Na pasta tests, espelhando a estrutura do src: o teste do service de cobrança mora em tests/services, com o mesmo nome do arquivo testado. Esse espelhamento é o que permite encontrar o teste sem procurar, e a suíte cresce organizada por padrão.

Vale usar um gerador de estrutura pronta?

Vale como partida, com leitura: os geradores populares entregam a árvore comum, e o time precisa entender cada pasta antes de codar nelas. Estrutura copiada sem entendimento produz a mesma bagunça com nomes bonitos, e a entrevista técnica cobra exatamente esse entendimento.

Como organizar um projeto que já está bagunçado?

Com migração incremental, e não com grande reescrita: a cada tarefa nova, o código tocado entra no lugar certo, e os imports antigos são atualizados no mesmo PR. Em 3 ou 4 ciclos, as partes mais movimentadas do projeto já moram no lugar certo, sem parar a entrega para reorganizar tudo de uma vez.

Produtos relacionados

Este conteúdo tem links de afiliado: se você comprar por eles, podemos receber uma comissão sem custo extra para você. A escolha dos produtos segue critérios próprios e não é influenciada por comissão.

O que você achou deste artigo?

Responda a Pergunta do Dia Teste seu conhecimento e mantenha sua streak. Crie seu Dev Card público Perfil dev compartilhável em um único link.

Depois dessa formação...

Veja vagas em tecnologia →

Vagas relacionadas

Ver todas as vagas →
DA

Escrito por

Dagmar Cirino

Entusiasta das Tecnologias

Publicado em

Sou o Cirino, e desenvolvo soluções e produtos utilizando linguagens de programação e ferramentas de analytics e monitoração baseadas em Cloud. Trabalho com tecnologia desde 2010,...

Ver perfil do autor

COMPARTILHAR