Mise à niveau vers Astro v5

Ce guide vous aidera à migrer d’Astro v4 à Astro v5.

Vous devez d’abord mettre à niveau un ancien projet vers la version 4 ? Consultez notre ancien guide de migration.

Besoin de voir la documentation de la v4 ? Visitez cette ancienne version du site de documentation (instantané de la v4.16 non maintenu).

Mettre à niveau Astro

Mettez à niveau la version d’Astro de votre projet vers la dernière version en utilisant votre gestionnaire de paquets :

npm

# Mettre à niveau Astro et les intégrations officielles ensemble
npx @astrojs/upgrade

pnpm

# Mettre à niveau Astro et les intégrations officielles ensemble
pnpm dlx @astrojs/upgrade

Yarn

# Mettre à niveau Astro et les intégrations officielles ensemble
yarn dlx @astrojs/upgrade

Vous pouvez également mettre à niveau manuellement vos intégrations Astro si nécessaire, et vous devrez peut-être aussi mettre à niveau d’autres dépendances de votre projet.

Besoin de continuer ?

Après avoir mis à niveau Astro, il est possible que vous n’ayez pas besoin d’apporter de modifications à votre projet !

Cependant, si vous remarquez des erreurs ou un comportement inattendu, veuillez vérifier ci-dessous ce qui a changé et qui pourrait nécessiter une mise à jour dans votre projet.

Astro v5.0 inclut des changements potentiellement non rétrocompatibles, ainsi que la suppression et la dépréciation de certaines fonctionnalités.

Si votre projet ne fonctionne pas comme prévu après la mise à niveau vers la version 5.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 d’Astro pour les notes de version complètes.

Mises à niveau des dépendances

Toute mise à niveau majeure des dépendances d’Astro peut entraîner des changements avec rupture de compatibilité dans votre projet.

Vite 6.0

Astro v5.0 passe à Vite v6.0 comme serveur de développement et regroupeur de production.

Que dois-je faire ?

Si vous utilisez des modules d’extension, une configuration ou des API spécifiques à Vite, consultez le guide de migration de Vite pour connaître leurs changements non rétrocompatibles et mettez à jour votre projet si nécessaire.

@astrojs/mdx

PR d'implémentation : Nettoyage du code JSX inutilisé (#11741)

Dans Astro v4.x, Astro effectuait un traitement interne du JSX pour l’intégration @astrojs/mdx.

Astro v5.0 transfère cette responsabilité de gestion et de rendu du JSX et MDX directement au paquet @astrojs/mdx. Cela signifie qu’Astro 5.0 n’est plus compatible avec les anciennes versions de l’intégration MDX.

Que dois-je faire ?

Si votre projet inclut des fichiers .mdx, vous devez mettre à niveau @astrojs/mdx vers la dernière version (v4.0.0) afin que votre JSX soit correctement géré par l’intégration.

Si vous utilisez un moteur de rendu MDX côté serveur avec l’API expérimentale des conteneurs d’Astro (EN), vous devez mettre à jour l’importation pour refléter le nouvel emplacement :

import mdxRenderer from "astro/jsx/server.js";
import mdxRenderer from "@astrojs/mdx/server.js";

En savoir plus sur l’utilisation de MDX dans votre projet.

Héritage

Les fonctionnalités suivantes sont désormais considérées comme des fonctionnalités héritées. Elles devraient fonctionner normalement mais ne sont plus recommandées et sont en mode maintenance. Elles ne bénéficieront d’aucune amélioration future et la documentation ne sera pas mise à jour. Ces fonctionnalités seront éventuellement dépréciées, puis complètement supprimées.

Héritage : API des collections de contenu de la v2.0

Dans Astro 4.x, les collections de contenu étaient définies, interrogées et rendues en utilisant l’API des collections de contenu introduite pour la première fois dans Astro v2.0. Toutes les entrées de la collection étaient des fichiers locaux dans le dossier réservé src/content/. De plus, la convention de nom de fichier d’Astro visant à exclure la création de pages individuelles a été intégrée à l’API des collections de contenu.

Astro 5.0 introduit une nouvelle version des collections de contenu utilisant l’API de la couche de contenu qui apporte plusieurs améliorations de performance et des capacités supplémentaires. Bien que les anciennes collections (héritées) et les nouvelles (API de la couche de contenu) puissent continuer à coexister dans cette version, il y a potentiellement des changements non rétrocompatibles pour les collections héritées existantes.

Cette version supprime également l’option permettant de préfixer les noms de fichiers d’entrée de collection avec un trait de soulignement (_) pour empêcher la création d’une route.

Que dois-je faire ?

Nous recommandons de convertir toutes les collections existantes vers la nouvelle API de la couche de contenu dès que possible et de créer toute nouvelle collection en utilisant l’API de la couche de contenu.

Si vous ne pouvez pas convertir vos collections, veuillez consulter les changements non rétrocompatibles pour les collections héritées pour voir si vos collections existantes sont affectées et nécessitent une mise à jour.

Si vous ne pouvez apporter aucune modification à vos collections pour le moment, vous pouvez activer l’option legacy.collections qui vous permettra de conserver vos collections dans leur état actuel jusqu’à ce que l’option héritée ne soit plus prise en charge.

En savoir plus sur la mise à jour des collections de contenu.

Mise à jour des collections existantes

Consultez les instructions ci-dessous pour mettre à jour une collection de contenu existante (type: 'content' ou type: 'data') afin d’utiliser l’API de la couche de contenu.

Instructions étape par étape pour mettre à jour une collection

1. Déplacez le fichier de configuration du contenu. Ce fichier ne se trouve plus dans le dossier src/content/. Ce fichier devrait maintenant exister dans src/content.config.ts.

2. Éditez la définition de la collection. Votre collection mise à jour nécessite un chargeur (loader), qui indique à la fois un dossier pour l’emplacement de votre collection (base) et un motif (pattern) définissant les noms de fichiers et les extensions des entrées de la collection à faire correspondre. (Vous devrez peut-être mettre à jour l’exemple ci-dessous en conséquence. Vous pouvez utiliser globster.xyz pour vérifier votre motif global). L’option pour sélectionner un type de collection n’est plus disponible.

   src/content.config.ts

   import { defineCollection, z } from 'astro:content';
   import { glob } from 'astro/loaders';
   
   const blog = defineCollection({
     // Pour les couches de contenu, vous ne définissez plus de `type`.
     type: 'content',
     loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
     schema: z.object({
       title: z.string(),
       description: z.string(),
       pubDate: z.coerce.date(),
       updatedDate: z.coerce.date().optional(),
     }),
   });

3. Changez les références de slug à id. Les collections de couches de contenu n’ont pas de champ slug réservé. À la place, toutes les collections mises à jour auront un id :

   src/pages/[slug].astro

   ---
   export async function getStaticPaths() {
     const posts = await getCollection('blog');
     return posts.map((post) => ({
       params: { slug: post.slug },
       params: { slug: post.id },
       props: post,
     }));
   }
   ---

   Vous pouvez également mettre à jour les noms de fichiers de routage dynamique pour qu’ils correspondent à la valeur du paramètre getStaticPaths() modifié.

