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

📚 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 (branche 6.4.x au moment de la rédaction), en même temps qu’une grosse mise à jour de dépendances (React 19.2, TypeScript 5.9, ESLint 10, Tailwind 4). 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 — à commencer par le pré-requis Node 22 : Astro 6 abandonne le support de Node 18 et 20. Voici ce que j’ai croisé sur le chemin.

🖼️ La rastérisation des SVG est désormais active

C’est le changement le plus visible si votre site utilise le composant <Image /> d’Astro avec des fichiers SVG. En Astro 5, le service d’images Sharp ignorait silencieusement la propriété format quand la source était un SVG : le fichier était renvoyé tel quel. À partir d’Astro 6, le service tente bel et bien la conversion vers le format demandé (PNG, WebP, AVIF…), ce qui peut casser des images jusqu’ici servies en vectoriel — notamment les SVG avec polices embarquées, qui sont l’une des limitations connues de Sharp.

La recommandation officielle, citée dans le guide de migration, est de tester explicitement le format avant d’appliquer une transformation :

<Image
	src={imageQuiPeutEtreUnSvg}
	format={imageQuiPeutEtreUnSvg.format === 'svg' ? 'svg' : 'avif'}
	alt="exemple"
/>

À noter, depuis Astro 6.3, l’option image.dangerouslyProcessSVG: true (disponible dans astro.config.mjs) permet d’activer explicitement le passage des SVG dans le pipeline d’optimisation d’image. Elle reste désactivée par défaut pour de bonnes raisons : un SVG malicieusement formé peut être coûteux à traiter (déni de service), d’où le préfixe dangerously.

// astro.config.mjs
import { defineConfig } from 'astro/config';
 
export default defineConfig({
	image: {
		dangerouslyProcessSVG: true
	}
});

Sur mon site, j’utilise des SVG simples (logos d’outils comme GitLab ou CircleCI), donc tester le format dans les composants <Image /> a suffi. Sur un projet plus sensible, je passerais composant par composant pour éviter les mauvaises surprises côté polices ou filtres.

📦 Les imports CSS « bare » deviennent plus stricts

Astro 6 embarque Vite 7, dont la résolution des modules s’est durcie. Conséquence : un import « side-effect » sans extension explicite, sur un package qui n’expose pas de types, peut désormais lever une erreur.

C’est typiquement le cas avec Fontsource :

// ❌ Peut casser selon la version du package
import '@fontsource-variable/noto-sans';
 
// ✅ Précisez l'entrée explicite
import '@fontsource-variable/noto-sans/index.css';

astro check retourne un message 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 la résolution.

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

Astro 6.4 introduit une nouvelle option markdown.processor, et déprécie dans la foulée les configurations historiques markdown.remarkPlugins, markdown.rehypePlugins, markdown.remarkRehype et markdown.gfm. Aucune coupure immédiate, mais le but est clair : centraliser la configuration du pipeline derrière unified() (ou satteri(), l’alternative officielle introduite en parallèle).

La nouvelle forme recommandée :

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkReadingTime from 'remark-reading-time';
import rehypePrettyCode from 'rehype-pretty-code';
 
export default defineConfig({
	markdown: {
		processor: unified({
			remarkPlugins: [remarkReadingTime],
			rehypePlugins: [rehypePrettyCode]
		})
	}
});

Pour les projets qui empilent quelques plugins (chez moi, rehype-pretty-code et remark-reading-time), la migration tient en quelques lignes. Rien d’urgent, mais c’est le genre de dette qui se paie quand la prochaine majeure arrivera et supprimera l’ancienne 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 → 5.9 : aucune adaptation à signaler.
• Vite 6 → 7 (transitif via Astro) : c’est ce qui rend le contrôle des imports plus strict (voir Fontsource ci-dessus).
• 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 : à mettre à jour pour rester compatible Vite 7 et Node 22.

✅ Checklist de migration

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

1. Vérifier que votre environnement (local + déploiement) tourne sur Node 22 ou plus.
2. Bumper Astro et les intégrations officielles dans le package.json.
3. Lancer npm install et regarder les peer warnings : certains plugins ESLint et Tailwind ne suivent pas immédiatement les majors.
4. Exécuter astro check pour repérer les imports CSS « bare » à corriger.
5. Exécuter astro build et vérifier les composants <Image /> pointant sur des SVG : conditionner format selon image.format === 'svg' pour éviter une rastérisation involontaire.
6. Réviser les endpoints .xml.ts, .json.ts : ils ne sont plus accessibles avec un slash final, peu importe build.trailingSlash.
7. 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

• Site officiel Astro
• Documentation Astro
• Guide officiel : Upgrade to Astro v6
• Notes de version Astro