import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import { FileTree } from '@astrojs/starlight/components'; import { Steps } from '@astrojs/starlight/components';

Ce guide vous aidera à effectuer la migration à partir d'Astro v1 vers Astro v2.

Vous avez besoin de mettre à niveau un projet plus vieux vers la v1 ? Consultez notre ancien guide de migration.

Mettre à niveau Astro

Mettez à jour la version d'Astro de votre projet vers la dernière version à l'aide de votre gestionnaire de paquets. Si vous utilisez les intégrations Astro, veuillez également les mettre à jour vers la dernière version.

Exemple : mettre à niveau les intégrations React et Tailwind

npm install @astrojs/react@latest @astrojs/tailwind@latest

Exemple : mettre à niveau les intégrations React et Tailwind

yarn add @astrojs/react@latest @astrojs/tailwind@latest

Modifié : un dossier _astro/ dédié aux ressources générées

Dans la version 1.x, les ressources étaient générées à divers emplacements, notamment dans assets/, dans chunks/ et à la racine de la sortie de compilation.

Astro v2.0 déplace et unifie l'emplacement de toutes les ressources générées lors de la compilation vers un nouveau dossier _astro/.

Vous pouvez contrôler cet emplacement avec la nouvelle option de configuration build.assets.

Que devrais-je faire ?

Mettez à jour la configuration de votre plateforme de déploiement si elle dépend de l'emplacement de ces ressources.

Modifié : configuration des modules d'extension Markdown

Supprimé : extendDefaultPlugins

Dans la v1.x, Astro utilisait markdown.extendDefaultPlugins pour réactiver les modules d'extension par défaut d'Astro lors de l'ajout de vos propres modules d'extension Markdown.

Astro v2.0 supprime entièrement cette option de configuration puisqu'il s'agit désormais du comportement par défaut.

L'application de modules d'extension Remark et Rehype dans votre configuration Markdown ne désactive plus les modules d'extension par défaut d'Astro. GitHub-Flavored Markdown et Smartypants sont désormais appliqués, que vous personnalisiez ou non remarkPlugins et rehypePlugins.

Que devrais-je faire ?

Supprimez extendDefaultPlugins dans votre configuration. C'est désormais le comportement par défaut d'Astro dans la v2.0, et vous pouvez supprimer cette ligne sans aucun remplacement.

// astro.config.mjsimport { defineConfig } from 'astro/config';export default defineConfig({  markdown: {    extendDefaultPlugins,  }});

Ajouté : gfm et smartypants

Dans la v1.x, vous pouviez choisir de désactiver les deux modules d'extensions Markdown (GitHub-Flavored Markdown et SmartyPants) intégrées par défaut dans Astro en définissant markdown.extendDefaultPlugins: false.

Astro v2.0 remplace markdown.extendDefaultPlugins: false par des options booléennes distinctes pour contrôler individuellement chacun des modules d'extension Markdown intégrées par défaut dans Astro. Ces options sont activées par défaut et peuvent être définies sur false indépendamment.

Que devrais-je faire ?

Supprimez extendDefaultPlugins: false et ajoutez les options pour désactiver chaque module d'extension individuellement.

• markdown.gfm: false désactive GitHub-Flavored Markdown
• markdown.smartypants: false désactive SmartyPants

// astro.config.mjsimport { defineConfig } from 'astro/config';export default defineConfig({  markdown: {    extendDefaultPlugins: false,    smartypants: false,    gfm: false,  }});

Modifié : configuration des modules d'extension MDX

Remplacé : extendPlugins a été remplacé par extendMarkdownConfig

Dans la v1.x, l'option extendPlugins de l'intégration MDX gérait la façon dont vos fichiers MDX devaient hériter de votre configuration Markdown : toute votre configuration Markdown (markdown), ou les modules d'extension par défaut d'Astro uniquement (default).

