Migrer de Hugo/Hexo/Next.js vers Astro : guide détaillé en 3 jours

Introduction

Chaque fois que j’ouvre mon blog et que je vois le chargement traîner, ça me chagrine un peu. Ou alors j’essaie d’ajouter une petite fonction à un template Hugo et je me heurte à une syntaxe vraiment peu intuitive. Ou encore, avec Next.js en statique, le bundle JavaScript est énorme — pour un simple blog, pourquoi charger autant de code ?

J’ai vécu tout ça. Puis j’ai entendu parler d’Astro — un framework qui promet des performances au top, PageSpeed Insights à 100 sans effort. J’étais sceptique, mais de plus en plus de développeurs partageaient des retours positifs : la migration n’est pas si complexe. J’ai craqué.

Mais entre l’envie et l’action, il reste des inquiétudes :

1. La migration sera-t-elle pénible ? Des dizaines ou centaines d’articles à retoucher un par un ?
2. Et le SEO ? Si la structure d’URL change ?
3. Quels pièges anticiper ? Ne pas rester bloqué à mi-chemin.

Si vous partagez ces doutes, cet article est pour vous. Je détaille le parcours complet depuis Hugo, Hexo et Next.js vers Astro : opérations concrètes, pièges courants et bonnes pratiques. D’après les retours collectés, comptez 1 à 3 jours.

Pourquoi migrer vers Astro

Pourquoi tant de monde migre ? Ce n’est pas une mode — les bénéfices sont concrets.

Atouts principaux d’Astro

Stratégie zéro JavaScript

La grande force d’Astro : zéro JavaScript par défaut. Les pages générées n’incluent aucun JS. Pour un blog ou une doc, c’est l’optimisation performance ultime.

Un développeur japonais raconte : après migration Next.js → Astro, PageSpeed Insights est passé de 85 à 100 — à chaque test. Deux facteurs :

• Suppression du JavaScript d’hydratation
• CSS inliné, moins de requêtes réseau

Architecture Islands

Un site moderne a quand même besoin d’interactivité : commentaires, recherche, bascule de thème. Astro répond avec les Islands — vous ajoutez du JavaScript uniquement aux composants interactifs dans une page HTML statique.

Comme une île au milieu d’un océan statique : seule l’île est dynamique.

Expérience de développement moderne

Si vous avez utilisé Hugo, vous connaissez ses templates. Astro est différent : les fichiers .astro ressemblent presque à du JSX, avec React, Vue, Svelte, etc.

Un blogueur résume bien : personnaliser un thème Hugo est difficile malgré les templates open source ; avec Astro, ajuster un thème suit la logique du frontend moderne.

Comparaison avec les autres frameworks

Quels projets conviennent à la migration

Tous les projets ne doivent pas migrer. Vérifiez d’abord :

Projets adaptés :

• Blog personnel, blog technique
• Documentation, base de connaissances
• Site vitrine, pages produit
• Portfolio

Projets moins adaptés :

• SPA très interactive (dashboard, back-office)
• Applications avec mises à jour temps réel
• Applications avec beaucoup d’état côté client

En clair : si votre site est « contenu d’abord », Astro est fait pour vous. Beaucoup d’interactivité et de temps réel ? Restez sur Next.js ou une SPA.

Préparation avant migration

Ne vous lancez pas tout de suite. Ces étapes facilitent grandement la suite.

1. Sauvegarder le projet existant

C’est l’étape la plus importante. Je recommande une branche git :

# Créer une branche de migration
git checkout -b migrate-to-astro

# Sauvegarder l'état actuel
git add .
git commit -m "Backup : début migration vers Astro"

En cas de problème, vous revenez à la branche d’origine.

2. Estimer la charge de travail

Avant de commencer, faites le point :

Contenu :

• Nombre d’articles : ____
• Syntaxe Markdown : standard / étendue
• Nombre d’images : ____
• Stockage images : chemins relatifs / absolus

Estimation du temps :

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

• Moins de 50 articles : 1 jour
• 50–200 articles : 2 jours
• Plus de 200 : 3 jours

3. Choisir un thème Astro

De nombreux thèmes de blog existent. Un style proche de l’actuel fait gagner du temps :

Thèmes recommandés :

• AstroPaper : épuré, idéal pour un blog technique
• Fuwari : multilingue, riche en fonctionnalités
• Astro Cactus : arborescence complète

Création rapide :

# Thème AstroPaper
npm create astro@latest my-blog -- --template satnaing/astro-paper