4. Basculez vers la nouvelle fonction render(). Les entrées n’ont plus de méthode render(), car elles sont maintenant des objets simples sérialisables. À la place, importez la fonction render() de astro:content.

   src/pages/index.astro

   ---
   import { getEntry, render } from 'astro:content';
   
   const post = await getEntry('blog', params.slug);
   
   const { Content, headings } = await post.render();
   const { Content, headings } = await render(post);
   ---
   <Content />

Changements non rétrocompatibles des anciennes collections content et data.

PR d'implémentation : Mise en œuvre des collections existantes à l'aide de glob (#11976)

Par défaut, les collections qui utilisent l’ancienne propriété type (content ou data) et qui ne définissent pas de chargeur (loader) sont maintenant implémentées sous le capot en utilisant le chargeur intégré glob() de l’API de la couche de contenu, avec une gestion supplémentaire de la rétrocompatibilité.

De plus, une rétrocompatibilité temporaire existe pour conserver le fichier de configuration du contenu dans son emplacement original de src/content/config.ts.

Cette implémentation de la rétrocompatibilité est capable d’émuler la plupart des fonctionnalités des anciennes collections et permettra à de nombreuses anciennes collections de continuer à fonctionner même sans mettre à jour votre code. Cependant, il y a des différences et des limitations qui peuvent entraîner des changements avec rupture de compatibilité dans les collections existantes :

• Dans les versions précédentes d’Astro, les collections étaient générées pour tous les dossiers dans src/content/, même s’ils n’étaient pas définis dans src/content/config.ts. Ce comportement est maintenant déprécié, et les collections doivent toujours être définies dans src/content.config.ts. Pour les collections existantes, il peut s’agir de déclarations vides (par exemple const blog = defineCollection({})) et Astro définira implicitement votre ancienne collection pour vous d’une manière compatible avec le nouveau comportement de chargement.
• Le champ spécial layout n’est pas pris en charge dans les entrées de collection Markdown. Cette propriété n’est destinée qu’aux fichiers de pages autonomes situés dans src/pages/ et n’est pas susceptible de se trouver dans les entrées de votre collection. Cependant, si vous utilisiez cette propriété, vous devez maintenant créer des routes dynamiques qui incluent le style de votre page.
• L’ordre de tri des collections générées n’est pas déterministe et dépend de la plate-forme. Cela signifie que si vous appelez getCollection(), l’ordre dans lequel les entrées sont retournées peut être différent de ce qu’il était auparavant. Si vous avez besoin d’un ordre spécifique, vous devez trier les entrées de la collection vous-même.
• image().refine() n’est pas pris en charge. Si vous avez besoin de valider les propriétés d’une image, vous devrez le faire au moment de l’exécution de votre page ou de votre composant.
• L’argument key de getEntry(collection, key) utilise un type string, plutôt que d’avoir des types pour chaque entrée.
• Auparavant, lors de l’appel de getEntry(collection, key) avec une chaîne statique comme clé, le type renvoyé n’était pas « nullable ». Ce type inclut désormais undefined, vous devez donc vérifier si l’entrée est définie avant d’utiliser le résultat ou vous aurez des erreurs de type.

Activation de l’option legacy.collections.

PR d'implémentation : Mise en œuvre des collections héritées à l'aide de glob (#11976)

Si vous n’êtes pas encore prêt à mettre à jour vos collections existantes, vous pouvez activer l’option legacy.collections et vos collections existantes continueront à fonctionner comme avant.

Dépréciées

Les fonctionnalités dépréciées suivantes ne sont plus prises en charge et ne sont plus documentées. Veuillez mettre à jour votre projet en conséquence.

Certaines fonctionnalités dépréciées peuvent continuer à fonctionner temporairement jusqu’à ce qu’elles soient complètement supprimées. D’autres peuvent n’avoir aucun effet ou générer une erreur vous invitant à mettre à jour votre code.

Déprécié : Astro.glob()

PR d'implémentation : Déprécier glob (#11826)

Dans Astro v4.x, vous pouviez utiliser Astro.glob() dans vos composants .astro pour interroger plusieurs fichiers dans votre projet. Cela avait quelques limitations (où cela pouvait être utilisé, performances, etc.), et l’utilisation des fonctions de requête de l’API des collections de contenu ou de import.meta.glob() propre à Vite fournissait souvent plus de fonctions et de flexibilité.

Astro 5.0 déprécie Astro.glob() en faveur de l’utilisation de getCollection() pour interroger vos collections, et de import.meta.glob() pour interroger d’autres fichiers sources dans votre projet.

Que dois-je faire ?

Remplacez toutes les utilisations de Astro.glob() par import.meta.glob(). Notez que import.meta.glob() ne retourne plus de Promise, vous devrez donc mettre à jour votre code en conséquence. Vous ne devriez pas avoir besoin de mettre à jour vos motifs glob.

src/pages/blog.astro

---
const posts = await Astro.glob('./posts/*.md');
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

{posts.map((post) => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}

Le cas échéant, envisagez d’utiliser les collections de contenu pour organiser votre contenu, qui disposent de leurs propres fonctions d’interrogation, plus récentes et plus performantes.

Vous pouvez également envisager d’utiliser des paquets glob de NPM, tels que fast-glob.

En savoir plus sur l’importation de fichiers avec import.meta.glob.

Déprécié : functionPerRoute (API des adaptateurs)

PR d'implémentation : Supprimer l'option functionPerRoute (#11714)

Dans Astro v4.x, vous pouviez choisir de créer un fichier séparé pour chaque route définie dans le projet, reflétant votre répertoire src/pages/ dans le dossier de compilation. Par défaut, Astro émettait un seul fichier entry.mjs, qui était responsable de l’émission de la page rendue à chaque requête.

Astro v5.0 supprime l’option permettant d’abandonner le comportement par défaut. Ce comportement est maintenant standard et non configurable.

Supprimez la propriété functionPerRoute de votre configuration adapterFeatures. Elle n’est plus disponible.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          adapterFeatures: {
              functionPerRoute: true
          }
        });
      },
    },
  };
}

En savoir plus sur l’API des adaptateurs pour créer des intégrations d’adaptateur.

Déprécié : routes sur le hook astro:build:done(API des intégrations)

PR d'implémentation : feat(next): astro:routes:resolved (#12329)

Dans Astro v4.x, les intégrations accédaient aux routes à partir du hook astro:build:done.

Astro v5.0 déprécie le tableau routes passé à ce hook. À la place, il expose un nouveau hook astro:routes:resolved qui s’exécute avant astro:config:done, et à chaque fois qu’une route change dans le développement. Il possède les mêmes propriétés que la liste routes dépréciée, à l’exception de distURL qui n’est disponible que pendant la compilation.

Que dois-je faire ?

Supprimez toute instance de routes passée à astro:build:done et remplacez-la par le nouveau hook astro:routes:resolved. Accédez à distURL depuis l’objet Map assets nouvellement exposé :

mon-integration.mjs

const integration = () => {
    let routes
    return {
        name: 'mon-integration',
        hooks: {
            'astro:routes:resolved': (params) => {
                routes = params.routes
            },
            'astro:build:done': ({
                routes
                assets
            }) => {
                for (const route of routes) {
                    const distURL = assets.get(route.pattern)
                    if (distURL) {
                        Object.assign(route, { distURL })
                    }
                }
                console.log(routes)
            }
        }
    }
}

En savoir plus sur le hook astro:routes:resolved de l’API des intégrations pour créer des intégrations.

Supprimées