Astro v2.0 remplace le comportement contrôlé par mdx.extendPlugins par trois nouvelles options configurables indépendamment qui sont définies sur true par défaut :

• mdx.extendMarkdownConfig pour hériter de tout ou aucune de votre configuration Markdown
• mdx.gfm pour activer ou désactiver GitHub-Flavored Markdown dans MDX
• mdx.smartypants pour activer ou désactiver SmartyPants dans MDX

Que devrais-je faire ?

Supprimez extendPlugins: 'markdown' dans votre configuration. C'est désormais le comportement par défaut.

// astro.config.mjsimport { defineConfig } from 'astro/config';import mdx from '@astrojs/mdx';export default defineConfig({  integrations: [    mdx({      extendPlugins: 'markdown',    }),  ],});

Remplacez extendPlugins: 'defaults' par extendMarkdownConfig: false et ajoutez les options distinctes pour GitHub-Flavored Markdown et SmartyPants pour activer ces modules d'extension par défaut individuellement dans MDX.

// astro.config.mjsimport { defineConfig } from 'astro/config';import mdx from '@astrojs/mdx';export default defineConfig({  integrations: [    mdx({      extendPlugins: 'defaults',      extendMarkdownConfig: false,      smartypants: true,      gfm: true,    }),  ],});

Ajouté : Plus d'options de configuration MDX pour correspondre à Markdown