# Ou thème Fuwari
npm create astro@latest my-blog -- --template saicaca/fuwari

4. Préparer l’environnement

• Node.js : v18.14.1 ou supérieur
• Gestionnaire de paquets : npm, pnpm ou yarn
• Extension VS Code : Astro (officielle, indispensable)

Migration depuis Hugo — étapes détaillées

Hugo compte probablement le plus d’utilisateurs — je commence par lui. Difficulté modérée, surtout conversion de templates.

Étape 1 : Créer le projet Astro

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

# Intégrations courantes
npx astro add mdx sitemap

Étape 2 : Migrer le contenu Markdown

Étape clé. Bonne nouvelle : le frontmatter Hugo et Astro est largement compatible, quelques champs à ajuster.

Correspondance des champs frontmatter :

# Format Hugo
---
title: "Mon article"
date: 2023-01-15
tags: ["frontend", "Astro"]
---

# Format Astro (⬅ = modification)
---
title: "Mon article"
pubDate: 2023-01-15  ⬅ date → pubDate
tags: ["frontend", "Astro"]
---

Pour beaucoup d’articles, un script de remplacement en lot :

# 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
}

Étape 3 : Conversion des templates

Hugo utilise Go Template, Astro une syntaxe proche de JSX. Astuce : si vous aviez du HTML, collez-le dans un fichier .astro — 70 % du travail est fait.

Exemple Hugo :

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

Conversion 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 syntaxe est plus moderne, non ?

Étape 4 : Images et ressources statiques

Copiez le contenu de static/ Hugo vers public/ Astro, chemins inchangés :

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

Les références /images/pic.jpg ou chemins relatifs restent valides : public/ est servi à la racine.

Étape 5 : Redirections d’URL

Crucial pour le SEO. Si la structure d’URL change, configurez des redirections 301.

Dans astro.config.mjs :

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

Migration depuis Hexo — étapes détaillées

Similaire à Hugo, avec quelques spécificités Hexo.

Étape 1 : Projet et Content Collections

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

Astro gère le contenu via Content Collections, configurées dans 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 };

Validation des types sur le frontmatter — très pratique.

Étape 2 : Contenu et images

Copiez source/_posts/ vers src/content/blog/, puis remplacez date par pubDate :

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

Deux approches pour les images :

Option 1 : répertoire public/ (simple, recommandé)

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

Chemins dans les articles inchangés.

Option 2 : composant Image Astro (meilleures perfs)

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

<Image src={myImage} alt="Description" />

Étape 3 : Redirections de chemins

Hexo : /YYYY/MM/DD/post-name/ par défaut. Astro : /blog/post-name/.

Pour conserver l’ancien format :

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

Étape 4 : RSS en contenu intégral

Hexo sort le RSS en intégral par défaut ; Astro nécessite une config manuelle.

npx astro add rss

Dans 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: 'Mon blog',
    description: 'Description du 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), // contenu intégral
    })),
  });
}

Migration depuis Next.js — étapes détaillées

Un peu plus complexe — différence d’architecture. En mode SSG Next.js, c’est plus simple.

Étape 1 : Comprendre les différences d’architecture

Différences clés :

• Next.js : SPA avec _app.js global
• Astro : MPA, chaque page est indépendante

Points communs :

• Syntaxe JSX
• Routage par fichiers
• SSG et SSR

À garder en tête : vous ne « migrez » pas une app Next.js — vous reconstruisez un site de contenu avec Astro.

Étape 2 : Projet et intégration React

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

Vous pouvez réutiliser vos composants React existants.

Étape 3 : Stratégie de migration des composants

Astro accepte .jsx et .tsx directement.

Composant Next.js (inchangé) :

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

Utilisation dans Astro :

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

<Button client:load>Cliquez-moi</Button>

client:load indique qu’Astro doit charger du JavaScript (par défaut, les composants sont statiques).

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Étape 4 : Convertir les composants React en composants Astro

Pour les composants sans interactivité, préférez Astro — meilleures perfs.

Composant Next.js/React :

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>
  );
}

Composant Astro :

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

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

Principales différences :

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

Étape 5 : Ajuster la stratégie d’hydratation

Next.js hydrate par défaut tous les composants ; Astro non.

Indiquez manuellement les composants interactifs :

Directives d’hydratation :

• client:load — hydrate au chargement
• client:idle — quand le navigateur est inactif
• client:visible — quand le composant entre dans le viewport
• client:only — rendu client uniquement

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

<!-- Interaction immédiate -->
<Counter client:load />

