@astrojs/ vercel

Cet adaptateur permet à Astro de déployer votre site rendu hybrid ou server sur Vercel.

Si vous utilisez Astro comme constructeur de site statique, vous n’avez besoin de cet adaptateur que si vous utilisez des services Vercel supplémentaires (par exemple Vercel Web Analytics, Vercel Image Optimization). Sinon, vous n’avez pas besoin d’adaptateur pour déployer votre site statique.

Apprenez à déployer votre site Astro dans notre Guide de déploiement Vercel.

Pourquoi Astro Vercel ?

Vercel 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 construction d’Astro pour préparer votre projet à être déployé via Vercel.

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 Vercel pour activer SSR dans votre projet Astro avec la commande astro add suivante. Cela installera @astrojs/vercel et apportera les changements appropriés à votre fichier astro.config.mjs en une seule étape.

npx astro add vercel

pnpm astro add vercel

yarn astro add vercel

Installation manuelle

Tout d’abord, ajoutez l’adaptateur @astrojs/vercel aux dépendances de votre projet en utilisant votre gestionnaire de paquets préféré :

npm install @astrojs/vercel

pnpm add @astrojs/vercel

yarn add @astrojs/vercel

Ensuite, ajoutez l’adaptateur et votre mode de rendu à la demande à votre fichier astro.config.* :

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel(),
});

Choix d’une méthode de déploiement

Vous pouvez vous déployer vers différentes cibles :

serverless : SSR à l’intérieur d’une fonction Node.js.
static : génère un site web statique en suivant les formats de sortie de Vercel, les redirections, etc.

Vous pouvez changer la cible en changeant l’importation :

import vercel from '@astrojs/vercel/serverless';
import vercel from '@astrojs/vercel/static';

Utilisation

En savoir plus sur le déploiement de votre projet sur Vercel

Vous pouvez déployer par CLI (vercel deploy) ou en connectant votre nouveau repo dans le Vercel Dashboard. Vous pouvez également créer une version de production localement :

astro build
vercel deploy --prebuilt

Configuration

Pour configurer cet adaptateur, passez un objet à l’appel de la fonction vercel() dans astro.config.mjs :

`webAnalytics`

Type: VercelWebAnalyticsConfig
Disponible pour: Serverless, Static

Ajouté à la version : @astrojs/vercel@3.8.0

Vous pouvez activer Vercel Web Analytics en définissant webAnalytics : { enabled : true }. Cela injectera les scripts de suivi de Vercel dans toutes vos pages.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  }),
});

`imagesConfig`

Type : VercelImageConfig
Disponible pour : Serverless, Static

Ajouté à la version : @astrojs/vercel@3.3.0

Options de configuration pour Image Optimization API de Vercel. Voir la documentation sur la configuration des images de Vercel pour une liste complète des paramètres pris en charge.

Les propriétés domains et remotePatterns seront automatiquement remplies en utilisant les paramètres image correspondants d’Astro.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imagesConfig: {
      sizes: [320, 640, 1280],
    },
  }),
});

`imageService`

Type : boolean
Disponible pour : Serverless, Static

Ajouté à la version : @astrojs/vercel@3.3.0

Lorsque cette option est activée, un Service d’images alimenté par l’API Vercel Image Optimization sera automatiquement configuré et utilisé en production. En développement, le service d’image spécifié par devImageService sera utilisé à la place.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imageService: true,
  }),
});

---
import { Image } from 'astro:assets';
import astroLogo from '../assets/logo.png';
---

<!-- This component -->
<Image src={astroLogo} alt="Mon super logo !" />

<!-- deviendra le HTML suivant -->
<img
  src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
  alt="Mon super logo !"
  loading="lazy"
  decoding="async"
  width="..."
  height="..."
/>

`devImageService`

Type : 'sharp' | 'squoosh' | string
Disponible pour : Serverless, Static

Ajouté à la version : @astrojs/vercel@3.8.0

Défaut : sharp

Permet de configurer le service d’images à utiliser pour le développement lorsque imageService est activé. Cela peut être utile si vous ne pouvez pas installer les dépendances de Sharp sur votre machine de développement, mais que l’utilisation d’un autre service d’image comme Squoosh vous permet de prévisualiser les images dans votre environnement de développement. La construction n’est pas affectée et utilisera toujours l’optimisation d’image de Vercel.

Il peut également être défini à une valeur arbitraire afin d’utiliser un service d’images personnalisé au lieu des services intégrés d’Astro.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    imageService: true,
    devImageService: 'squoosh',
  }),
});

`isr`

Type : boolean | VercelISRConfig
Disponible pour : Serverless

Ajouté à la version : @astrojs/vercel@7.2.0

Défaut : false

