De WordPress a Astro 6: 5 Errores que Nos Costaron 5 Días Extra en una Migración de 2,500 Páginas

Migrar un sitio editorial de WordPress a Astro 6 suena simple en teoría: exportas el contenido, lo estructuras en JSON y builds el frontend. En la práctica, la migración de contenido tomó 8 días hábiles — 5 más de los 3 que presupuestamos. Este artículo documenta cada error, cuánto nos costó en tiempo real, y el marco de decisión que ahora usamos para que no te pase lo mismo.

El proyecto era un portal editorial con 2,500+ páginas en 3 idiomas, operando sobre WordPress con un theme pesado, plugins de caching, y un editor de Gutenberg lleno de bloques personalizados que el cliente había acumulado durante 5 años. El objetivo: migrar a Astro 6 + Cloudflare Pages para mejorar rendimiento y costos de hosting.

Las métricas finales justificaron la migración: TTFB de 680ms (servidor en Miami) a 98ms (edge de Cloudflare en Panamá), Lighthouse de 38 a 97, y LCP de 4.2s a 1.8s. Pero el camino estuvo lleno de errores que cualquier equipo que planee una migración similar debería conocer.

Error #1: Subestimamos la Transformación de Bloques Gutenberg (5 días perdidos)

El error más costoso. Presupuestamos 3 días para migrar 2,500+ páginas de contenido. Nos tomó 8.

WordPress almacena el contenido como bloques de Gutenberg en serialized HTML dentro de wp_posts.post_content. Astro 6 usa Content Collections con schemas de Zod 4 — archivos planos en JSON, YAML o Markdoc. Suena como una transformación directa, pero la realidad es más compleja:

• YouTube embeds personalizados: El cliente había desarrollado un bloque propio de YouTube con parámetros de tracking, timestamp y thumbnail personalizado. No existía un parser que entendiera ese bloque → tuvimos que escribir uno.
• Tablas complejas con estilos inline: Gutenberg permite tablas con anchos de columna, colores de fondo y alineación. Todo eso se pierde al extraer HTML plano.
• Acordeones y pestañas: Bloques de interfaz que en WordPress funcionaban con JavaScript de terceros. En Astro no hay equivalente directo → hubo que reconstruirlos como componentes de isla.

Lección: Agenda una semana completa para el mapeo y transformación de contenido antes de escribir una línea de frontend. Los schemas de Zod son lo primero que debes definir — no lo último.

Error #2: No Validamos el Schema de Zod Antes de Exportar

Comenzamos a escribir el export script sin tener los schemas de Zod completamente definidos. Esto significó que el script generaba JSON que después no pasaba la validación de Astro, y tuvimos que re-exportar varias veces.

El schema de Zod 4 (Astro 6 migró de Zod 3 a Zod 4) es más estricto que el anterior. Por ejemplo:

import { z, defineCollection } from 'astro:content';

const blogCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string().max(160),
    pubDate: z.date(),
    author: z.string(),
    image: z.string().optional(),
    tags: z.array(z.string()).optional(),
    category: z.enum(['marketing', 'webdevelopment', 'automation', 'media']),
  })
});

Cada campo faltante, tipo incorrecto o categoría inválida en el JSON exportado causaba un error de build. Con 2,500+ páginas, iterar sobre estos errores consumió medio día que pudimos haber evitado.

Lección: Define y congela los schemas de Zod antes de escribir CUALQUIER script de exportación. Invierte el flujo: schema primero, export después.

Error #3: Ignoramos el Costo de las Live Collections en Tráfico Alto

Astro 6 introdujo Live Collections como una alternativa dinámica a las Static Collections — contenido que se actualiza sin rebuild completo. Las usamos para la homepage y las secciones destacadas, ya que el cliente publica contenido nuevo varias veces al día.

Pero Live Collections no son gratis. En un pico de 50,000 visitas en una hora (cubrimos un evento en vivo), el servidor de Live Collections se saturó. La solución fue agregar Redis cache (TTL 60s) frente a las Live Collections, a un costo de ~$15/mes.

