Acabo de migrar este portfolio de Astro 4 a Astro 5. La experiencia fue dolorosa pero útil. Aquí va el post-mortem honesto. Con la decisión que tomé mal.
Lo que encontré
Astro 5 cambió las Content Collections. Lo que antes era content/blog/*.md con
un schema en content/config.ts, ahora requiere un loader (glob() o file())
declarado en el mismo sitio. Si no migras el config, las collections devuelven
arrays vacíos sin error claro.
El fix: declarar el loader explícitamente.
defineCollection({
loader: glob({ pattern: "**/*.md", base: "./src/content/blog" }),
schema: z.object({
title: z.string(),
date: z.date(),
tags: z.array(z.string()),
}),
});Sin esto, no hay contenido. Perdí 1 hora debuggeando esto.
El segundo drama
Las páginas dinámicas con getStaticPaths(). Astro 5 cambió la firma ligeramente.
Antes devolvías un array directo, ahora también se puede usar paginate() con más
features. La migración es retrocompatible pero los tipos cambiaron.
Otro drama: las View Transitions API ahora son nativas en Astro 5
(<ViewTransitions /> en lugar del paquete @astrojs/transitions). Menos deps,
mejor integración.
La decisión que me arrepiento
Astro 5 ofrece server islands para contenido interactivo por página. Pensé
que sería buena idea: en lugar de generar HTML estático para /blog/, generar
server islands que se hidratan en cliente.
Resultado: build time subió de 1.4s a 8s. El portfolio no necesita server islands para 6 posts. Volví a static generation.
Lección: no adoptes feature nuevo sin medir impacto. Astro 5 está bien, server islands están bien para portfolio de 200+ posts, pero no para 6.
Total
4 horas de migración. 35 páginas funcionando. 0 páginas rotas. El portfolio está más rápido porque eliminé dependencias.
El proceso que recomiendo
- Lee el migration guide oficial entero antes de empezar. Yo leí los primeros 3 párrafos. Me ahorré 2 horas si lo hubiera leído entero.
- Migra en una branch separada. Si algo sale mal, rollback es 30 segundos.
- Mide antes y después. Build time, lighthouse score, bundle size. Sin métricas no sabes si la migración fue buena.
- Migra una sección a la vez. No todo de golpe.
¿Migrastes a Astro 5 también? Cuéntame tu experiencia.