Bootstrap de projeto e layout de diretórios do EmDash CMS

Publicado em 2026-04-08 por Emdash Cms Everything

Para quem é este guia

Use este guia quando estiver partindo de um repositório vazio e quiser uma estrutura de diretórios que suporte:

• mudanças de conteúdo editorial todos os dias
• iteração de frontend sem quebrar suposições do CMS
• uma mudança de implantação do desenvolvimento local para a Cloudflare depois

O objetivo não é a árvore de pastas mais esperta. O objetivo é reduzir o custo de manutenção de longo prazo.

Comece pela decisão de runtime primeiro

Antes de criar arquivos, decida para qual runtime você está otimizando nos próximos 30 a 90 dias:

• Node.js + SQLite para onboarding local mais rápido e menor complexidade operacional
• Cloudflare Workers + D1 + R2 para SSR em produção, armazenamento gerenciado e integração mais estreita com o modelo de plugins do EmDash

Se a equipe ainda valida estratégia de conteúdo, comece com Node.js primeiro e mantenha nomes prontos para Cloudflare desde o dia um. Isso evita lock-in de plataforma cedo e mantém a migração simples.

Layout de diretórios base recomendado

your-emdash-site/
├── src/
│   ├── components/            # Apenas peças de UI reutilizáveis
│   ├── layouts/               # Cascas de página compartilhadas
│   ├── pages/                 # Rotas Astro
│   ├── lib/                   # Lógica de domínio e integrações
│   ├── styles/                # Tokens de estilo globais e compartilhados
│   └── live.config.ts         # Mapeamento de coleção de conteúdo ao vivo
├── seed/                      # Dados seed para bootstrap/demo
├── public/                    # Assets estáticos (favicons, imagens estáticas)
├── docs/                      # Docs de produto e conteúdo editorial (MDX)
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── emdash-env.d.ts

Se o projeto existente já usa utils/ em vez de lib/, mantenha por enquanto. Renomeie só quando puder impor regras claras de propriedade.

Modelo de propriedade de diretórios

A estrutura só funciona quando a propriedade é explícita:

• src/components: unidades só de apresentação; sem chamadas diretas a banco ou armazenamento
• src/layouts: preocupações de moldura compartilhada (tags head, moldura de nav, casca de rodapé)
• src/pages: composição de rota e ligação de dados para renderização
• src/lib: regras de negócio, adaptadores de dados e cola específica de plataforma
• seed: conteúdo base reproduzível para novos ambientes

Essa divisão evita o desvio mais comum: código utilitário virando silenciosamente lógica de negócio.

Caminho de bootstrap que evita retrabalho

Para projetos de produção, use esta sequência:

1. Criar com o scaffold oficial
2. Escolher um template (blog, marketing ou portfolio)
3. Manter convenções geradas salvo conflito com padrão claro da equipe
4. Adicionar só uma customização estrutural por vez

Por que esta sequência importa: a maioria dos atrasos de lançamento não vem de recursos faltando. Vem de divergência estrutural cedo que depois quebra docs, scripts e onboarding.

Comandos de bootstrap recomendados

# Gerar um novo projeto EmDash CMS
npm create emdash@latest my-emdash-site
cd my-emdash-site

# Instalar e iniciar desenvolvimento local
npm install
npm run dev

Antipadrões comuns a evitar

1) Codificar rotas primeiro sem decisões de modelo de conteúdo

Construir rotas de página antes de alinhar forma de coleção e taxonomia causa reescritas caras.

2) Misturar preocupações de implantação em pastas de UI

Não coloque scripts específicos de deploy e helpers de config sob components ou pages. Mantenha preocupações de plataforma em arquivos de config e src/lib.

3) Pastas utils sem limite

Se tudo vai para utils, a descoberta colapsa. Prefira domínios nomeados em src/lib, como src/lib/content, src/lib/media e src/lib/auth.

Definição de pronto para configuração inicial do projeto

Trate o bootstrap como completo só quando todas as verificações passarem:

• servidor de dev local roda sem patch manual
• um fluxo de conteúdo de exemplo funciona ponta a ponta
• dados seed podem ser importados em ambiente novo
• build de CI passa sem hacks específicos de ambiente
• um novo contribuidor navega o repositório em menos de dez minutos

O que fazer em seguida

Depois que a estrutura estiver estável:

1. documentar escolha de runtime e critérios de migração no repositório
2. definir convenções de nomenclatura de tipos de conteúdo antes do volume crescer
3. implementar runbook de implantação para a plataforma escolhida

Estrutura de diretórios é arquitetura, não cosmética. Travá-la cedo economiza semanas depois.