El problema no fue el costo — fue que no lo anticipamos en el diseño de arquitectura. Si lo hubiéramos hecho desde el día 1, habríamos ahorrado el tiempo de implementar el cache después del pico.

Lección: Si usas Live Collections para contenido que puede recibir picos de tráfico, presupuesta Redis cache desde la arquitectura inicial. Asume que cualquier página en Live Collections tendrá al menos un pico de 10x el tráfico normal.

Error #4: Dejamos el Pipeline de Imágenes para el Final

WordPress genera múltiples tamaños de imagen automáticamente al subir un archivo. Astro 6 con @astrojs/image puede hacer lo mismo, pero requiere configurar las variantes manualmente.

En nuestro caso, pospusimos la configuración del pipeline de imágenes pensando que era un detalle menor. Resultó ser la optimización individual de mayor impacto: las imágenes que los editores subían como PNGs de 5MB se servían como AVIF de 40-120KB — una reducción del 97-99%. Pero configurarlo requirió:

1. Definir 5 variantes por imagen (AVIF, WebP, JPEG en 2 tamaños cada una)
2. Configurar CDN externo para servir las variantes
3. Escribir guía para los editores sobre formatos de subida

Lección: El pipeline de imágenes debe ser lo SEGUNDO que configures después de los schemas de Zod. Es la optimización con mejor relación impacto/esfuerzo. Recomendamos AVIF como formato por defecto, WebP como fallback, y un tamaño máximo de 1920px para hero images.

Referencia: Cómo migramos de JPEG a AVIF en Astro: el ahorro real de ancho de banda.

Error #5: No Preparamos al Equipo Editorial para el Cambio de Flujo

La transición de Gutenberg (editor visual) a archivos Markdoc/JSON no es solo técnica — es cultural. Los editores estaban acostumbrados a arrastrar bloques, ver previews visuales y publicar con un clic.

En Astro 6, el contenido se escribe en archivos planos, se versiona con git, y se despliega mediante CI/CD. Para un equipo editorial que nunca usó línea de comandos, el cambio fue traumático. Tuvimos que:

• Construir un dashboard personalizado para que pudieran seguir publicando sin tocar terminal
• Escribir documentación detallada del flujo editorial en Astro
• Hacer sesiones de capacitación de 2 horas cada una durante 3 días

Lección: El change management para el equipo editorial toma tanto como la migración técnica. No asumas que porque el frontend es mejor, el equipo lo va a adoptar. Invierte en UI editorial y capacitación desde el inicio.

Marco de Decisión: ¿Tu Sitio Debe Migrar de WordPress a Astro 6?

Basado en esta experiencia y otros 3 proyectos similares, desarrollamos este marco de decisión:

Resultados Finales y Métricas Comparativas

El sitio pasó de tener un TTFB de 680ms desde servidores en Miami a 98ms servido desde el edge de Cloudflare en Panamá — una diferencia que los usuarios de Latinoamérica, que constituían el 70% de la audiencia, notaron de inmediato.

Lo Que Haríamos Diferente

Si pudiéramos hacer esta migración de nuevo, con el conocimiento actual:

1. Dedicar una semana completa al modelado de contenido con Zod antes de escribir código. La migración de datos siempre toma más de lo esperado, y tener los schemas correctos desde el día 1 ahorra iteraciones.
2. Pipeline de imágenes como prioridad #2. No como un detalle para después. La optimización de imágenes fue el mayor impacto individual en rendimiento.
3. Redis cache desde el día 1 para Live Collections. No esperar a que ocurra el primer pico de tráfico.
4. Capacitación editorial paralela a la migración técnica. No secuencial. El equipo editorial debería estar listo para publicar el día del lanzamiento.
5. Presupuestar 2x el tiempo de migración de contenido para cualquier proyecto con bloques personalizados de Gutenberg. Si el cliente tiene más de 3 tipos de bloques custom, asume que cada uno requerirá un parser dedicado.

Si estás evaluando una migración similar, te recomendamos leer también nuestro análisis de arquitectura multilingüe con Astro vs Next.js y cómo Astro maneja contenido multimedia pesado — ambos contienen datos de producción que complementan este caso de estudio.