import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro' import Since from '/components/Since.astro';

Cet adaptateur permet à Astro de déployer vos routes et fonctionnalités rendues à la demande sur Netlify, y compris les îlots de serveurs, les actions et les sessions.

Si vous utilisez Astro comme générateur de site statique, vous n'avez besoin de cet adaptateur que si vous utilisez des services Netlify supplémentaires qui nécessitent un serveur (p. ex. CDN d'images de Netlify). Sinon, vous n’avez pas besoin d’un adaptateur pour déployer votre site statique.

Apprenez à déployer votre site Astro dans notre guide de déploiement Netlify.

Pourquoi Astro Netlify

Netlify est une plateforme de déploiement qui vous permet d'héberger votre site en vous connectant directement à votre dépôt GitHub. Cet adaptateur améliore le processus de compilation d'Astro pour préparer votre projet à être déployé via Netlify.

Installation

Astro inclut une commande astro add pour automatiser l'installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.

Ajoutez l'adaptateur Netlify pour activer le rendu à la demande dans votre projet Astro avec la commande astro add. Cela installera @astrojs/netlify et apportera les changements appropriés à votre fichier astro.config.mjs en une seule étape.

Désormais, vous pouvez activer le rendu à la demande par page ou définir la configuration de sortie de votre compilation sur output: 'server' pour restituer toutes vos pages par défaut sur le serveur.

Installation manuelle

Tout d'abord, installez l'adaptateur Netlify dans les dépendances de votre projet en utilisant votre gestionnaire de paquets préféré :

