Anatomía del build: astro build, dist y preview

Desarrollar es un diálogo: editas, guardas, el navegador responde. Desplegar es lo contrario, un monólogo congelado —el proyecto se cuece una vez y a partir de ahí solo se sirve—. astro build es el instante exacto de esa congelación: toma tu carpeta de fuentes, resuelve el contenido, compila los componentes, empaqueta el JavaScript de las islas y deja en dist/ un conjunto de artefactos terminados. Según tengas o no un adapter, esa carpeta significa dos cosas muy distintas: ficheros planos que cualquier CDN sirve sin pensar, o un manojo de assets junto a un manejador de servidor listo para ejecutarse. Entender qué hay dentro de dist/ es entender qué vas a desplegar.

astro build: la fábrica que congela el proyecto

Un solo comando desencadena una cadena de trabajos que rara vez ves con detalle. astro build no es un paso atómico, sino una tubería con etapas bien definidas, y conocerlas te da un mapa mental para cuando algo falla.

astro build
# 1. carga astro.config.mjs y resuelve integraciones y adapter
# 2. ejecuta los loaders de contenido y valida los schemas
# 3. compila cada .astro con el compilador en Rust
# 4. Rolldown empaqueta el JavaScript de las islas
# 5. renderiza cada ruta prerenderizable a HTML
# 6. escribe todo en dist y emite un resumen

El orden importa. El contenido se resuelve antes de renderizar, porque una página no puede pintarse sin sus datos; las islas se empaquetan aparte del HTML, porque viajan por canales distintos —el marcado va horneado, el script se hidrata en el cliente—. Cuando el build se rompe, el mensaje casi siempre delata en qué etapa: un schema de Zod que no valida detiene la fase de contenido; un import roto detiene el empaquetado; un Astro.glob sin resultados aparece al renderizar.

Al terminar, Astro imprime un resumen que no es decorativo: es la radiografía del despliegue que estás a punto de hacer. Leerlo con atención dice más que abrir la carpeta a ciegas.

• Cuántas páginas se prerenderizaron a HTML y cuántas quedaron como rutas bajo demanda.
• El peso del JavaScript de cada isla, la métrica que de verdad gobierna el rendimiento percibido.
• El tiempo total, repartido entre resolver contenido, compilar los .astro y empaquetar.
• Avisos de assets pesados o imágenes sin optimizar que conviene atender antes de publicar.

dist como sitio estático

Sin adapter, el output es static y dist/ es literalmente el sitio: una jerarquía de ficheros terminados, sin una sola línea de tu código pendiente de ejecutar. Abrirlos revela la anatomía de una web horneada.

dist/
  index.html          # cada ruta, ya renderizada a HTML
  blog/
    primer-post/
      index.html
  _astro/             # JS de islas y CSS con hash de contenido
    hoisted.a1b2c3.js
    index.d4e5f6.css
  favicon.svg         # copiado tal cual desde public

Todo lo que ves aquí es inerte: bytes que ya existían antes de la primera visita. El HTML está completo, el CSS lleva un hash en el nombre para cachearse para siempre, y la carpeta _astro guarda solo el JavaScript de las islas que declararon una directiva client:. Servir esto no requiere cómputo: un CDN devuelve el fichero y termina. Esa es la razón de que el estático sea tan barato y tan rápido —no hay servidor que mantener ni proceso que pueda caerse—.

Conviene distinguir las tres clases de fichero que conviven en la carpeta, porque cada una se cachea de forma distinta:

• El HTML de cada ruta, terminado y sin hash: su nombre no cambia aunque su contenido sí, así que debe revalidarse a menudo.
• Los assets con hash en _astro: el nombre deriva del contenido, de modo que pueden cachearse para siempre sin riesgo de servir algo viejo.
• Lo copiado de public tal cual: favicons, robots.txt y ficheros que quieres servir sin que Vite los reescriba.

Salida de servidor: client y server

En cuanto instalas un adapter y alguna ruta se renderiza bajo demanda, el build parte dist/ en dos mitades con roles opuestos. Ya no es un sitio terminado, sino un sitio a medio hornear que necesita un runtime para completarse.

dist/
  client/   # servible por un CDN, igual que el estatico
  server/
    entry.mjs   # el punto de entrada que arranca el runtime

La lección clave es que dist/server no es un sitio: es un programa. Nadie lo sirve como ficheros; alguien lo ejecuta. Confundir las dos mitades es el error más común al desplegar SSR —subir dist/server a un CDN estático no produce nada, porque un CDN no arranca procesos—. El adapter existe justo para que cada mitad aterrice donde le corresponde.

astro preview: el ensayo general

Entre construir y desplegar hay un abismo peligroso: nunca has visto correr eso que acabas de generar. astro preview cierra esa brecha levantando un servidor local que sirve dist/ tal cual, sin el andamiaje del dev server.

astro build && astro preview
# levanta dist en http://localhost:4321 como en produccion

La diferencia con astro dev es sustancial y por eso preview atrapa fallos que dev esconde. El dev server compila al vuelo, aplica HMR y no pasa por Rolldown en producción; preview no compila nada, sirve el artefacto real. Aquí afloran los problemas que solo existen tras el build: una ruta de asset que se rompió al empaquetar, un base mal configurado, una imagen que no se optimizó, una isla que se hidrata distinto sobre el bundle final.

Hay una regla de higiene que ahorra incidentes: nunca despliegues algo que no hayas servido al menos una vez con astro preview. El coste es de segundos y la recompensa es desproporcionada —cada fallo que preview atrapa en tu máquina es un fallo que no verá tu plataforma ni, peor, tu visitante—. Es el último control de calidad que está enteramente en tus manos antes de ceder el sitio a la red.

flowchart TD
SRC[src pages y contenido] --> COMP[compilador en Rust]
COMP --> BUND[Rolldown empaqueta las islas]
BUND --> OUT[carpeta dist]
OUT --> EST[modo estatico HTML y assets]
OUT --> SSR[modo servidor client mas server]
EST --> PREV[astro preview lo ensaya en local]
SSR --> PREV
style COMP fill:#89b4fa,color:#11111b
style OUT fill:#a6e3a1,color:#11111b