<!-- Chargement différé, meilleures perfs -->
<HeavyChart client:visible />

Stratégie cruciale pour les performances.

Étape 6 : Routes dynamiques

getStaticPaths de Next.js a son équivalent 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>

Étape 7 : Comparaison des gains de performance

Le plus gros bénéfice de la migration :

Avant (Next.js SSG) :

• PageSpeed Insights : 85
• JS au premier chargement : ~200 Ko
• Lighthouse Performance : 80–90

Après (Astro) :

• PageSpeed Insights : 100 (à chaque test)
• JS au premier chargement : ~10 Ko (0 Ko sans composants interactifs)
• Lighthouse Performance : 95–100

Sources du gain :

• Suppression du coût d’hydratation React
• CSS inliné, moins de requêtes
• JavaScript chargé à la demande

Bonnes pratiques communes à toute migration

Quel que soit le framework source :

1. Migration par phases

Pas besoin de tout migrer d’un coup :

Phase 1 : pilote

• 5–10 articles test
• Valider le processus
• Mesurer les gains

Phase 2 : migration complète

• Tous les articles
• Templates et composants
• Règles de redirection

Phase 3 : peaufinage

• Fonctions manquantes
• Optimisation performance
• Contrôle SEO

Un blogueur n’a migré que ses nouveaux articles vers Astro au début — approche progressive, risque limité.

2. Protéger le SEO

Redirections 301

Si les URLs changent :

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

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

Mettre à jour le sitemap

npx astro add sitemap

Dans astro.config.mjs :

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

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

Soumettre aux moteurs

Après migration : Google Search Console et Bing Webmaster Tools — nouveau sitemap.

3. Optimisation des images

Le composant Image d’Astro vaut le coup :

npx astro add image

Exemple :

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

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

Avantages : tailles multiples, WebP automatique, lazy loading.

4. Checklist de tests

Avant la mise en ligne :

Contenu :

• Tous les articles s’affichent
• Frontmatter complet
• Liens internes cliquables
• Pages tags et catégories OK

Ressources :

• Images chargées
• CSS appliqué

Fonctionnalités :

• Recherche
• Commentaires
• RSS

SEO :

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

• Sitemap généré
• robots.txt correct
• Anciennes URLs redirigées

Performance :

• PageSpeed Insights
• Lighthouse

Outils utiles :

• Broken Link Checker — liens morts
• PageSpeed Insights — performance
• Screaming Frog — crawl SEO

Problèmes courants et solutions

1. Erreurs de build

Problème : Could not find Sharp

Dépendance pour l’optimisation d’images Astro.

# Solution
npm install sharp

Sinon, désactiver l’optimisation dans astro.config.mjs :

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

Problème : version MDX incompatible

Avec Astro 5.0, mettre à jour @astrojs/mdx vers v4.0.0 :

npm install @astrojs/mdx@latest

2. Styles perdus

Problème : portée CSS (scoped)

Les balises <style> Astro sont scoped par défaut.

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

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

Problème : styles du contenu Markdown

Le HTML rendu depuis Markdown nécessite des styles globaux :

<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>

Ou le plugin Tailwind Typography.

3. Services tiers

Système de commentaires

Disqus, Giscus, Utterances — tous compatibles :

<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="fr"
  crossorigin="anonymous"
  async>
</script>

Analytics

Google Analytics :

<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. Configuration du déploiement

Vercel

Connectez le dépôt GitHub — Vercel détecte Astro automatiquement.

Cloudflare Pages

• Build command : npm run build
• Build output directory : dist
• Node.js : 18 ou supérieur

GitHub Pages

Dans astro.config.mjs :

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

Conclusion

En résumé, migrer vers Astro n’est pas si effrayant. La plupart des développeurs terminent en 1 à 3 jours, satisfaits du résultat.

Points clés :

1. Sauvegarder : branche git, retour arrière possible
2. Migration progressive : piloter quelques articles avant la migration complète
3. Protéger le SEO : 301, sitemap, classements
4. Tester : liens, images, fonctionnalités avant mise en ligne
5. Profiter des gains : PageSpeed Insights à 100 facilement

Mon conseil : hésitez-vous encore ? Créez une branche de test, migrez quelques articles, lancez un benchmark. Satisfait ? Allez-y. Sinon, aucune perte.

Ressources utiles :

• Documentation officielle Astro
• Communauté Discord Astro
• Bibliothèque de thèmes Astro

Bonne migration ! Des questions ? Commentez ci-dessous.