Ensuite, ajoutez l'adaptateur à votre fichier astro.config.* :

 import { defineConfig } from 'astro/config'; import netlify from '@astrojs/netlify'; export default defineConfig({    // ...    adapter: netlify(), });

Utilisation

Lisez le guide de déploiement complet ici.

Suivez les instructions pour compiler votre site localement. Après la compilation, vous aurez un dossier .netlify/ contenant à la fois les fonctions de Netlify dans le dossier .netlify/functions-internal/ et les fonctions Edge de Netlify dans le dossier .netlify/edge-functions/.

Pour déployer votre site, installez la CLI de Netlify et exécutez :

netlify deploy

L'article de blog de Netlify sur Astro et la documentation de Netlify fournissent plus d'informations sur la manière d'utiliser cette intégration pour déployer vers Netlify.

Exécution du middleware Astro sur les fonctions Edge de Netlify

Tout middleware Astro est appliqué aux pages pré-rendues au moment de la compilation, et aux pages pré-rendues au moment de l'exécution.

Pour implémenter des redirections, des contrôles d'accès ou des en-têtes de réponse personnalisés pour les pages pré-rendues, exécutez votre middleware sur les fonctions Edge de Netlify en activant l'option edgeMiddleware :

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  // ...  adapter: netlify({    edgeMiddleware: true,  }),});

Lorsque edgeMiddleware est activé, une fonction edge exécutera votre code middleware pour toutes les requêtes, y compris les ressources statiques, les pages pré-rendues et les pages rendues à la demande.

Pour les pages rendues à la demande, l'objet context.locals est sérialisé en utilisant du JSON et envoyé dans un en-tête pour la fonction serverless, qui effectue le rendu. Comme mesure de sécurité, la fonction serverless refusera de servir les requêtes avec une réponse 403 Forbidden à moins qu'elles ne proviennent de la fonction edge générée.

Accès au contexte Edge depuis votre site

Les fonctions Edge de Netlify fournissent un objet de contexte qui comprend des métadonnées sur la demande, telles que l'IP de l'utilisateur, les données de géolocalisation et les cookies.

Cet objet est accessible via l'objet Astro.locals.netlify.context :

---const {  geo: { city },} = Astro.locals.netlify.context;---<h1>Bonjour, aimable visiteur de {city} !</h1>

Si vous utilisez TypeScript, vous pouvez obtenir des typages corrects en mettant à jour src/env.d.ts pour utiliser NetlifyLocals :

type NetlifyLocals = import('@astrojs/netlify').NetlifyLocalsdeclare namespace App {  interface Locals extends NetlifyLocals {    // ...  }}

Ceci n'est pas disponible sur les pages pré-rendues.

Prise en charge du CDN Image de Netlify

Cet adaptateur utilise par défaut le CDN Image de Netlify pour transformer les images à la volée sans impacter sur les temps de compilation. Il est implémenté en utilisant un service d'images d'Astro sous le capot.

Pour ne pas utiliser l'optimisation d'image à distance du CDN de Netlify, utilisez l'option imageCDN :

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  // ...  adapter: netlify({    imageCDN: false,  }),});

Si vous utilisez des images hébergées sur un autre domaine, vous devez autoriser les chaînes de domaines ou d'URL en utilisant les options de configuration image.domains ou image.remotePatterns :

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({    // ...    adapter: netlify(),    image: {      domains: ['exemple.com'],    },});

Pour plus d'informations, voir le guide d'autorisation des images distantes. Cela n'est pas nécessaire pour les images hébergées sur le même domaine que votre site.

Sites statiques avec l'adaptateur Netlify

Pour les sites statiques (output: 'static') hébergés sur Netlify, vous n'avez généralement pas besoin d'adaptateur. Cependant, certaines fonctionnalités de déploiement ne sont disponibles qu'à travers un adaptateur.

Les sites statiques devront installer cet adaptateur pour utiliser et configurer le service d'image de Netlify.

Si vous utilisez la configuration redirects dans votre configuration Astro, l'adaptateur Netlify peut être utilisé pour traduire cette configuration au format _redirects approprié.

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  // ...  adapter: netlify(),  redirects: {    '/blog/ancien-article': '/blog/nouvel-article',  },});

Une fois que vous avez exécuté astro build, il y aura un fichier dist/_redirects. Netlify l'utilisera pour router correctement les pages en production.

:::note Vous pouvez toujours inclure un fichier public/_redirects pour les redirections manuelles. Toutes les redirections que vous spécifiez dans la configuration des redirections sont ajoutées à la fin de la vôtre. :::

Sessions

L'API Sessions d'Astro vous permet de stocker facilement les données utilisateur entre chaque requête. Ceci peut être utilisé pour des éléments tels que les données et préférences utilisateur, les paniers d'achat et les identifiants d'authentification. Contrairement au stockage des cookies, la taille des données est illimitée et elles peuvent être restaurées sur différents appareils.

Astro configure automatiquement Netlify Blobs pour le stockage de session lors de l'utilisation de l'adaptateur Netlify. Si vous préférez utiliser un autre pilote de stockage de session, vous pouvez le spécifier dans votre configuration Astro. Consultez la référence de configuration session pour plus de détails.

Mise en cache des pages

Les pages rendues à la demande sans contenu dynamique peuvent être mises en cache pour améliorer les performances et réduire l'utilisation des ressources. L'activation de l'option cacheOnDemandPages dans l'adaptateur mettra en cache toutes les pages rendues par le serveur pour une durée maximale d'un an :

export default defineConfig({  // ...  adapter: netlify({    cacheOnDemandPages: true,  }),});

Cela peut être modifié page par page en ajoutant des en-têtes de mise en cache à votre réponse :

---import Layout from '../components/Layout.astro';Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');---<Layout title="Astro on Netlify">  {new Date()}</Layout>

Grâce au contrôle précis du cache, Netlify prend en charge les en-têtes de cache standard comme CDN-Cache-Control ou Vary. Reportez-vous à la documentation pour en savoir plus sur la mise en place, par exemple, de la mise en cache TTL (time to live) ou SWR (stale while revalidate) : https://docs.netlify.com/platform/caching

Inclure ou exclure des fichiers des fonctions Netlify

Lors du déploiement d'un site Astro avec rendu à la demande sur Netlify, les fonctions générées tracent et incluent automatiquement les dépendances du serveur. Cependant, vous devrez peut-être personnaliser les fichiers inclus dans vos fonctions Netlify.

includeFiles

La propriété includeFiles vous permet de spécifier explicitement des fichiers supplémentaires qui doivent être regroupés avec votre fonction. Ceci est utile pour les fichiers qui ne sont pas automatiquement détectés comme dépendances, tels que :

• les fichiers de données chargés à l'aide des opérations fs
• les fichiers de configuration
• les fichiers de modèles

Fournissez un tableau de fichiers supplémentaires à inclure avec les chemins de fichiers relatifs à la racine (root) de votre projet. Les chemins absolus peuvent ne pas fonctionner comme prévu.

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  // ...  adapter: netlify({    includeFiles: ['./mes-donnees.json'], // chemin relatif à `root`  }),});

excludeFiles

Vous pouvez utiliser la propriété excludeFiles pour empêcher le regroupement de fichiers spécifiques qui seraient autrement inclus. Cela est utile pour :

• Réduire la taille du regroupement
• Exclure des binaires volumineux
• Empêcher le déploiement de fichiers indésirables

Fournissez un tableau de fichiers spécifiques à exclure avec des chemins de fichiers relatifs à la racine (root) de votre projet. Les chemins absolus peuvent ne pas fonctionner comme prévu.

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  // ...  adapter: netlify({    excludeFiles: ['./src/un_gros_fichier.jpg'], // chemin relatif à `root`  }),});

Utilisation des motifs glob

includeFiles et excludeFiles prennent en charge les motifs glob pour faire correspondre plusieurs fichiers :

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  adapter: netlify({    includeFiles: [      './data/**/*.json'    ],    excludeFiles: [      './node_modules/package/**/*',      './src/**/*.test.js'    ]  }),});

Fonctionnalités de développement local

Lors de l'exécution de astro dev, l'adaptateur active plusieurs fonctionnalités de la plateforme Netlify pour garantir que l'environnement correspond le plus possible à la production. Celles-ci comprennent :

• Un serveur local pour le CDN Image de Netlify. Il est utilisé par défaut pour les images.
• Un serveur local pour Netlify Blobs. Il est utilisé par défaut pour les sessions.
• Les redirections, réécritures et en-têtes définis dans votre configuration Netlify
• Un accès au contexte Netlify Edge dans les pages à la demande
• Les variables d'environnement de votre site Netlify

Celles-ci fonctionnent mieux lorsque votre site local est lié à un site Netlify à l'aide de netlify link.

Vous pouvez activer ou désactiver certaines de ces fonctionnalités à l'aide de l'option devFeatures dans la configuration de votre adaptateur. Par défaut, toutes les fonctionnalités sont activées, à l'exception des variables d'environnement.

devFeatures

L'option devFeatures peut être soit un booléen pour activer ou désactiver toutes les fonctionnalités, soit un objet pour activer des fonctionnalités spécifiques.

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  // ...  adapter: netlify({    devFeatures: {      // Active la prise en charge du CDN Image de Netlify dans dev. La valeur par défaut est true.      images: false,       // Injecte les variables d'environnement Netlify dans dev. La valeur par défaut est false.      environmentVariables: true,     },  }),});

devFeatures.images

Active la prise en charge locale du CDN Image de Netlify en cours de développement.

Cela utilise une version locale du CDN Image de Netlify, plutôt que le service d'images d'Astro par défaut.

devFeatures.environmentVariables

Injecte les variables d'environnement de votre site Netlify dans l'environnement de développement.

Cela vous permet d'utiliser les mêmes valeurs en développement qu'en production. Consultez la documentation de Netlify sur les variables d'environnement pour plus d'informations, notamment sur la manière d'utiliser différentes variables pour différents environnements.

Fonctionnalités expérimentales

Les fonctionnalités suivantes sont également disponibles, mais peuvent être sujettes à des modifications non rétrocompatibles lors de futures mises à jour. Veuillez suivre attentivement le journal des modifications de @astrojs/netlify pour être informés des mises à jour si vous utilisez ces fonctionnalités dans votre projet.

experimentalStaticHeaders

Active la définition d'en-têtes personnalisés pour les pages pré-rendues dans la configuration de Netlify.

Si cette option est activée, l'adaptateur enregistrera les en-têtes statiques dans le fichier de configuration de l'API Framework lorsqu'ils sont fournis par les fonctionnalités d'Astro, telles que la politique de sécurité du contenu.

Par exemple, lorsque la politique de sécurité du contenu expérimentale est activée, experimentalStaticHeaders peut être utilisée pour ajouter les en-têtes CSP (headers) à votre configuration Netlify, au lieu de créer un élément <meta> :

import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';export default defineConfig({  experimental: {    csp: true  },  adapter: netlify({    experimentalStaticHeaders: true   })});

Exemples

• Le modèle de démarrage Astro avec Netlify Edge fournit un exemple et un guide dans le fichier README.

• Parcourir les projets Astro Netlify sur GitHub pour plus d'exemples !