EmDash CMS – Arranque del proyecto y estructura de directorios

Publicado el8 abr 2026porEmdash Cms Everything

Para quién es esta guía

Úsala cuando partas de un repositorio vacío y quieras una estructura que soporte:

• cambios editoriales de contenido cada día
• iteración de frontend sin romper supuestos del CMS
• un despliegue posterior del desarrollo local a Cloudflare

El objetivo no es el árbol de carpetas más ingenioso, sino reducir el coste de mantenimiento a largo plazo.

Primero decide el tiempo de ejecución

Antes de crear archivos, decide qué tiempo de ejecución optimizarás en los próximos 30 a 90 días:

• Node.js + SQLite para incorporación local más rápida y menor complejidad operativa
• Cloudflare Workers + D1 + R2 para SSR en producción, almacenamiento gestionado e integración más estrecha con el modelo de plugins de EmDash

Si el equipo aún valida la estrategia de contenidos, empieza con Node.js y mantén nombres listos para Cloudflare desde el día uno. Evitas bloqueo temprano en la plataforma y mantienes la migración sencilla.

Estructura de directorios base recomendada

your-emdash-site/
├── src/
│   ├── components/            # Solo piezas de UI reutilizables
│   ├── layouts/               # Cascos de página compartidos
│   ├── pages/                 # Rutas Astro
│   ├── lib/                   # Lógica de dominio e integraciones
│   ├── styles/                # Tokens de estilo globales y compartidos
│   └── live.config.ts         # Mapeo de colecciones de contenido en vivo
├── seed/                      # Datos semilla para arranque/demo
├── public/                    # Activos estáticos (favicons, imágenes)
├── docs/                      # Documentación del producto y contenido editorial (MDX)
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── emdash-env.d.ts

Si el proyecto ya usa utils/ en lugar de lib/, mantenlo por ahora. Renombra solo cuando puedas aplicar reglas de propiedad claras.

Modelo de propiedad de directorios

La estructura solo funciona con propiedad explícita:

• src/components: unidades solo de presentación; sin llamadas directas a base de datos o almacenamiento
• src/layouts: marco compartido (head, nav, pie)
• src/pages: composición de rutas y cableado de datos para el renderizado
• src/lib: reglas de negocio, adaptadores de datos y pegamento específico de plataforma
• seed: contenido base reproducible para entornos nuevos

Así se evita el desvío más común: el código de utilidades que pasa silenciosamente a ser lógica de negocio.

Ruta de arranque que evita retrabajo

Para proyectos de producción, usa esta secuencia:

1. Crear con el scaffold oficial
2. Elegir una plantilla (blog, marketing o portfolio)
3. Mantener las convenciones generadas salvo conflicto con un estándar claro del equipo
4. Añadir solo una personalización estructural cada vez

Por qué importa el orden: la mayoría de retrasos no vienen de funciones que faltan, sino de divergencia estructural temprana que luego rompe documentación, scripts e incorporación.

Comandos de arranque recomendados

# Crear un proyecto EmDash CMS nuevo
npm create emdash@latest my-emdash-site
cd my-emdash-site

# Instalar y arrancar desarrollo local
npm install
npm run dev

Anti-patrones comunes

1) Código primero por rutas sin decidir el modelo de contenido

Construir rutas de página antes de acordar la forma de colecciones y taxonomías provoca reescrituras caras.

2) Mezclar preocupaciones de despliegue en carpetas de UI

No pongas scripts específicos de despliegue ni ayudas de configuración bajo components o pages. Las preocupaciones de plataforma van en archivos de configuración y src/lib.

3) Carpetas utils sin límite

Si todo va a utils, desaparece la descubribilidad. Prefiere dominios con nombre en src/lib, por ejemplo src/lib/content, src/lib/media, src/lib/auth.

Definición de terminado para la configuración inicial

Considera el arranque completo solo cuando:

• el servidor de desarrollo local funciona sin parches manuales
• un flujo de contenido de ejemplo funciona de extremo a extremo
• los datos semilla se pueden importar en un entorno nuevo
• el build de CI pasa sin hacks específicos del entorno
• un nuevo colaborador puede orientarse en el repositorio en menos de diez minutos

Qué hacer después

Cuando la estructura sea estable:

1. documenta la elección de tiempo de ejecución y criterios de migración en el repositorio
2. define convenciones de nombres de tipos de contenido antes de que crezca el volumen
3. implementa el runbook de despliegue para tu plataforma

La estructura de directorios es arquitectura, no cosmética. Fijarla pronto ahorra semanas después.