Mise à niveau vers Astro v2

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.

# Mise à niveau vers Astro v2.x
npm install astro@latest

# Exemple : mettre à niveau les intégrations React et Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

# Mise à niveau vers Astro v2.x
pnpm add astro@latest

# Exemple : mettre à niveau les intégrations React et Tailwind
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

# Mise à niveau vers Astro v2.x
yarn add astro@latest

# Exemple : mettre à niveau les intégrations React et Tailwind
yarn add @astrojs/react@latest @astrojs/tailwind@latest

Changements non rétrocompatibles dans Astro v2.0

Astro v2.0 inclut quelques modifications majeures avec rupture de compatibilité, ainsi que la suppression de certaines fonctionnalités précédemment dépréciées. Si votre projet ne fonctionne pas comme prévu après la mise à niveau vers la version 2.0, consultez ce guide pour obtenir un aperçu de tous les changements non rétrocompatibles et des instructions sur la façon de mettre à jour votre base de code.

Consultez le journal des modifications pour accéder aux notes de version complètes.

Supprimé : prise en charge de Node 14

Node 14 devrait atteindre sa fin de vie en avril 2023.

Astro v2.0 abandonne entièrement la prise en charge de Node 14, afin que tous les utilisateurs d’Astro puissent profiter des fonctionnalités plus modernes de Node.

Que devrais-je faire ?

Vérifiez que votre environnement de développement et votre environnement de déploiement utilisent Node 16.12.0 ou une version ultérieure.

Vérifiez votre version locale de Node en utilisant :
Fenêtre du terminal
```
node -v
```
Si votre environnement de développement local doit être mis à niveau, installez Node.
Consultez la documentation de votre environnement de déploiement pour vérifier qu’il prend en charge Node 16.

Vous pouvez spécifier Node 16.12.0 pour votre projet Astro soit dans un paramètre de configuration du tableau de bord, soit dans un fichier .nvmrc.

Réservé : `src/content/`

Astro v2.0 inclut désormais l’API Collections pour organiser vos fichiers Markdown et MDX en collections de contenu. Cette API réserve src/content/ comme dossier spécial.

Que devrais-je faire ?

Renommez un dossier src/content/ existant pour éviter les conflits. Ce dossier, s’il existe, ne peut désormais être utilisé que pour les collections de contenu.

Modifié : la barre oblique finale d’`Astro.site`

Dans la version 1.x, Astro garantissait que l’URL que vous définissez comme site dans astro.config.mjs contenait toujours une barre oblique finale lors de l’accès à l’aide de Astro.site.

Astro v2.0 ne modifie plus la valeur de site. Astro.site utilisera la valeur exacte définie, et une barre oblique finale doit être spécifiée si vous la souhaitez.

Que devrais-je faire ?

Dans astro.config.mjs, ajoutez une barre oblique finale à l’URL définie dans site.

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  site: 'https://example.com/',
});

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

Répertoiredist/
- Répertoire_astro
  - client.9218e799.js
  - index.df3f880e0.css

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.

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

import { 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.

import { 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.

import { 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.

import { 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().

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

import { 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.

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

---
import '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.

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

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

import { 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.

Contribuer Communauté Parrainer

Mise à niveau vers Astro v2

Mettre à niveau Astro

Changements non rétrocompatibles dans Astro v2.0

Supprimé : prise en charge de Node 14

Que devrais-je faire ?

Réservé : src/content/

Que devrais-je faire ?

Modifié : la barre oblique finale d’Astro.site

Que devrais-je faire ?

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

Que devrais-je faire ?

Modifié : configuration des modules d’extension Markdown

Supprimé : extendDefaultPlugins

Que devrais-je faire ?

Ajouté : gfm et smartypants

Que devrais-je faire ?

Modifié : configuration des modules d’extension MDX

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

Que devrais-je faire ?

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

Que devrais-je faire ?

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

Que devrais-je faire ?

Modifié : Configuration RSS

Que devrais-je faire ?

Modifié : prise en charge de Svelte dans les IDE

Que devrais-je faire ?

Supprimé : legacy.astroFlavoredMarkdown

Que devrais-je faire ?

Supprimé : Astro.resolve()

Que devrais-je faire ?

Supprimé : Astro.fetchContent()

Que devrais-je faire ?

Supprimé : Astro.canonicalURL

Que devrais-je faire ?

Mis à jour : Vite 4

Que devrais-je faire ?

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

Problèmes connus

Réservé : `src/content/`

Modifié : la barre oblique finale d’`Astro.site`

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

Supprimé : `extendDefaultPlugins`

Ajouté : `gfm` et `smartypants`

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

Supprimé : `legacy.astroFlavoredMarkdown`

Supprimé : `Astro.resolve()`

Supprimé : `Astro.fetchContent()`

Supprimé : `Astro.canonicalURL`