Astro v2.0 vous permet désormais de définir individuellement chaque option de configuration Markdown disponible (à l'exception de drafts) séparément dans la configuration de votre intégration MDX.

// astro.config.mjsimport { defineConfig } from 'astro/config';import mdx from '@astrojs/mdx';export default defineConfig({  markdown: {    remarkPlugins: [remarkPlugin1],    gfm: true,  },  integrations: [    mdx({      remarkPlugins: [remarkPlugin2],      gfm: false,    })  ]});

Que devrais-je faire ?

Revisitez votre configuration Markdown et MDX et comparez votre configuration existante avec les nouvelles options disponibles.

Modifié : accès des modules d'extension au frontmatter

Dans la version 1.x, les modules d'extension Remark et Rehype n'avaient pas accès au frontmatter de l'utilisateur. Astro fusionnait le frontmatter des modules d'extension avec le frontmatter de votre fichier, sans transmettre ce dernier à vos modules d'extension.

Astro v2.0 donne aux modules d'extension Remark et Rehype l'accès au frontmatter de l'utilisateur via l'injection de frontmatter. Cela permet aux auteurs de modules d'extension de modifier le frontmatter existant d'un utilisateur ou de calculer de nouvelles propriétés basées sur d'autres propriétés.

Que devrais-je faire ?

Vérifiez tous les modules d'extension Remark et Rehype que vous avez écrites pour voir si leur comportement a changé. Notez que data.astro.frontmatter est désormais le frontmatter complet du document Markdown ou MDX, plutôt qu'un objet vide.

Modifié : Configuration RSS

Dans la v1.x, le paquet RSS d'Astro vous permettait d'utiliser items: import.meta.glob(...) pour générer une liste d'éléments de flux RSS. Cette utilisation est désormais dépréciée et sera éventuellement supprimée.

Astro v2.0 introduit une enveloppe pagesGlobToRssItems() à la propriété items.

Que devrais-je faire ?

Importez, puis enveloppez votre fonction existante contenant import.meta.glob() avec l'assistant pagesGlobToRssItems().

// src/pages/rss.xml.jsimport rss, {  pagesGlobToRssItems} from '@astrojs/rss';export async function get(context) {  return rss({    items: await pagesGlobToRssItems(      import.meta.glob('./blog/*.{md,mdx}'),    ),  });}

Modifié : prise en charge de Svelte dans les IDE

Astro v2.0 nécessite un fichier svelte.config.js dans votre projet si vous utilisez l'intégration @astrojs/svelte. Ceci est nécessaire pour fournir l’auto-complétion dans l’IDE.

Que devrais-je faire ?

Ajoutez un fichier svelte.config.js à la racine de votre projet :

// svelte.config.jsimport { vitePreprocess } from '@astrojs/svelte';export default {  preprocess: vitePreprocess(),};

Pour les nouveaux utilisateurs, ce fichier sera ajouté automatiquement lors de l'exécution de astro add svelte.

Supprimé : legacy.astroFlavoredMarkdown

Dans la version 1.0, Astro a déplacé l'ancien Astro-Flavored Markdown (également appelé composants dans Markdown) vers une fonctionnalité héritée.

Astro v2.0 supprime complètement l'option legacy.astroFlavoredMarkdown. L'importation et l'utilisation de composants dans les fichiers .md ne fonctionneront plus.

Que devrais-je faire ?

Supprimez cette option héritée. Elle n'est plus disponible dans Astro.

// astro.config.mjsexport default defineConfig({	legacy: {		astroFlavoredMarkdown: true,	},})

Si vous utilisiez cette fonctionnalité dans la v1.x, nous vous recommandons d'utiliser l'intégration MDX qui vous permet de combiner des composants et des expressions JSX avec la syntaxe Markdown.

Supprimé : Astro.resolve()

Dans la version 0.24, Astro a déprécié Astro.resolve() pour obtenir des URL résolues vers des ressources que vous pourriez vouloir référencer dans le navigateur.

Astro v2.0 supprime complètement cette option. La présence d'Astro.resolve() dans votre code provoquera une erreur.

Que devrais-je faire ?

Résolvez les chemins des ressources en utilisant plutôt import. Par exemple :

---// src/pages/index.astroimport 'style.css';import imageUrl from './image.png';---<img src={imageUrl} />

Supprimé : Astro.fetchContent()

Dans la version 0.26, Astro a déprécié Astro.fetchContent() pour récupérer les données de vos fichiers Markdown locaux.

Astro v2.0 supprime complètement cette option. La présence d'Astro.fetchContent() dans votre code provoquera une erreur.

Que devrais-je faire ?

Utilisez Astro.glob() pour récupérer les fichiers Markdown ou mettez à jour votre code pour utiliser la fonctionnalité Collections de contenu.

---// src/pages/index.astroconst allPosts = await Astro.glob('./posts/*.md');---

Supprimé : Astro.canonicalURL

Dans la version 1.0, Astro a déprécié Astro.canonicalURL pour construire une URL canonique.

Astro v2.0 supprime complètement cette option. La présence d'Astro.canonicalURL dans votre code provoquera une erreur.

Que devrais-je faire ?

Utilisez Astro.url pour construire une URL canonique.

---// src/pages/index.astroconst canonicalURL = new URL(Astro.url.pathname, Astro.site);---

Mis à jour : Vite 4

Astro v2.0 passe de Vite 3 à Vite 4, sorti en Décembre 2022.

Que devrais-je faire ?

Aucune modification de votre code ne devrait être nécessaire ! Nous avons géré la majeure partie de la mise à niveau pour vous dans Astro ; cependant, certains comportements subtils de Vite peuvent encore changer entre les versions.

Reportez-vous au Guide de migration Vite officiel si vous rencontrez des problèmes.

Options expérimentales supprimées dans Astro v2.0

Supprimez les options expérimentales suivantes de astro.config.mjs :

// astro.config.mjsimport { defineConfig } from 'astro/config';export default defineConfig({  experimental: {    contentCollections: true,    prerender: true,    errorOverlay: true,  },})

Ces fonctionnalités sont désormais disponibles par défaut :

• Collections de contenu comme moyen de gérer vos fichiers Markdown et MDX en garantissant la fiabilité des types Typescript.
• Pré-rendu de pages individuelles au format HTML statique lors de l'utilisation de SSR pour améliorer la vitesse et la mise en cache.
• Une superposition de messages d'erreur repensée.

Problèmes connus

Il n’y a actuellement aucun problème connu.