Les fonctionnalités suivantes ont été entièrement supprimées de la base de code et ne peuvent plus être utilisées. Certaines d’entre elles ont pu continuer à fonctionner dans votre projet même après leur dépréciation. D’autres n’ont peut-être eu aucun effet en silence.

Les projets contenant désormais ces fonctionnalités supprimées ne pourront pas être compilés, et il n’y aura plus de documentation vous invitant à supprimer ces fonctionnalités.

Supprimée : L’intégration Lit

PR d'implémentation : Supprimée `@astrojs/lit` (#11680)

Dans Astro v4.x, Lit était une bibliothèque de framework maintenue par l’équipe Core à travers le paquet @astrojs/lit.

Astro v5.0 supprime cette intégration et elle ne recevra plus de mises à jour pour assurer la compatibilité avec les versions 5.x et supérieures.

Que dois-je faire ?

Vous pouvez continuer à utiliser Lit pour les composants client en ajoutant une balise de script côté client. Par exemple :

<script>
  import "../components/MyTabs";
</script>

<my-tabs title="Ce sont mes onglets">...</my-tabs>

Si vous souhaitez maintenir vous-même une intégration Lit, vous pouvez utiliser la dernière version publiée de @astrojs/lit comme point de départ et mettre à jour les paquets appropriés.

En savoir plus sur les intégrations officielles d’Astro.

Supprimé : Mode de rendu hybride (hybrid).

PR d'implémentation : Fusionner output:hybrid et output:static (#11824)

Dans Astro v4.x, Astro fournissait trois modes de sortie de rendu (output) : 'static', 'hybrid', et 'server'.

Astro v5.0 fusionne les modes de rendu output: 'hybrid' et output: 'static' en une seule configuration (maintenant appelée 'static') qui fonctionne de la même manière que l’option hybride précédente.

Il n’est plus nécessaire de spécifier output: 'hybrid' dans votre configuration Astro pour utiliser les pages rendues par le serveur. La nouvelle option output: 'static' a cette capacité incluse.

Astro vous permettra désormais de désactiver automatiquement le pré-rendu dans votre site statique sans qu’aucune modification de votre configuration de sortie ne soit nécessaire. N’importe quelle route de page ou point de terminaison peut inclure export const prerender = false pour être rendu par le serveur à la demande, alors que le reste de votre site est généré statiquement.

Que dois-je faire ?

Si votre projet utilisait le rendu hybride, vous devez maintenant supprimer l’option output: 'hybrid' de votre configuration Astro, car elle n’existe plus. Cependant, aucune autre modification de votre projet n’est nécessaire, et vous ne devriez pas avoir de changements avec rupture de compatibilité. Le comportement précédent 'hybrid' est maintenant le comportement par défaut, sous un nouveau nom 'static'.

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  output: 'hybrid',
});

Si vous utilisiez l’option output: 'static' (par défaut), vous pouvez continuer à l’utiliser comme avant. Par défaut, toutes vos pages continueront à être pré-rendues et vous aurez un site complètement statique. Vous ne devriez pas avoir de changement avec rupture de compatibilité dans votre projet.

Un adaptateur est toujours nécessaire pour déployer un projet Astro avec des pages rendues par le serveur, quel que soit le mode de sortie output utilisé par votre projet. Si vous n’incluez pas d’adaptateur, vous recevrez un avertissement pendant le développement et une erreur au moment de la compilation.

En savoir plus sur le rendu à la demande dans Astro.

Supprimé : prise en charge des valeurs dynamiques pour prerender dans les routes

PR d'implémentation : Fusionner output:hybrid et output:static (#11824)

Dans Astro 4.x, les variables d’environnement pouvaient être utilisées pour définir dynamiquement la valeur des exportations prerender dans les routes, par exemple export const prerender = import.meta.env.SOME_VAR.

Astro v5.0 supprime la prise en charge des valeurs dynamiques dans les exportations prerender. Seules les valeurs statiques true et false sont prises en charge.

Que dois-je faire ?

1. Supprimez toutes les exportations dynamiques prerender dans vos routes :

   src/pages/blog/[slug].astro

   ---
   export const prerender = import.meta.env.SOME_VAR;
   ---

2. Utilisez une intégration Astro dans votre fichier astro.config.mjs pour définir les valeurs prerender qui doivent être dynamiques dans le hook "astro:route:setup" :

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import { loadEnv } from 'vite';
   
   export default defineConfig({
     integrations: [
       {
         name: 'set-prerender',
         hooks: {
           'astro:route:setup': ({ route }) => {
             // Charger les variables d'environnement à partir des fichiers .env (si nécessaire)
             const { PRERENDER } = loadEnv(process.env.NODE_ENV, process.cwd(), '');
             // Rechercher les routes correspondant au nom de fichier attendu.
             if (route.component.endsWith('/blog/[slug].astro')) {
               // Définir la valeur de prerender par route selon vos besoins.
               route.prerender = PRERENDER;
             }
           },
         },
       }
     ],
   });

Supprimé : Service d’images Squoosh

PR d'implémentation : supprimer le service d'image squoosh (#11770)

Dans Astro 4.x, vous pouviez configurer image.service: squooshImageService() pour utiliser Squoosh pour transformer vos images à la place de Sharp. Cependant, la bibliothèque sous-jacente libsquoosh n’est plus maintenue et présente des problèmes de mémoire et de performance.

Astro 5.0 supprime entièrement le service d’optimisation d’images Squoosh.

Que dois-je faire ?

Pour passer au service d’image Sharp intégré, supprimez l’importation de squooshImageService dans votre configuration Astro. Par défaut, vous utiliserez Sharp pour astro:assets.

astro.config.mjs

import { squooshImageService } from "astro/config";
import { defineConfig } from "astro/config";

export default defineConfig({
 image: {
   service: squooshImageService()
 }
});

Si vous utilisez un gestionnaire de paquets strict comme pnpm, vous pouvez avoir besoin d’installer le paquet sharp manuellement pour utiliser le service d’image Sharp, même s’il est intégré à Astro par défaut.

Si votre adaptateur ne prend pas en charge l’optimisation d’image Sharp intégrée à Astro, vous pouvez configurer un service d’image no-op pour vous permettre d’utiliser les composants <Image /> et <Picture />.

Vous pouvez également envisager un service d’images Squoosh maintenu par la communauté si vous ne pouvez pas utiliser le service d’images Sharp.

Pour les adaptateurs

Si votre adaptateur précisait auparavant son statut de compatibilité avec Squoosh, vous devez maintenant supprimer cette information de la configuration de votre adaptateur.

my-adapter.mjs

supportedAstroFeatures: {
  assets: {
    isSquooshCompatible: true
  }
}

En savoir plus sur la configuration de votre service d’images par défaut.

Supprimé : certains types exposés au public

PR d'implémentation : Refactor/types (#11715)

Dans Astro v4.x, @types/astro.ts exposait publiquement tous les types aux utilisateurs, qu’ils soient encore activement utilisés ou seulement destinés à un usage interne.

Astro v5.0 refactorise ce fichier pour supprimer les types obsolètes et internes. Ce remaniement apporte des améliorations à votre éditeur (par exemple, des complétions plus rapides, une utilisation plus faible de la mémoire et des options de complétion plus pertinentes). Cependant, ce remaniement peut provoquer des erreurs dans certains projets qui s’appuient sur des types qui ne sont plus disponibles pour le public.

Que dois-je faire ?

Supprimez tous les types qui provoquent des erreurs dans votre projet car vous n’y avez plus accès. Il s’agit principalement d’API qui ont été précédemment dépréciées et supprimées, mais il peut également s’agir de types qui sont désormais internes.

Voir les types publics exposés à l’utilisation.

Options expérimentales

Les options expérimentales suivantes ont été supprimées dans la version 5.0 d’Astro et peuvent désormais être utilisées :

• env
• serverIslands

De plus, les options expérimentales suivantes ont été supprimées et sont maintenant le comportement par défaut ou recommandé dans Astro v5.0.

• directRenderScript (Voir ci-dessous pour les changements non rétrocompatibles apportés au comportement par défaut de <script>.)
• globalRoutePriority (Voir ci-dessous pour les changements non rétrocompatibles apportés à l’ordre de priorité des routes par défaut.)
• contentLayer (Voir les conseils pour mettre à jour les collections de contenu existantes vers la nouvelle API de couche de contenu préférée).

Les options expérimentales suivantes ont été supprimées et leurs fonctionnalités correspondantes ne font pas partie d’Astro v5.0.

• contentCollectionsCache

Supprimez ces options expérimentales si vous les utilisiez auparavant, et déplacez votre configuration env à la racine de votre configuration Astro :

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    directRenderScript: true,
    globalRoutePriority: true,
    contentLayer: true,
    serverIslands: true,
    contentCollectionsCache: true,
    env: {
      schema: {...}
    }
  },
  env: {
      schema: {...}
  }
})

