Migrar de Hugo/Hexo/Next.js a Astro: guía detallada en 3 días

Introducción

Cada vez que abres tu blog y ves cómo carga despacio, algo se te encoge un poco. O quieres añadir una función pequeña a una plantilla de Hugo y descubres que la sintaxis es casi antinatural. O montaste un blog estático con Next.js y el JavaScript empaquetado es enorme para algo que solo debería mostrar artículos.

Yo pasé por lo mismo. Hasta que conocí Astro, el framework que promete llevar el rendimiento al máximo y sacar 100 en PageSpeed Insights sin esfuerzo. Al principio desconfiaba, pero al ver a más desarrolladores contar que la migración no era tan dura, me animé.

Aun así, migrar da respeto. Tres dudas suelen repetirse:

1. ¿Será muy pesado? Tengo decenas o cientos de artículos; ¿hay que tocarlos uno a uno?
2. ¿Afectará al SEO? ¿Y si cambian las URL?
3. ¿Qué trampas conviene conocer antes? No quieres quedarte a medias.

Si te identificas, este artículo es para ti. Recorro la ruta completa desde Hugo, Hexo y Next.js hacia Astro: pasos concretos, trampas habituales y buenas prácticas. Según la experiencia que he recopilado, el proceso suele llevar 1-3 días.

Por qué vale la pena migrar a Astro

Antes de los pasos, conviene ver por qué tantos equipos migran. No es moda: hay beneficios medibles.

Ventajas clave de Astro

Estrategia Zero JavaScript

La gran seña de Astro es el JS cero por defecto. Las páginas generadas no incluyen JavaScript salvo que lo pidas. Para blogs y documentación centrados en contenido, es una de las mejores palancas de rendimiento.

Un desarrollador japonés contó que, tras migrar de Next.js a Astro, PageSpeed Insights pasó de 85 a 100 y se mantuvo ahí en cada prueba. La mejora viene sobre todo de:

• Eliminar el JavaScript necesario para la hidratación
• Inlinar CSS y reducir peticiones de red

Arquitectura Islands

Los sitios modernos necesitan interactividad: comentarios, búsqueda, cambio de tema. Astro lo resuelve con Islands: en HTML estático añades JavaScript solo a los componentes que lo necesitan; el resto sigue siendo estático.

Es como una isla con vida dinámica rodeada de un mar de HTML estático.

Experiencia de desarrollo moderna

Si has usado Hugo, sabes lo incómoda que puede ser su sintaxis de plantillas. Astro es distinto: los archivos .astro se parecen mucho a JSX y puedes usar componentes de React, Vue, Svelte y otros frameworks habituales.

Un blogger lo resumió bien: en Hugo personalizar plantillas es incómodo aunque haya muchos temas open source; en Astro ajustar un tema es mucho más natural, con mentalidad de frontend moderno.

Comparación con otros frameworks

Tabla rápida de diferencias:

Qué proyectos encajan mejor

No todo proyecto debe migrar a Astro. Mira si el tuyo encaja en estas categorías:

Proyectos que encajan bien:

• Blogs personales y técnicos
• Documentación y bases de conocimiento
• Webs corporativas y páginas de producto
• Portfolios

Proyectos menos indicados:

• Aplicaciones de una sola página muy interactivas (dashboards, paneles de administración)
• Apps con actualización de datos en tiempo real
• Proyectos con mucho estado en el cliente

En resumen: si tu sitio es contenido primero, Astro encaja muy bien. Si necesitas mucha interactividad y estado en tiempo real, Next.js u otro framework SPA sigue siendo la opción sensata.

Preparación antes de migrar

No empieces a tocar código sin estos pasos; la migración irá mucho más fluida.

1. Copia de seguridad del proyecto actual

Es el paso más importante. Yo uso una rama de git:

# Crear rama de migración
git checkout -b migrate-to-astro

# Guardar el estado actual
git add .
git commit -m "Backup: inicio de migración a Astro"

Si algo sale mal, vuelves a la rama anterior.

2. Evaluar el volumen de trabajo

Antes de empezar, estima el esfuerzo:

Evaluación de contenido:

• Número de artículos: ____
• Sintaxis Markdown: estándar / extendida
• Número de imágenes: ____
• Ubicación de imágenes: rutas relativas / absolutas

Estimación de tiempo:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

• Menos de 50 artículos: 1 día
• 50-200 artículos: 2 días
• Más de 200: 3 días

3. Elegir un tema de Astro

Hay temas de blog muy buenos. Elegir uno parecido al actual ahorra tiempo:

Temas recomendados:

• AstroPaper: minimalista, ideal para blogs técnicos
• Fuwari: multidioma y con muchas funciones
• Astro Cactus: incluye árbol de categorías completo

