Estructura del proyecto y frontmatter

Aprende cómo se organiza un proyecto Astro y qué papel juega el frontmatter en los componentes .astro.

Si en Astro no entiendes bien la estructura del proyecto y el frontmatter, todo lo demás se vuelve confuso. Esta lección es probablemente la más importante al empezar.

Estructura mínima

Una estructura típica:

public/
src/
  components/
  layouts/
  pages/
  content/
  styles/
astro.config.mjs
package.json

Qué va en cada sitio

  • public/: archivos estáticos que salen tal cual
  • src/pages/: páginas y rutas
  • src/components/: piezas reutilizables
  • src/layouts/: plantillas generales
  • src/content/: contenido tipado con collections
  • src/styles/: estilos compartidos

Qué es el frontmatter

En un archivo .astro, el bloque superior entre --- y --- se ejecuta en servidor durante build o SSR.

---
const title = 'Mi página';
const productos = ['Ratón', 'Teclado', 'Monitor'];
---

<h1>{title}</h1>
<ul>
  {productos.map((producto) => <li>{producto}</li>)}
</ul>

Ese bloque no es un “script de navegador”. Es lógica de preparación de datos.

La idea importante

En Astro conviene separar mentalmente dos cosas:

  • frontmatter: prepara datos
  • template: pinta HTML

Si entiendes eso, ya tienes media arquitectura del framework.

Qué puedes hacer dentro del frontmatter

Puedes:

  • importar componentes
  • importar utilidades
  • leer props
  • hacer fetch
  • transformar arrays
  • preparar variables para render
---
import Layout from '../layouts/BaseLayout.astro';
const nombre = 'Carlos';
const destacados = ['Astro', 'MDX', 'SSR'];
---

<Layout title="Inicio">
  <h1>Hola, {nombre}</h1>
  <p>Hoy vamos a ver {destacados.join(', ')}</p>
</Layout>

Qué no debes asumir

No todo lo que escribes en .astro acaba en el navegador. El frontmatter desaparece como tal al compilar.

Eso significa que:

  • no puedes usar ahí APIs del DOM como document.querySelector
  • sí puedes hacer trabajo de servidor

Una regla muy útil

Si una variable solo sirve para renderizar HTML, probablemente deba vivir en el frontmatter. Si algo requiere interacción del usuario en cliente, ya entra otro tipo de solución.

En la siguiente lección vamos con páginas, routing y el sistema de rutas de Astro.