Ces fonctionnalités sont toutes disponibles par défaut dans Astro v5.0.

Découvrez ces fonctionnalités passionnantes et bien plus encore dans l’article du blog sur la v5.0.

Modifications des paramètres par défaut

Certains comportements par défaut ont été modifiés dans Astro v5.0 et le code de votre projet peut nécessiter une mise à jour pour tenir compte de ces changements.

Dans la plupart des cas, la seule action nécessaire est de revoir le déploiement de votre projet existant et de s’assurer qu’il continue à fonctionner comme vous l’attendez, en apportant des mises à jour à votre code si nécessaire. Dans certains cas, il peut exister un paramètre de configuration vous permettant de continuer à utiliser l’ancien comportement par défaut.

La protection CSRF est désormais définie par défaut

PR d'implémentation : modification de la valeur par défaut de checkOrigin (#11788)

Dans Astro v4.x, la valeur par défaut de security.checkOrigin était false. Auparavant, vous deviez explicitement définir cette valeur à true pour activer la protection contre la falsification des requêtes intersites (CSRF).

Astro v5.0 change la valeur par défaut de cette option en true, et vérifiera automatiquement que l’en-tête « origin » correspond à l’URL envoyée par chaque requête dans les pages rendues à la demande.

Que dois-je faire ?

Si vous aviez précédemment configuré security.checkOrigin: true, vous n’avez plus besoin de cette ligne dans votre configuration Astro. C’est maintenant le comportement par défaut.

Pour désactiver ce comportement, vous devez explicitement configurer security.checkOrigin: false.

astro.config.mjs

export default defineConfig({
  output: "server",
  security: {
    checkOrigin: false
  }
})

En savoir plus sur les options de configuration de la sécurité

Ordre de priorité des routes injectées et des redirections