Creación rápida:

# Con el tema AstroPaper
npm create astro@latest my-blog -- --template satnaing/astro-paper

# O con Fuwari
npm create astro@latest my-blog -- --template saicaca/fuwari

4. Preparar el entorno

Asegúrate de tener:

• Node.js: v18.14.1 o superior
• Gestor de paquetes: npm, pnpm o yarn
• Extensión de VS Code: Astro (oficial, imprescindible)

Pasos detallados: migrar desde Hugo

Hugo suele ser el caso más frecuente. La dificultad es media; el grueso del trabajo es convertir plantillas.

Paso 1: Crear el proyecto Astro

npm create astro@latest my-new-blog
cd my-new-blog
npm install

# Instalar integraciones habituales
npx astro add mdx sitemap

Paso 2: Migrar el contenido Markdown

Es el paso crítico. La buena noticia: el frontmatter de Hugo y Astro es en gran parte compatible; solo hay que ajustar algunos campos.

Mapeo de campos del frontmatter:

# Formato Hugo
---
title: "Mi artículo"
date: 2023-01-15
tags: ["frontend", "Astro"]
---

# Formato Astro (cambios marcados con ⬅)
---
title: "Mi artículo"
pubDate: 2023-01-15  ⬅ date pasa a pubDate
tags: ["frontend", "Astro"]
---

Con muchos artículos, puedes automatizar el reemplazo:

# macOS/Linux
find content -name "*.md" -exec sed -i '' 's/^date:/pubDate:/g' {} +

# Windows (PowerShell)
Get-ChildItem content -Filter *.md -Recurse | ForEach-Object {
    (Get-Content $_.FullName) -replace '^date:', 'pubDate:' | Set-Content $_.FullName
}

Paso 3: Trucos para convertir plantillas

Las plantillas de Hugo usan Go Template; Astro usa sintaxis tipo JSX. Un atajo: si ya tenías HTML, pégalo en un .astro y tendrás hecho gran parte del trabajo.

Ejemplo de plantilla Hugo:

{{ range .Pages }}
  <article>
    <h2>{{ .Title }}</h2>
    <p>{{ .Summary }}</p>
  </article>
{{ end }}

Equivalente en Astro:

---
const posts = await Astro.glob('../pages/blog/*.md');
---

{posts.map(post => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
  </article>
))}

La sintaxis resulta mucho más moderna.

Paso 4: Imágenes y recursos estáticos

Copia el contenido de static/ de Hugo a public/ de Astro, manteniendo las rutas:

cp -r hugo-blog/static/* astro-blog/public/

Si en los artículos usas rutas relativas o absolutas (por ejemplo /images/pic.jpg), no hace falta cambiarlas: lo de public/ se sirve desde la raíz del sitio.

Paso 5: Redirecciones de URL

Importante para el SEO. Si cambia la estructura de URL, configura redirecciones 301.

En astro.config.mjs:

export default defineConfig({
  redirects: {
    '/old-path': '/new-path',
    '/posts/[slug]': '/blog/[slug]',
  }
})

Pasos detallados: migrar desde Hexo

La migración desde Hexo es parecida a la de Hugo, con matices propios.

Paso 1: Crear el proyecto y configurar Content Collections

pnpm create astro@latest my-blog --template satnaing/astro-paper
cd my-blog
pnpm install

Astro gestiona el contenido con Content Collections; configúralo en src/content/config.ts:

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

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
    tags: z.array(z.string()),
  }),
});

export const collections = { blog };

Ese esquema valida el frontmatter y avisa si falta algún campo.

Paso 2: Migrar contenido e imágenes

Copia los artículos de source/_posts/ de Hexo a src/content/blog/ de Astro y reemplaza date por pubDate:

find src/content/blog -name "*.md" -exec sed -i 's/^date:/pubDate:/g' {} +

Para imágenes hay dos enfoques:

Opción 1: carpeta public/ (simple, recomendada)

cp -r hexo-blog/source/images astro-blog/public/images

Las rutas en los artículos no cambian.

Opción 2: componente Image de Astro (mejor rendimiento)

---
import { Image } from 'astro:assets';
import myImage from '../assets/pic.jpg';
---

<Image src={myImage} alt="Descripción" />

Paso 3: Redirecciones de rutas

Hexo suele usar /YYYY/MM/DD/post-name/; Astro por defecto /blog/post-name/.

Para conservar el formato antiguo, en astro.config.ts:

export default defineConfig({
  redirects: {
    '/:year/:month/:day/:slug': '/blog/:slug',
  }
})

Paso 4: RSS con contenido completo

Hexo suele publicar el cuerpo completo en el RSS; en Astro hay que configurarlo.

npx astro add rss

En src/pages/rss.xml.js:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
import { marked } from 'marked';

export async function GET(context) {
  const posts = await getCollection('blog');

  return rss({
    title: 'Mi blog',
    description: 'Descripción del blog',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      link: `/blog/${post.slug}/`,
      content: marked.parse(post.body), // contenido completo
    })),
  });
}

Pasos detallados: migrar desde Next.js

De Next.js a Astro es un poco más complejo por diferencias de arquitectura. Si usabas SSG en Next.js, la migración es más sencilla.

Paso 1: Entender las diferencias de arquitectura

Diferencias clave:

• Next.js es una SPA con un _app.js global
• Astro es un sitio multipágina (MPA); cada página es independiente

Similitudes:

• Ambos admiten JSX
• Enrutado por sistema de archivos
• SSG y SSR

Mentalmente no estás «migrando» una app Next.js completa, sino reconstruyendo un sitio de contenido con Astro.

Paso 2: Crear el proyecto e instalar React

npm create astro@latest my-blog
cd my-blog
npx astro add react

Con la integración de React puedes reutilizar componentes existentes.

Paso 3: Estrategia de migración de componentes

Astro admite .jsx y .tsx directamente; puedes copiar componentes React tal cual.

Componente Next.js (sin cambios):

// components/Button.jsx
export default function Button({ children, onClick }) {
  return <button onClick={onClick}>{children}</button>
}

Uso en Astro:

---
import Button from '../components/Button.jsx';
---

<Button client:load>Haz clic</Button>

La directiva client:load indica que el componente necesita JavaScript en el cliente (por defecto los componentes son estáticos).

Paso 4: Pasar componentes React a Astro

Para componentes sin interactividad, conviene convertirlos a .astro por rendimiento.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Componente React/Next.js:

export default function Card({ title, description }) {
  const formattedDate = new Date().toLocaleDateString();

  return (
    <div className="card">
      <h2>{title}</h2>
      <p>{description}</p>
      <span>{formattedDate}</span>
    </div>
  );
}

Componente Astro:

---
const { title, description } = Astro.props;
const formattedDate = new Date().toLocaleDateString();
---

<div class="card">
  <h2>{title}</h2>
  <p>{description}</p>
  <span>{formattedDate}</span>
</div>

Diferencias principales:

• className → class
• Props desde Astro.props
• JavaScript entre ---

Paso 5: Ajustar la estrategia de hidratación

Next.js hidrata por defecto; Astro no. Tú decides qué componentes necesitan interactividad:

Directivas de hidratación:

• client:load - hidrata al cargar la página
• client:idle - hidrata cuando el navegador está inactivo
• client:visible - hidrata al entrar en el viewport
• client:only - solo en el cliente

---
import Counter from '../components/Counter.jsx';
import HeavyChart from '../components/HeavyChart.jsx';
---

<!-- Interactividad inmediata -->
<Counter client:load />

<!-- Carga diferida, mejor rendimiento -->
<HeavyChart client:visible />

Elegir bien estas directivas marca una gran diferencia de rendimiento.

Paso 6: Rutas dinámicas

getStaticPaths de Next.js tiene equivalente en Astro con sintaxis muy parecida:

Ruta dinámica en Astro:

---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

Paso 7: Comparación de rendimiento

Aquí está la mayor ganancia. Según experiencias reales:

Antes (Next.js SSG):

• PageSpeed Insights: 85 puntos
• JS en la primera carga: ~200 KB
• Lighthouse Performance: 80-90

Después (Astro):

• PageSpeed Insights: 100 (de forma consistente)
• JS en la primera carga: ~10 KB (0 KB si no hay componentes interactivos)
• Lighthouse Performance: 95-100

La mejora viene de:

• Quitar el coste de hidratación de React
• Inlinar CSS y reducir peticiones
• Cargar JavaScript solo donde hace falta

Buenas prácticas generales de migración

Da igual el framework de origen; estas prácticas aplican a todos.

1. Migración por fases

No hace falta migrar todo de golpe:

Fase 1: piloto

• Migra 5-10 artículos
• Valida el flujo
• Mide la mejora de rendimiento

Fase 2: migración completa

• Todo el contenido
• Plantillas y componentes
• Reglas de redirección

Fase 3: pulido

• Funciones que falten
• Optimización de rendimiento
• Revisión SEO

Un blogger contó que al principio solo publicaba artículos nuevos en Astro y dejaba los antiguos donde estaban. Ese enfoque gradual reduce el riesgo.

2. Proteger el SEO

Lo que más preocupa en una migración. No te saltes esto:

Redirecciones 301

Si cambian las URL, configura 301:

// Vercel: vercel.json
{
  "redirects": [
    { "source": "/old-path/:slug", "destination": "/new-path/:slug", "permanent": true }
  ]
}

// Cloudflare Pages: _redirects
/old-path/:splat /new-path/:splat 301

Actualizar el sitemap

npx astro add sitemap

En astro.config.mjs:

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://yourdomain.com',
  integrations: [sitemap()],
});

Enviar a los buscadores

Tras la migración, envía el nuevo sitemap en Google Search Console y Bing Webmaster Tools.

3. Optimización de imágenes

Astro incluye componentes de optimización de imágenes; úsalos:

npx astro add image

Ejemplo:

---
import { Image } from 'astro:assets';
import cover from '../assets/cover.jpg';
---

<Image src={cover} alt="Imagen de portada" width={800} height={600} />

Ventajas: varios tamaños automáticos, conversión a WebP y carga diferida.

4. Lista de comprobación antes de publicar

No publiques sin revisar:

Contenido:

• Todos los artículos se muestran bien
• Frontmatter completo
• Enlaces internos funcionan
• Páginas de etiquetas y categorías correctas

Recursos:

• Imágenes cargan bien
• Estilos CSS aplicados

Funciones:

• Búsqueda operativa
• Sistema de comentarios operativo
• RSS disponible

SEO:

• Sitemap generado
• robots.txt correcto
• URL antiguas redirigen bien

Rendimiento:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

• Prueba en PageSpeed Insights
• Auditoría Lighthouse

Herramientas útiles:

• Broken Link Checker - enlaces rotos
• PageSpeed Insights - rendimiento
• Screaming Frog - rastreo SEO

Problemas frecuentes y soluciones

Estos son los fallos que más aparecen y cómo resolverlos.

1. Errores de build

Problema: Could not find Sharp

Dependencia de optimización de imágenes de Astro.

# Solución
npm install sharp

Si sigue fallando, desactiva la optimización en astro.config.mjs:

export default defineConfig({
  image: {
    service: { entrypoint: 'astro/assets/services/noop' }
  }
})

Problema: versión de MDX incompatible

Con Astro 5.0, actualiza @astrojs/mdx a v4.0.0:

npm install @astrojs/mdx@latest

2. Pérdida de estilos

Problema: estilos con alcance que no aplican

El <style> de Astro es scoped por defecto.

<!-- Estilo local -->
<style>
  .card { color: blue; }
</style>

<!-- Estilo global -->
<style is:global>
  .card { color: blue; }
</style>

Problema: estilos del contenido Markdown

El HTML generado desde Markdown necesita estilos globales:

<style is:global>
  .prose h1 { font-size: 2rem; }
  .prose h2 { font-size: 1.5rem; }
  .prose p { margin: 1rem 0; }
  .prose code { background: #f4f4f4; padding: 0.2rem 0.4rem; }
</style>

<article class="prose">
  <Content />
</article>

O usa el plugin Tailwind Typography.

3. Integración de servicios de terceros

Sistema de comentarios

Astro admite Disqus, Giscus, Utterances y otros:

<script
  src="https://giscus.app/client.js"
  data-repo="your-username/your-repo"
  data-repo-id="your-repo-id"
  data-category="Announcements"
  data-category-id="your-category-id"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="bottom"
  data-theme="light"
  data-lang="zh-CN"
  crossorigin="anonymous"
  async>
</script>

Analítica

Google Analytics se integra directamente:

<html>
  <head>
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'G-XXXXXXXXXX');
    </script>
  </head>
</html>

4. Configuración de despliegue

Vercel

Conecta el repositorio de GitHub; Vercel detecta Astro automáticamente.

Cloudflare Pages

Configuración de build:

• Build command: npm run build
• Build output directory: dist
• Node.js version: 18 o superior

GitHub Pages

En astro.config.mjs:

export default defineConfig({
  site: 'https://username.github.io',
  base: '/repo-name',
})

Conclusión

Migrar a Astro no es tan intimidante como parece. Según la experiencia que he recopilado, la mayoría termina en 1-3 días y queda satisfecha.

Resumen de puntos clave:

1. Copia de seguridad: rama git para poder volver atrás
2. Migración gradual: pocos artículos de prueba antes del volcado completo
3. Cuidar el SEO: 301, sitemap actualizado, proteger el ranking
4. Probar a fondo: enlaces, imágenes y funciones antes de publicar
5. Aprovechar el rendimiento: PageSpeed Insights a 100 es un objetivo realista

Mi consejo: si dudas, abre una rama de prueba, migra unos artículos y mide rendimiento. Si convence, sigue; si no, no pierdes nada.

Recursos útiles:

• Documentación oficial de Astro
• Comunidad Discord de Astro
• Biblioteca de temas de Astro

¡Buena migración! Si te atascas, comenta y lo vemos.