Bootstrap del progetto Emdash CMS e struttura delle directory

Pubblicato il 2026-04-08 di Emdash Cms Everything

A chi si rivolge questa guida

Usa questa guida quando parti da un repository vuoto e vuoi una struttura di directory capace di supportare:

• modifiche quotidiane ai contenuti editoriali
• iterazioni frontend senza rompere le assunzioni del CMS
• una migrazione del deploy dallo sviluppo locale a Cloudflare in seguito

L’obiettivo non è creare l’albero cartelle più “furbo”. L’obiettivo è ridurre il costo di manutenzione nel lungo periodo.

Parti prima dalla decisione sul runtime

Prima di creare file, decidi per quale runtime vuoi ottimizzare nei prossimi 30-90 giorni:

• Node.js + SQLite per onboarding locale più rapido e minore complessità operativa
• Cloudflare Workers + D1 + R2 per SSR in produzione, storage gestito e integrazione più stretta con il modello plugin di EmDash

Se il tuo team sta ancora validando la strategia contenuti, inizia prima con Node.js e mantieni da subito naming compatibile con Cloudflare. Così eviti lock-in di piattaforma precoce mantenendo una migrazione semplice.

Struttura directory base consigliata

your-emdash-site/
├── src/
│   ├── components/            # Solo componenti UI riutilizzabili
│   ├── layouts/               # Shell di pagina condivise
│   ├── pages/                 # Route Astro
│   ├── lib/                   # Logica di dominio e integrazioni
│   ├── styles/                # Token di stile globali e condivisi
│   └── live.config.ts         # Mappatura delle collection contenuto live
├── seed/                      # Dati seed per bootstrap/demo
├── public/                    # Asset statici (favicon, immagini statiche)
├── docs/                      # Documentazione prodotto e contenuti editoriali (MDX)
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── emdash-env.d.ts

Se il progetto esistente usa già utils/ invece di lib/, mantienilo per ora. Rinomina solo quando puoi far rispettare regole di ownership chiare.

Modello di ownership delle directory

La struttura funziona solo quando l’ownership è esplicita:

• src/components: unità solo di presentazione; nessuna chiamata diretta a database o storage
• src/layouts: aspetti condivisi del frame (tag head, frame navigazione, shell footer)
• src/pages: composizione route e wiring dati per il rendering
• src/lib: regole di business, adapter dati e glue specifico di piattaforma
• seed: baseline contenuto riproducibile per nuovi ambienti

Questa separazione previene la deriva più comune: codice utility che diventa silenziosamente logica di business.

Percorso di bootstrap che evita rilavorazioni

Per progetti di produzione, usa questa sequenza:

1. Crea il progetto con lo scaffold ufficiale
2. Scegli un solo template (blog, marketing o portfolio)
3. Mantieni le convenzioni generate salvo conflitto con uno standard di team chiaro
4. Aggiungi una sola personalizzazione strutturale alla volta

Perché questa sequenza conta: la maggior parte dei ritardi di lancio non nasce da feature mancanti. Nasce da divergenze strutturali precoci che poi rompono documentazione, script e onboarding.

Comandi bootstrap consigliati

# Crea lo scaffold di un nuovo progetto Emdash CMS
npm create emdash@latest my-emdash-site
cd my-emdash-site

# Installa e avvia lo sviluppo locale
npm install
npm run dev

Anti-pattern comuni da evitare

1) Sviluppo route-first senza decisioni sul modello contenuti

Costruire le route prima di concordare forma di collection e tassonomie porta a riscritture costose.

2) Mescolare aspetti di deploy nelle cartelle UI

Non mettere script specifici di deploy e helper di configurazione in components o pages. Mantieni gli aspetti di piattaforma nei file di config e in src/lib.

3) Cartelle utils senza confini

Se tutto finisce in utils, la scopribilità crolla. Preferisci domini nominati in src/lib come src/lib/content, src/lib/media e src/lib/auth.

Definizione di completamento per il setup iniziale

Considera il bootstrap completo solo quando tutti i controlli passano:

• il server di sviluppo locale gira senza patch manuali
• un flusso contenuto di esempio funziona end-to-end
• i dati seed sono importabili in un ambiente nuovo
• la build CI passa senza hack specifici d’ambiente
• un nuovo contributor riesce a orientarsi nel repository in meno di dieci minuti

Cosa fare dopo

Dopo aver stabilizzato la struttura:

1. documenta nel repository la scelta runtime e i criteri di migrazione
2. definisci convenzioni di naming dei content type prima che il volume cresca
3. implementa un runbook di deploy per la piattaforma scelta

La struttura delle directory è architettura, non cosmetica. Bloccarla presto fa risparmiare settimane dopo.