Volver al Blog

Migrando Mi Sitio Personal de Astro 2 a Astro 6

· 5 min de lectura

Mi sitio personal ha corrido en Astro desde 2023, pero estaba atorado en la versión 2.7. Con Astro 6 afuera y un montón de mejoras que quería hacer, decidí aventarme la migración completa. Esto es lo que aprendí saltando cuatro versiones mayores en una sola sesión.

¿Por Qué Actualizar?

Astro 2.7 estaba bien, pero el ecosistema había avanzado. El nuevo Content Layer API, mejor optimización de imágenes, y Vite 7 eran demasiado buenos para ignorar. Además, mi sitio había acumulado deuda técnica — bugs de CSS, valores hardcodeados, y un homepage que era solo un logo y un avatar. Triste.

La Ruta de Migración: v2 → v3 → v4 → v5 → v6

Saltar cuatro versiones mayores suena aterrador, pero las guías de migración de Astro están bien documentadas. Estos son los breaking changes principales que tuve que resolver:

Content Collections → Content Layer API

Este fue el cambio más grande. El viejo src/content/config.ts se convirtió en src/content.config.ts, y cada colección ahora necesita un loader:

import { glob } from "astro/loaders";

const blogCollection = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/content/blog" }),
  schema: z.object({
    title: z.string(),
    // ...
  }),
});

slug → id

Cada referencia a post.slug tuvo que cambiar a post.id. Esto afectó todas las rutas dinámicas, páginas de listado, y el feed RSS.

render() ahora se importa

En vez de llamar post.render(), ahora importas render de astro:content:

import { render } from "astro:content";
const { Content } = await render(post);

Endpoint RSS: get → GET

El nombre de la función del endpoint RSS cambió de get en minúsculas a GET en mayúsculas para seguir las convenciones de métodos HTTP.

astro-icon v0.8 → v1

La ruta de importación cambió de astro-icon a astro-icon/components, y el paquete ahora necesita registrarse como integración en astro.config.mjs. También tuve que instalar @iconify-json/mdi para los Material Design Icons.

Migrando de npm a Bun

Ya que andaba en eso, cambié de npm a Bun. El proceso fue simple:

  1. Borrar node_modules y package-lock.json
  2. Correr bun install
  3. Actualizar scripts en package.json para usar bunx --bun

Los tiempos de build bajaron de ~1.6s a ~1.1s. No es una diferencia enorme para un sitio chico, pero bun install es notablemente más rápido que npm install.

Lo Que Arreglé en el Camino

La migración también fue oportunidad de arreglar bugs que había estado ignorando:

  • Un } extra en el CSS del Header que rompía estilos
  • width: 100vph (no es una unidad real) → 100%
  • Un typo en el nombre de clase porfolio → portfolio
  • margin-top: 1rem 0 (shorthand inválido) → margin: 1rem 0
  • Atributos alt vacíos en imágenes
  • Una propiedad color duplicada en un hover state
  • El componente BackButtom.astro → BackButton.astro

Sí, todo eso estaba ahí. No pregunten cuánto tiempo.

El Rediseño

Con código limpio como base, rediseñé todo el sitio:

  • Nueva paleta de colores — Navy, Teal, Sky Blue, y Beige
  • Homepage — Sección hero con botones CTA, grid de skills, preview de open source, y dev setup
  • Página About — Timeline completo de carrera de 1988 a 2026
  • Página Open Source — Mostrando mis proyectos en Go y Rust
  • Portfolio — Cards rediseñadas con tags de tecnologías
  • Footer — Consistente en todas las páginas con links sociales
  • Página 404 — Página de error personalizada
  • SEO — robots.txt, og:image, meta author, descripciones dinámicas

Herramientas Que Usé

Usé Claude Code extensivamente durante todo el proceso. Me ayudó a leer las guías de migración, identificar breaking changes, actualizar todos los archivos, y atrapar bugs. Tener un asistente de IA que puede leer documentación, entender el codebase, y hacer cambios en múltiples archivos simultáneamente hizo esta migración mucho más rápida que hacerla manualmente.

Lecciones Aprendidas

  1. No le tengas miedo a los saltos de versión mayores — Las guías de migración de Astro son completas. Léelas con cuidado y haz cambios metódicamente.
  2. Arregla bugs mientras andas ahí — Una migración es el momento perfecto para limpiar deuda técnica.
  3. Las CSS custom properties ahorran tiempo — Cambiar toda la paleta de colores fue solo editar 4 variables.
  4. Bun es un reemplazo directo — La migración de npm tomó como 2 minutos.
  5. Usa herramientas de IA — Son geniales para trabajo tedioso de migración y para atrapar cosas que se te pasarían.

Resultado

El sitio pasó de ser un template básico con un logo y un avatar a un portafolio profesional completo con 6 páginas, imágenes optimizadas, SEO adecuado, y un sistema de diseño consistente. Y todo se despliega automáticamente en Vercel con cada git push.

Si todavía están en una versión vieja de Astro, les recomiendo dar el salto. Solo el nuevo Content Layer API ya lo vale.