Permet à votre projet d’être déployé en tant que fonction ISR (Incremental Static Regeneration), qui met en cache vos pages rendues à la demande de la même manière que les pages pré-rendues après la première demande.

Pour activer cette fonctionnalité, mettez isr à true dans la configuration de votre adaptateur Astro dans astro.config.mjs :

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    isr: true,
  }),
});

Notez que les demandes de fonctions de l’ISR ne comprennent pas de paramètres de recherche, comme requests en mode statique.

Invalidation du cache de l’ISR

Par défaut, une fonction ISR est mise en cache pour la durée de votre déploiement. Vous pouvez contrôler davantage la mise en cache en définissant un délai d’expiration ou en excluant complètement certains itinéraires de la mise en cache.

Invalidation basée sur le temps

Vous pouvez modifier la durée de mise en cache des routes en configurant une valeur expiration en secondes :

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    isr: {
      // met en cache toutes les pages à la première demande et les sauvegarde pendant 1 jour
      expiration: 60 * 60 * 24,
    },
  }),
});

Exclusion des chemins d’accès de la mise en cache

Pour mettre en œuvre le Mode brouillon ou la Régénération statique incrémentale (RSI) à la demande de Vercel, vous pouvez créer un jeton de contournement et le fournir à la configuration isr avec toutes les routes à exclure de la mise en cache :

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
    output: "server",
    adapter: vercel({
        isr: {
            // Une chaîne aléatoire secrète que vous créez.
            bypassToken: "005556d774a8",
            // Des chemins qui seront toujours fraîchement servis.
            exclude: [ "/api/invalidate", "/posts/[...slug]" ]
        }
    })
})

`includeFiles`

Type : string[]
Disponible pour : Serverless

Utilisez cette propriété pour forcer l’intégration de fichiers dans votre fonction. C’est utile lorsque vous remarquez qu’il manque des fichiers.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    includeFiles: ['./my-data.json'],
  }),
});

`excludeFiles`

Type : string[]
Disponible pour : Serverless

Utilisez cette propriété pour exclure du processus de regroupement des fichiers qui seraient autrement inclus.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    excludeFiles: ['./src/some_big_file.jpg'],
  }),
});

`maxDuration`

Type : number
Disponible pour : Serverless

Utilisez cette propriété pour étendre ou limiter la durée maximale (en secondes) que les fonctions Serverless peuvent exécuter avant de s’arrêter. Voir la documentation Vercel pour la limite par défaut et la limite maximale pour votre plan de compte.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
// ...
  output: "server",
  adapter: vercel({
    maxDuration: 60
  }),
});

Configuration du regroupement des fonctions

L’adaptateur Vercel combine toutes vos routes en une seule fonction par défaut.

Vous avez également la possibilité de diviser les constructions en une fonction séparée pour chaque route en utilisant l’option functionPerRoute. Cela réduit la taille de chaque fonction, ce qui signifie que vous êtes moins susceptible de dépasser la limite de taille pour une fonction individuelle. De plus, les démarrages de code sont plus rapides.

Vérifiez que votre plan Vercel comprend un nombre approprié de fonctions avant d’activer l’option functionPerRoute. Par exemple, le niveau gratuit de Vercel limite chaque déploiement à un maximum de 12 fonctions. Si votre plan Vercel est insuffisant pour le nombre de routes de votre projet, vous recevrez un message d’erreur pendant le déploiement.

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    functionPerRoute: true,
  }),
});

Le middleware Vercel Edge avec le middleware Astro

L’adaptateur @astrojs/vercel/serverless peut créer une [fonction edge] (https://vercel.com/docs/functions/edge-functions) à partir d’un middleware Astro dans votre base de code. Lorsque ‘edgeMiddleware’ est activé, une fonction edge exécute votre code middleware pour toutes les demandes, 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.

Il s’agit d’une fonctionnalité opt-in, et l’option edgeMiddleware doit être positionnée à true :

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    edgeMiddleware: true,
  }),
});

L’Edge Middleware a accès au RequestContext de Vercel avec ctx.locals.vercel.edge. Si vous utilisez TypeScript, vous pouvez obtenir les typages appropriés en mettant à jour src/env.d.ts pour utiliser EdgeLocals :

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />

type EdgeLocals = import('@astrojs/vercel').EdgeLocals

declare namespace App {
  interface Locals extends EdgeLocals {
    // ...
  }
}

Support des versions de Node.js

L’adaptateur @astrojs/vercel supporte des versions spécifiques de Node.js pour déployer votre projet Astro sur Vercel. Pour voir les versions de Node.js supportées sur Vercel, cliquez sur l’onglet des paramètres d’un projet et descendez jusqu’à la section “Node.js Version”.