PR d'implémentation : Suppression de l'ordre de priorité des routes (#11798)

Dans Astro v4.x, experimental.globalRoutePriority était un paramètre optionnel qui assurait que les routes injectées, les routes basées sur des fichiers, et les redirections étaient toutes priorisées en utilisant les règles d’ordre de priorité des routes pour toutes les routes. Cela permettait de mieux contrôler le routage dans votre projet en ne donnant pas automatiquement la priorité à certains types de routes et en normalisant l’ordre de priorité des routes.

Astro v5.0 supprime ce paramètre expérimental et en fait le nouveau comportement par défaut d’Astro : les redirections et les routes injectées sont désormais prioritaires au même titre que les routes du projet basées sur des fichiers.

Notez que c’était déjà le comportement par défaut dans Starlight, et que cela ne devrait pas affecter les projets Starlight mis à jour.

Que dois-je faire ?

Si votre projet inclut des routes injectées ou des redirections, veuillez vérifier que vos routes génèrent les URL des pages comme prévu. Voici un exemple du nouveau comportement attendu.

Dans un projet contenant les routes suivantes:

• Route basée sur les fichiers : /blog/post/[pid]
• Route basée sur les fichiers : /[page]
• Route injectée : /blog/[...slug]
• Redirection : /blog/tags/[tag] -> /[tag]
• Redirection : /posts -> /blog

Les URL suivantes seront générées (au lieu de suivre l’ordre de priorité des routes d’Astro v4.x) :

• /blog/tags/astro est générée par la redirection vers /tags/[tag] (au lieu de la route injectée /blog/[...slug])
• /blog/post/0 est genérée par la route basée sur les fichiers /blog/post/[pid] (au lieu de la route injectée /blog/[...slug])
• /posts est générée par la redirection vers /blog (au lieu de la route basée sur les fichiers /[page])

En cas de collisions de routes, lorsque deux routes de même priorité tentent de générer la même URL, Astro enregistre un avertissement identifiant les routes en conflit.

En savoir plus sur les règles d’ordre de priorité des routes.

Les balises <script> sont rendues directement comme déclarées

PR d'implémentation : Faire de directRenderScript la valeur par défaut (#11791)

Dans Astro v4.x, experimental.directRenderScript était un paramètre optionnel pour restituer directement les <scripts> tels que déclarés dans les fichiers .astro (y compris les fonctionnalités existantes comme TypeScript, l’importation de node_modules, et la déduplication des scripts). Cette stratégie empêchait les scripts d’être exécutés à des endroits où ils n’étaient pas utilisés. De plus, les scripts rendus conditionnellement étaient auparavant implicitement intégrés sur place sans traitement par Astro, comme si une directive is:inline leur était automatiquement ajoutée.

Astro 5.0 supprime cette option expérimentale et en fait le nouveau comportement par défaut d’Astro : les scripts ne sont plus placés dans le <head>, les scripts multiples sur une page ne sont plus regroupés, et une balise <script> peut interférer avec la mise en forme CSS. De plus, les scripts rendus conditionnellement ne sont plus implicitement intégrés sans traitement par Astro.

Que dois-je faire ?

Veuillez vérifier vos balises <script> et vous assurer qu’elles se comportent comme vous le souhaitez.

Si vous aviez auparavant des balises <script> rendues conditionnellement, vous devrez ajouter un attribut is:inline pour conserver le même fonctionnement qu’auparavant.

src/components/MyComponent.astro

---
type Props = {
  afficherAlerte: boolean
}

const { afficherAlerte } = Astro.props;
---
{
  afficherAlerte && <script is:inline>alert("Notification très importante !")</script>
}

En savoir plus sur l’utilisation des balises script dans Astro.

Changements non rétrocompatibles

Les changements suivants sont considérés comme des changements avec rupture de compatibilité dans Astro v5.0. Ces changements peuvent ou non assurer une rétrocompatibilité temporaire. Si vous utilisiez ces fonctionnalités, vous devriez peut-être mettre à jour votre code comme recommandé dans chaque entrée.

Renommé : composant <ViewTransitions />.

PR d'implémentation : Renommer le composant ViewTransitions en ClientRouter (#11980)

Dans Astro 4.x, l’API des transitions de vue d’Astro incluait un composant routeur <ViewTransitions /> pour permettre le routage côté client, les transitions de page, et plus encore.

Astro 5.0 renomme ce composant en <ClientRouter /> pour clarifier le rôle du composant dans l’API. Il est ainsi plus clair que les fonctionnalités du composant de routage <ClientRouter /> d’Astro sont légèrement différentes de celles du routeur MPA natif basé sur CSS.

Aucune fonctionnalité n’a changé. Ce composant a seulement changé de nom.

Que dois-je faire ?

Remplacer toutes les occurrences de l’importation et du composant ViewTransitions par ClientRouter :

src/layouts/MyLayout.astro

import { ViewTransitions } from 'astro:transitions';
import { ClientRouter } from 'astro:transitions';

<html>
  <head>
    ...
   <ViewTransitions />
   <ClientRouter />
  </head>
</html>

Plus d’informations sur les transitions de vue et le routage côté client dans Astro.

Modifié : Configuration de TypeScript

PR d'implémentation : Amélioration de tsconfig (#11859)

Dans Astro v4.x, Astro s’appuyait sur un fichier src/env.d.ts pour l’inférence des types et la définition des modules pour les fonctionnalités qui s’appuyaient sur les types générés.

Astro 5.0 utilise à la place un fichier .astro/types.d.ts pour l’inférence des types, et recommande maintenant de définir include et exclude dans tsconfig.json pour bénéficier des types d’Astro et éviter de vérifier les fichiers compilés.

L’exécution de astro sync ne crée plus, ni ne met à jour, src/env.d.ts car il n’est pas nécessaire pour vérifier les types des projets Astro standards.

Que dois-je faire ?

Pour mettre à jour votre projet avec les paramètres TypeScript recommandés par Astro, ajoutez les propriétés include et exclude suivantes à votre tsconfig.json existant :

tsconfig.json

{
  "extends": "astro/tsconfigs/base",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

Notez que src/env.d.ts n’est nécessaire que si vous avez ajouté des configurations personnalisées, ou si vous n’utilisez pas un fichier tsconfig.json.

En savoir plus sur la configuration de TypeScript dans Astro.

Modifié : Les actions soumises par des formulaires HTML n’utilisent plus les redirections de cookies.

PR d'implémentation : Actions middleware (#12373)

Dans Astro 4.x, les actions appelées à partir d’un formulaire HTML déclenchaient une redirection dont le résultat était transmis à l’aide de cookies. Cela posait des problèmes pour les erreurs de formulaire importantes et les valeurs de retour qui dépassaient la limite de 4 Ko du stockage basé sur les cookies.

Astro 5.0 restitue maintenant le résultat d’une action comme un résultat POST sans aucune redirection. Cela introduira une boîte de dialogue « confirmer le nouvel envoi du formulaire ? » lorsqu’un utilisateur tentera de rafraîchir la page, bien que cela n’impose plus une limite de 4 Ko sur la valeur de retour de l’action.

Que dois-je faire ?

Vous devez mettre à jour le traitement des résultats des actions qui reposent sur des redirections, et éventuellement traiter la boîte de dialogue « confirmer le nouvel envoi du formulaire ? » avec un middleware.

Rediriger vers la route précédente en cas d’erreur

Si l’action de votre formulaire HTML est dirigée vers une route différente (c’est-à-dire action={"/success-page" + actions.name}), Astro ne redirigera plus vers la route précédente en cas d’erreur. Vous pouvez implémenter ce comportement manuellement en utilisant les redirections dans votre composant Astro. Cet exemple redirige plutôt vers une nouvelle route en cas de succès, et gère les erreurs sur la page courante dans le cas contraire :

src/pages/newsletter.astro

---
import { actions } from 'astro:actions';

const result = Astro.getActionResult(actions.newsletter);
if (!result?.error) {
  // Incorporer les données de résultat pertinentes dans l'URL si nécessaire
  // exemple : redirect(`/confirmation?email=${result.data.email}`);
  return redirect('/confirmation');
}
---

<form method="POST" action={'/confirmation' + actions.newsletter}>
  <label>E-mail <input required type="email" name="email" /></label>
  <button>S'inscrire</button>
</form>

(Optionnel) Supprimer la boîte de dialogue de confirmation lors de l’actualisation

Pour résoudre le problème de la boîte de dialogue « confirmer le nouvel envoi du formulaire ? » lors de l’actualisation, ou pour conserver les résultats des actions entre les sessions, vous pouvez désormais personnaliser la gestion des résultats des actions à partir d’un middleware.

Nous recommandons d’utiliser un fournisseur de stockage de session comme décrit dans notre exemple Netlify Blob. Cependant, si vous préférez le comportement de transfert de cookie de la version 4.X et acceptez la limite de taille de 4 Ko, vous pouvez implémenter le modèle comme indiqué dans cet exemple :

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  // Sauter les demandes de pages pré-rendues
  if (context.isPrerendered) return next();

  const { action, setActionResult, serializeActionResult } = getActionContext(context);

  // Si le résultat d'une action a été transmis sous la forme d'un cookie, définir le résultat
  // pour qu'il soit accessible depuis `Astro.getActionResult()`.
  const payload = context.cookies.get('ACTION_PAYLOAD');
  if (payload) {
    const { actionName, actionResult } = payload.json();
    setActionResult(actionName, actionResult);
    context.cookies.delete('ACTION_PAYLOAD');
    return next();
  }

  // Si une action a été appelée à partir d'un formulaire HTML,
  // appeler le gestionnaire d'action et rediriger avec le résultat sous forme de cookie.
  if (action?.calledFrom === 'form') {
    const actionResult = await action.handler();

    context.cookies.set('ACTION_PAYLOAD', {
      actionName: action.name,
      actionResult: serializeActionResult(actionResult),
    });

    if (actionResult.error) {
    // Renvoyer à la page précédente en cas d'erreur
      const referer = context.request.headers.get('Referer');
      if (!referer) {
        throw new Error("Interne : Referer manquant de manière inattendue dans la requête POST de l'action.");
      }
      return context.redirect(referer);
    }
    // Rediriger vers la page de destination en cas de succès
    return context.redirect(context.originPathname);
  }

  return next();
})

Modifié : compiledContent() est maintenant une fonction asynchrone.

PR d'implémentation : Supprimer TLA en rendant compiledContent async (#11782)

Dans Astro 4.x, les attentes de haut niveau étaient incluses dans les modules Markdown. Cela posait des problèmes avec les services d’images personnalisés et les images à l’intérieur de Markdown, provoquant la sortie soudaine de Node sans message d’erreur.

Astro 5.0 fait de la propriété compiledContent() sur l’importation Markdown une fonction asynchrone, nécessitant un await pour résoudre le contenu.

Que dois-je faire ?

Mettez à jour votre code pour utiliser await lors de l’appel à compiledContent().

src/pages/post.astro

---
import * as myPost from "../blog/post.md";

const content = myPost.compiledContent();
const content = await myPost.compiledContent();
---

<Fragment set:html={content} />

En savoir plus sur la fonction compiledContent() pour renvoyer du Markdown compilé.

