← Tous les articles
Mer. 28 janvier 2026 · 4 min de lecture

🚀 Migrer un site de Astro 5 à Astro 6 : les pièges à éviter

# Astro # Migration # TypeScript
Astro

📚 Introduction

Quand une version majeure de framework sort, il y a toujours deux écoles : celles et ceux qui upgradent dès le premier jour, et celles et ceux qui attendent que la poussière retombe. J’avoue volontiers faire partie de la première catégorie, surtout sur mon site personnel — c’est l’endroit idéal pour tester les nouveautés sans casser un projet client.

Je viens de faire passer ce site de Astro 5 à Astro 6, en même temps qu’une grosse mise à jour de dépendances (React 19.2, TypeScript 6, ESLint 10, Tailwind 4.3). La bonne nouvelle, c’est que la migration s’est faite en quelques minutes. La moins bonne, c’est qu’il y a deux ou trois pièges qui ne sautent pas aux yeux à la lecture du changelog. Voici donc ce que j’ai croisé sur le chemin.

🖼️ Le traitement des SVG est désactivé par défaut

C’est de loin le changement le plus visible si votre site utilise le composant <Image /> d’Astro avec des fichiers SVG. À partir d’Astro 6, le service d’images refuse de traiter les sources SVG par défaut. Le build casse avec une erreur très explicite :

UnsupportedImageFormat: SVG image processing is disabled, but the source for "..." is an SVG.
Pass it through unchanged by setting `format="svg"` on the component,
or set `image.dangerouslyProcessSVG: true` to rasterize SVG sources.

Deux options pour s’en sortir, selon votre besoin :

  1. Laisser passer les SVG sans transformation, en ajoutant format="svg" sur chaque utilisation du composant Image. C’est l’option la plus sûre, parce qu’on évite la rasterisation et qu’on garde un vrai SVG en sortie.
  2. Réactiver le traitement global, en ajoutant un flag dans la configuration :
// astro.config.mjs
export default defineConfig({
	image: {
		remotePatterns: [{ protocol: 'https' }],
		dangerouslyProcessSVG: true
	}
});

Le préfixe dangerously n’est pas là par hasard : la rasterisation de SVG peut produire des résultats inattendus avec certains contenus dynamiques ou des polices intégrées. Sur mon site, j’utilise des SVG simples (logos de tools comme GitLab ou CircleCI), donc j’ai opté pour le flag global. Sur un projet plus sensible, je passerais composant par composant.

📦 Les imports CSS « bare » deviennent plus stricts

Astro 6 s’appuie sur TypeScript 6, qui durcit la résolution des modules. Conséquence : un import « side-effect » sans extension explicite, sur un package qui n’expose pas de types, ne passe plus.

C’est typiquement le cas avec Fontsource :

// ❌ Ne passe plus en TS 6
import '@fontsource-variable/noto-sans';
 
// ✅ Précisez l'entrée explicite
import '@fontsource-variable/noto-sans/index.css';

Le message d’erreur d’astro check est limpide :

Cannot find module or type declarations for side-effect import of '@fontsource-variable/noto-sans'.

La règle générale est simple : si un package n’exporte que du CSS et pas de types, importez explicitement le fichier .css cible. Ça marche partout, c’est plus lisible, et ça vous met à l’abri du prochain durcissement de TypeScript.

📝 markdown.remarkPlugins et markdown.rehypePlugins sont dépréciés

C’est une dépréciation, donc pas un blocage immédiat, mais autant le noter. Le build affiche désormais :

[astro] `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` sont dépréciés.
Passez-les à `unified({...})` depuis `@astrojs/markdown-remark` directement.

Pour les projets qui empilent quelques plugins (chez moi, rehype-pretty-code et remark-reading-time), il faudra prévoir une réécriture de la configuration markdown dans une prochaine itération. Rien d’urgent, mais c’est le genre de dette qui se paie quand la version 7 arrivera et supprimera l’API.

⚙️ Les autres dépendances qui montent en même temps

Un upgrade Astro est souvent l’occasion de remettre à plat le reste du package.json. Dans mon cas, j’ai aussi monté :

  • React 19.1 → 19.2 : pas de changement visible côté composants existants.
  • TypeScript 5.8 → 6.0 : c’est lui qui révèle l’import Fontsource ci-dessus, mais sinon tout passe sans toucher au code.
  • ESLint 9 → 10 : attention au peer dependency de certains plugins (eslint-plugin-jsx-a11y n’a pas encore déclaré le support officiel d’ESLint 10, le lint fonctionne malgré l’avertissement).
  • @astrojs/vercel 8 → 10 et @vercel/analytics 1 → 2 : aucune adaptation nécessaire pour mon usage.

✅ Checklist de migration

Pour résumer, si vous attaquez la même migration, voici les points à cocher :

  1. Bumper Astro et les intégrations officielles dans le package.json.
  2. Lancer npm install et regarder les peer warnings : certains plugins ESLint et Tailwind ne suivent pas immédiatement les majors.
  3. Exécuter astro check pour repérer les imports CSS « bare » à corriger.
  4. Exécuter astro build et vérifier le traitement des SVG : ajouter dangerouslyProcessSVG: true ou passer format="svg" au cas par cas.
  5. Noter les warnings de dépréciation pour les traiter dans une prochaine itération (notamment la configuration markdown).

🎉 Conclusion

Astro 6 reste fidèle à l’ADN du framework : une migration courte, des messages d’erreur qui pointent directement vers la solution, et une vraie attention portée à la rétrocompatibilité. Les pièges rencontrés ici ne sont pas dramatiques, mais ils ont la particularité d’être faciles à manquer si on se contente d’un npm update rapide.

Mon conseil : prenez un moment pour relire la configuration image et les imports CSS de votre projet, et planifiez la migration de la configuration markdown sur une itération dédiée. Le reste devrait passer tout seul.

🔗 Liens utiles