Modifié : astro:content ne peut plus être utilisé sur le client

PR d'implémentation : Empêcher l'utilisation de `astro:content` dans le client (#11827)

Dans Astro 4.x, il était possible d’accéder au module astro:content sur le client.

Astro 5.0 supprime cet accès, car il n’a jamais été exposé intentionnellement pour un usage client. L’utilisation de astro:content de cette manière avait des limitations et gonflait les paquets clients.

Que dois-je faire ?

Si vous utilisez actuellement astro:content dans le client, passez les données dont vous avez besoin à travers les props à vos composants clients à la place :

src/pages/blog.astro

---
import { getCollection } from 'astro:content';
import ClientComponent from '../components/ClientComponent';

const posts = await getCollection('blog');
const postsData = posts.map(post => post.data);
---

<ClientComponent posts={postsData} />

En savoir plus sur l’API astro:content.

Renommé : Noms des jetons de couleur du thème Shiki css-variables.

PR d'implémentation : Mise à jour vers les nouveaux noms de jetons shiki (#11661)

Dans Astro v4.x, le thème Shiki css-variables utilisait les jetons --astro-code-color-text et --astro-code-color-background pour définir les couleurs d’avant-plan et d’arrière-plan des blocs de code respectivement.

Astro v5.0 les renomme respectivement en --astro-code-foreground et --astro-code-background pour mieux s’aligner sur les valeurs par défaut de Shiki v1.

Que dois-je faire ?

Vous pouvez effectuer une recherche et un remplacement global dans votre projet pour migrer vers les nouveaux noms de jetons.

src/styles/global.css

:root {
  --astro-code-color-text: #000;
  --astro-code-color-background: #fff;
  --astro-code-foreground: #000;
  --astro-code-background: #fff;
}

Plus d’informations sur la coloration syntaxique dans Astro.

Modifié : module d’extension interne rehype Shiki pour la mise en évidence des blocs de code

PR d'implémentation : Refonte de createShikiHighlighter (#11825)

Dans Astro 4.x, le module d’extension rehype pour Shiki interne à Astro mettait en évidence les blocs de code en tant que HTML.

Astro 5.0 met à jour ce module d’extension pour mettre en évidence les blocs de code en tant que HAST (Hypertext Abstract Syntax Tree). Cela permet un traitement Markdown et MDX plus direct et améliore les performances lors de la compilation du projet. Cependant, cela peut causer des problèmes avec les transformateurs Shiki existants.

Que dois-je faire ?

Si vous utilisez des transformateurs Shiki passés à markdown.shikiConfig.transformers, vous devez vous assurer qu’ils n’utilisent pas le hook postprocess. Ce hook ne fonctionne plus sur les blocs de code dans les fichiers .md et .mdx. (Voir la documentation Shiki sur les hooks de transformation pour plus d’informations).

Les blocs de code dans les fichiers .mdoc et le composant intégré <Code /> d’Astro n’utilisent pas le module d’extension rehype pour Shiki interne et ne sont pas affectés.

Plus d’informations sur la coloration syntaxique dans Astro.

Modifié : Comportement automatique charset=utf-8 pour les pages Markdown et MDX

PR d'implémentation : Type de contenu non défini charset=utf-8 pour les pages md/mdx (#12231)

Dans Astro 4.0, les pages Markdown et MDX (situées dans src/pages/) répondaient automatiquement avec charset=utf-8 dans l’en-tête Content-Type, ce qui permettait de rendre les caractères non-ASCII dans vos pages.

Astro 5.0 met à jour ce comportement en ajoutant la balise <meta charset="utf-8"> à la place, et seulement pour les pages qui n’utilisent pas la propriété spéciale layout dans le frontmatter d’Astro. De même pour les pages MDX, Astro n’ajoutera la balise que si le contenu MDX n’importe pas un composant Layout.

Si vos pages Markdown ou MDX utilisent la propriété layout dans le frontmatter, ou si le contenu de la page MDX importe un composant Layout, alors l’encodage HTML sera géré par le composant layout désigné à la place, et la balise <meta charset="utf-8"> ne sera pas ajoutée à votre page par défaut.

Que dois-je faire ?

Si vous avez besoin de charset=utf-8 pour afficher votre page correctement, assurez-vous que vos composants de mise en page contiennent la balise <meta charset="utf-8">. Vous devrez peut-être l’ajouter si vous ne l’avez pas encore fait.

En savoir plus sur les mises en page Markdown.

Modifié : Métadonnées spécifiques à Astro attachées dans les modules d’extension remark et rehype

PR d'implémentation : Nettoyer les métadonnées Astro dans vfile.data (#11861)

Dans Astro 4.x, les métadonnées spécifiques à Astro attachées à vfile.data dans les modules d’extension remark et rehype étaient attachées à différents endroits avec des noms incohérents.

Astro 5 nettoie l’API et les métadonnées sont maintenant renommées comme suit :

• vfile.data.__astroHeadings -> vfile.data.astro.headings
• vfile.data.imagePaths -> vfile.data.astro.imagePaths

Les types de imagePaths ont également été mis à jour de Set<string> à string[]. Les métadonnées vfile.data.astro.frontmatter restent inchangées.

Que dois-je faire ?

Bien que nous ne considérions pas ces API comme publiques, elles sont accessibles aux modules d’extension remark et rehype qui souhaitent réutiliser les métadonnées d’Astro. Si vous utilisez ces API, assurez-vous d’y accéder dans les nouveaux emplacements.

En savoir plus sur l’utilisation des modules d’extension de Markdown dans Astro.

Modifié : configuration du point de terminaison de l’image

PR d'implémentation : Permettre de personnaliser la route du point de terminaison de l'image (#11908)

Dans Astro 4.x, vous pouviez définir un point de terminaison dans votre configuration image à utiliser pour l’optimisation de l’image.

Astro 5.0 vous permet de personnaliser une route et un point d’entrée (entrypoint) de la configuration image.endpoint. Cela peut être utile dans des situations spécifiques où la route par défaut /_image est en conflit avec une route existante ou avec la configuration de votre serveur local.

Que dois-je faire ?

Si vous avez précédemment personnalisé image.endpoint, déplacez ce point de terminaison vers la nouvelle propriété endpoint.entrypoint. En option, vous pouvez personnaliser une route :

astro.config.mjs

import { defineConfig } from "astro/config";

defineConfig({
  image: {
    endpoint: './src/image-endpoint.ts',
    endpoint: {
      route: "/image",
      entrypoint: "./src/image_endpoint.ts"
    }
  },
})

En savoir plus sur la définition d’un point de terminaison à utiliser pour l’optimisation des images.

Modifié : comportement de résolution de build.client et build.server.

PR d'implémentation : Correction du comportement de résolution de build.client et build.server (#11916)

Dans Astro v4.x, les options build.client et build.server étaient documentées pour être résolues relativement à l’option outDir, mais cela ne fonctionnait pas toujours comme prévu.

Astro 5.0 corrige le comportement pour résoudre correctement à partir de l’option outDir. Par exemple, si outDir est défini avec ./dist/nested/, alors par défaut :

• build.client sera résolu en <root>/dist/nested/client/
• build.server sera résolu en <root>/dist/nested/server/

Auparavant, les valeurs étaient incorrectement résolues :

• build.client était résolu en <root>/dist/nested/dist/client/
• build.server était résolu en <root>/dist/nested/dist/server/

Que dois-je faire ?

Si vous utilisiez les anciens chemins de compilation, assurez-vous que le code de votre projet est mis à jour avec les nouveaux chemins de compilation.

En savoir plus sur les options de configuration de compilation (build) dans Astro.

Modifié : Les dépendances JS dans le fichier de configuration ne sont plus traitées par Vite.

PR d'implémentation : Définir external: true lors du chargement de la configuration astro (#11819)

Dans Astro 4.x, les dépendances JS liées localement (par exemple npm link, dans un monorepo, etc) pouvaient utiliser les fonctionnalités de Vite comme import.meta.glob lorsqu’elles étaient importées par le fichier de configuration Astro.

Astro 5 met à jour le flux de chargement de la configuration Astro pour ignorer le traitement des dépendances JS liées localement avec Vite. Les dépendances exportant des fichiers TypeScript bruts ne sont pas affectées. Au lieu de cela, ces dépendances JS seront normalement importées par l’environnement d’exécution Node.js de la même manière que les autres dépendances de node_modules.

Ce changement a été fait parce que le comportement précédent a provoqué une confusion parmi les auteurs d’intégration qui ont testé un paquet qui fonctionnait localement, mais pas lorsqu’il était publié. Cela a également limité l’utilisation des dépendances CJS uniquement parce que Vite exigeait que le code soit ESM. Bien que ce changement n’affecte que les dépendances JS, il est également recommandé pour les paquets d’exporter du JavaScript au lieu du TypeScript brut lorsque c’est possible afin d’éviter une utilisation accidentelle spécifique à Vite car c’est un détail d’implémentation du flux de chargement de la configuration d’Astro.

Que dois-je faire ?

Assurez-vous que vos dépendances JS liées localement sont compilées avant d’exécuter votre projet Astro. Ensuite, le chargement de la configuration devrait fonctionner comme avant.

En savoir plus sur les paramètres de configuration de Vite dans Astro.

Modifié : les URL renvoyées par paginate()

PR d'implémentation : Ajouter la base à paginer (#11253)

Dans Astro v4.x, l’URL retournée par paginate() (par exemple page.url.next, page.url.first, etc.) n’incluait pas la valeur définie pour base dans votre configuration Astro. Vous deviez manuellement ajouter la valeur configurée pour base au chemin de l’URL.

Astro 5.0 inclut automatiquement la valeur base dans page.url.

Que dois-je faire ?

Si vous utilisez la fonction paginate() pour ces URLs, supprimez toute valeur base existante car elle est maintenant ajoutée pour vous :

---
export async function getStaticPaths({ paginate }) {
  const astronautPages = [{
    astronaut: 'Neil Armstrong',
  }, {
    astronaut: 'Buzz Aldrin',
  }, {
    astronaut: 'Sally Ride',
  }, {
    astronaut: 'John Glenn',
  }];
  return paginate(astronautPages, { pageSize: 1 });
}
const { page } = Astro.props;
// `base: /'docs'` configuré dans `astro.config.mjs`
const prev = "/docs" + page.url.prev;
const prev = page.url.prev;
---
<a id="prev" href={prev}>Précédent</a>

En savoir plus sur la pagination dans Astro.

Modifié : valeurs d’attribut HTML non booléennes

PR d'implémentation : Correction du rendu des attributs pour les valeurs booléennes (prise 2) (#11660)

Dans Astro v4.x, les attributs HTML non booléens pouvaient ne pas inclure leurs valeurs lorsqu’ils étaient rendus en HTML.

Astro v5.0 rend les valeurs explicites comme ="true" ou ="false", ce qui correspond à la gestion correcte des attributs dans les navigateurs.

Dans les exemples .astro suivants, seul allowfullscreen est un attribut booléen :

src/pages/index.astro

<!-- `allowfullscreen` est un attribut booléen -->
<p allowfullscreen={true}></p>
<p allowfullscreen={false}></p>
<!-- `inherit` n'est **pas** un attribut booléen -->
<p inherit={true}></p>
<p inherit={false}></p>
<!-- `data-*` ne sont pas des attributs booléens -->
<p data-light={true}></p>
<p data-light={false}></p>

Astro v5.0 préserve désormais l’attribut data complet avec sa valeur lors du rendu HTML des attributs non booléens :

<p allowfullscreen></p>
<p></p>

<p inherit="true"></p>
<p inherit></p>
<p inherit="false"></p>

<p data-light></p>
<p data-light="true"></p>
<p></p>
<p data-light="false"></p>

Que dois-je faire ?

Si vous utilisez des valeurs d’attributs, par exemple pour localiser des éléments ou pour effectuer un rendu conditionnel, mettez à jour votre code pour qu’il corresponde aux nouvelles valeurs d’attributs non booléennes :

el.getAttribute('inherit') === ''
el.getAttribute('inherit') === 'false'

el.hasAttribute('data-light')
el.dataset.light === 'true'

Plus d’informations sur l’utilisation des attributs HTML dans Astro.

Modifié : ajout de valeurs à context.locals

PR d'implémentation : TODOs (#11987)

Dans Astro 4.x, il était possible de remplacer complètement l’objet locals dans le middleware, les points de terminaison d’API et les pages lors de l’ajout de nouvelles valeurs.

Astro 5.0 vous demande d’ajouter des valeurs à l’objet locals existant sans le supprimer. Il n’est plus possible d’écraser complètement les valeurs locales dans les middleware, les points de terminaison d’API et les pages.

Que dois-je faire ?

Alors qu’auparavant vous écrasiez l’objet, vous devez maintenant lui attribuer des valeurs :

src/middleware.js

ctx.locals = {
Object.assign(ctx.locals, {
  one: 1,
  two: 2
}
})

En savoir plus sur l’enregistrement de données dans context.locals.

Modifié : params n’est plus décodé

PR d'implémentation : décoder le nom du chemin au début, ne pas décoder les paramètres (#12079)

Dans Astro v4.x, les params passés à getStaticPath() étaient automatiquement décodés en utilisant decodeURIComponent.

Astro v5.0 ne décode plus la valeur des params passés à getStaticPaths. Vous devez les décoder manuellement vous-même si nécessaire.

Que dois-je faire ?

Si vous utilisiez auparavant le décodage automatique, utilisez decodeURI lorsque vous passez params.

src/pages/[id].astro

---
export function getStaticPaths() {
  return [
    { params: { id: "%5Bpage%5D" } },
    { params: { id: decodeURI("%5Bpage%5D") } },
  ]
}

const { id } = Astro.params;
---

Notez que l’utilisation de decodeURIComponent est déconseillée pour getStaticPaths car elle décode plus de caractères qu’elle ne devrait, par exemple /, ?, # et d’autres encore.

En savoir plus sur la création de routes dynamiques avec params.

Modifié : Type RouteData remplacé par IntegrationsRouteData (API des intégrations)

PR d'implémentation : envoyer `IntegrationRouteData` aux intégrations (#11864)

Dans Astro v4.x, le type entryPoints dans les hooks astro:build:ssr et astro:build:done était RouteData.

Dans Astro v5.0, le type entryPoints est maintenant IntegrationRouteData, qui contient un sous-ensemble du type RouteData. Les champs isIndex et fallbackRoutes ont été supprimés.

Que dois-je faire ?

Mettez à jour votre adaptateur pour changer le type de entryPoints de RouteData à IntegrationRouteData.

import type {RouteData} from 'astro';
import type {IntegrationRouteData} from "astro"

function useRoute(route: RouteData) {
function useRoute(route: IntegrationRouteData) {
}

Voir la référence de l’API pour IntegrationRouteData.

Modifié : distURL est maintenant un tableau (API des intégrations)

PR d'implémentation : envoyer `IntegrationRouteData` aux intégrations (#11864)

Dans Astro v4.x, RouteData.distURL était undefined ou une URL.

Astro v5.0 met à jour le format de IntegrationRouteData.distURL pour qu’elle soit undefined ou un tableau d’URL. Ceci corrige une erreur précédente car une route peut générer plusieurs fichiers sur le disque, en particulier lors de l’utilisation de routes dynamiques telles que [slug] ou [...slug].

Que dois-je faire ?

Mettez à jour votre code pour traiter IntegrationRouteData.distURL comme un tableau.

if (route.distURL) {
  if (route.distURL.endsWith('index.html')) {
    // faire quelque chose
  }
  for (const url of route.distURL) {
    if (url.endsWith('index.html')) {
      // faire quelque chose
    }
  }
}

Voir la référence de l’API pour IntegrationRouteData.

Modifié : Arguments passés à app.render() (API des adaptateurs)

PR d'implémentation : TODOs (#11987)

Dans Astro 4.x, la méthode app.render() de l’API des adaptateurs pouvait recevoir trois arguments : une requête (request) obligatoire, un objet d’options ou un objet routeData, et locals.

Astro 5.0 combine ces deux derniers arguments en un seul argument d’options nommé renderOptions.

Que dois-je faire ?

Transmettez un objet comme second argument à app.render(), qui peut inclure routeData et locals comme propriétés.

const response = await app.render(request, routeData, locals);
const response = await app.render(request, {routeData, locals});

Consultez la référence de l’API des adaptateurs pour renderOptions.

Modifié : Propriétés de supportedAstroFeatures (API des adaptateurs)

PR d'implémentation : retravailler supportedAstroFeatures (#11806)

Dans Astro 4.x, supportedAstroFeatures, qui permet aux auteurs d’adaptateurs de spécifier les fonctionnalités prises en charge par leur intégration, incluait une propriété assets pour spécifier quels services d’images Astro étaient pris en charge.

Astro 5.0 remplace cette propriété par une propriété dédiée sharpImageService, utilisée pour déterminer si l’adaptateur est compatible avec le service d’image sharp intégré.

La version 5.0 ajoute également une nouvelle valeur limited pour les différentes propriétés de supportedAstroFeatures pour les adaptateurs, qui indique que l’adaptateur est compatible avec la fonctionnalité, mais avec certaines limitations. Ceci est utile pour les adaptateurs qui prennent en charge une fonctionnalité, mais pas dans tous les cas ou avec toutes les options

De plus, la valeur des différentes propriétés de supportedAstroFeatures pour les adaptateurs peut maintenant être des objets, avec les propriétés support et message. Le contenu de la propriété message affichera un message utile dans la CLI d’Astro lorsque l’adaptateur n’est pas compatible avec une fonctionnalité. Ceci est particulièrement utile avec la nouvelle valeur limited, pour expliquer à l’utilisateur pourquoi la prise en charge est limitée.

Que dois-je faire ?

Si vous utilisiez la propriété assets, supprimez-la car elle n’est plus disponible. Pour spécifier que votre adaptateur est compatible avec le service embarqué d’images sharp, remplacez cette propriété par sharpImageService.

Vous pouvez également mettre à jour vos fonctionnalités prises en charge avec la nouvelle option limited et inclure un message à propos de la prise en charge de votre adaptateur.

my-adapter.mjs

supportedAstroFeatures: {
  assets: {
    supportKind: "stable",
    isSharpCompatible: true,
    isSquooshCompatible: true,
  },
  sharpImageService: {
    support: "limited",
    message: "Cet adaptateur prend en charge le service intégré d'image sharp, mais avec certaines limitations."
  }
}

En savoir plus sur la spécification des fonctionnalités Astro prises en charge dans un adaptateur.

Supprimé : Format de définition déprécié pour les applications de la barre d’outils de développement (API de la barre d’outils de développement)

PR d'implémentation : Supprimer le format déprécié de l'application de la barre d'outils de développement (#11987)

Dans Astro 4.x, lors de la compilation d’une application de barre d’outils de développement, il était encore possible d’utiliser la signature addevToolbarApp(string); précédemment dépréciée. Les propriétés id, title, et icon pour définir l’application étaient alors disponibles à travers l’exportation par défaut du point d’entrée (entrypoint) de l’application.

Astro 5.0 supprime complètement cette option en faveur du format de l’objet actuel lors de la définition d’une application de barre d’outils de développement dans une intégration qui est plus intuitive et qui permet à Astro de fournir de meilleures erreurs lorsque les applications de barre d’outils ne parviennent pas à se charger correctement.

Que dois-je faire ?

Si vous utilisiez le format déprécié, mettez à jour votre application de barre d’outils de développement pour utiliser le nouveau format :

mon-integration.mjs

// Ancien format
addDevToolbarApp("./mon-app-barre-outils-dev.mjs");

// Nouveau format
addDevToolbarApp({
  id: "mon-app",
  name: "Mon Application",
  icon: "<svg>...</svg>",
  entrypoint: "./mon-app-barre-outils-dev.mjs",
});

mon-app-barre-outils-dev.mjs

export default {
  id: 'mon-app-barre-outils-dev',
  title: "Mon application pour la barre d'outils de développement",
  icon: '🚀',
  init() {
    // ...
  }
}

En savoir plus sur le développement d’une application de barre d’outils de développement pour Astro en utilisant l’API de la barre d’outils de développement.

Supprimé : configuration de Typescript pendant create-astro

PR d'implémentation : Mise à jour de create-astro (#12083)

Dans Astro v4.x, il était possible de choisir entre les trois paramètres TypeScript d’Astro lors de la création d’un nouveau projet en utilisant create astro, soit en répondant à une question, soit en passant une option --typescript associée au paramètre TypeScript désiré.

Astro 5.0 met à jour la commande CLI create astro pour supprimer la question TypeScript et son option --typescript associée. Le préréglage « strict » est maintenant la valeur par défaut pour tous les nouveaux projets créés avec la ligne de commande et il n’est plus possible de le personnaliser à ce moment-là. Cependant, le modèle TypeScript peut toujours être modifié manuellement dans tsconfig.json.

Que dois-je faire ?

Si vous utilisiez l’option --typescript avec create-astro, supprimez-la de votre commande.

npm

npm create astro@latest -- --template <example-name> --typescript strict
npm create astro@latest -- --template <example-name>

pnpm

pnpm create astro@latest --template <example-name> --typescript strict
pnpm create astro@latest --template <example-name>

Yarn

yarn create astro --template <example-name> --typescript strict
yarn create astro --template <example-name>

Consultez l’ensemble des options disponibles pour la commande create astro

Ressources communautaires

Vous connaissez une bonne ressource pour Astro v5.0 ? Modifier cette page et ajouter un lien ci-dessous !

Problèmes connus

Veuillez consulter les tickets sur le Github d’Astro pour tout problème signalé, ou pour signaler un problème vous-même.