Déployez votre site Astro sur les pages Cloudflare

Vous pouvez déployer votre projet Astro sur Cloudflare Pages, une plateforme permettant aux développeurs frontaux de collaborer et de déployer des sites web statiques (JAMstack) et SSR.

Ce guide comprend :

Comment déployer via le Cloudflare Pages Dashboard
Comment déployer un site en utilisant Wrangler, la CLI de Cloudflare
Comment déployer un site SSR en utilisant @astrojs/cloudflare

Pré-requis

Pour commencer, vous aurez besoin :

Un compte Cloudflare. Si vous n’en avez pas encore, vous pouvez créer un compte Cloudflare gratuit au cours de la procédure.
Le code de votre application poussé sur un dépôt GitHub ou GitLab.

Comment déployer un site avec Git

Créez un nouveau projet sur Cloudflare Pages.
Poussez votre code dans votre dépôt Git (GitHub, GitLab).
Connectez-vous au tableau de bord de Cloudflare et sélectionnez votre compte dans Comptes > Workers et Pages.
Sélectionnez Créer une application, naviguez dans l’onglet Pages et cliquez sur Se connecter à Git.
Sélectionnez le projet git que vous souhaitez déployer et cliquez sur Commencer la configuration.
Utilisez les paramètres de construction suivants :

Framework preset: Astro
Build command: npm run build
Build output directory: dist

Cliquez sur le bouton Enregistrer et déployer.

Comment déployer un site à l’aide de Wrangler

Installez Wrangler CLI.
Authentifiez Wrangler avec votre compte Cloudflare en utilisant wrangler login.
Lancez votre commande de construction.
Déployez en utilisant npx wrangler pages deploy dist.

# Installez Wrangler CLI
npm install -g wrangler
# Connectez-vous à votre compte Cloudflare depuis le CLI
wrangler login
# Exécutez votre commande de build
npm run build
# Créer un nouveau déploiement
npx wrangler pages deploy dist

Une fois vos ressources téléchargées, Wrangler vous donnera une URL de prévisualisation pour inspecter votre site. Lorsque vous vous connectez au tableau de bord de Cloudflare Pages, vous verrez votre nouveau projet.

Activer la prévisualisation localement avec Wrangler

Pour que la prévisualisation fonctionne, vous devez installer wrangler

pnpm install wrangler --save-dev

Il est alors possible de mettre à jour le script de prévisualisation pour exécuter wrangler au lieu de la commande de prévisualisation intégrée à Astro :

"preview" : "wrangler pages dev ./dist"

Comment déployer un site SSR

Vous pouvez construire un site Astro SSR pour le déployer sur Cloudflare Pages en utilisant l’adaptateur @astrojs/cloudflare.

Suivez les étapes ci-dessous pour configurer l’adaptateur. Vous pouvez ensuite déployer en utilisant l’une ou l’autre des approches documentées ci-dessus.

Installation rapide

Ajoutez l’adaptateur Cloudflare pour activer SSR dans votre projet Astro avec la commande astro add suivante. Cela installera l’adaptateur et apportera les changements appropriés à votre fichier astro.config.mjs en une seule étape.

npx astro add cloudflare

Installation manuelle

Si vous préférez installer l’adaptateur manuellement, suivez les deux étapes suivantes :

Ajoutez l’adaptateur @astrojs/cloudflare aux dépendances de votre projet en utilisant votre gestionnaire de paquets préféré. Si vous utilisez npm ou si vous n’êtes pas sûr, lancez ceci dans le terminal :

npm install @astrojs/cloudflare

Ajoutez ce qui suit à votre fichier astro.config.mjs :

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

export default defineConfig({
  output : 'server',
  adapter : cloudflare()
}) ;

Les modes

Il existe actuellement deux modes d’utilisation de Pages Functions avec l’adaptateur @astrojs/cloudflare.

Mode Avancé : Ce mode est utilisé lorsque vous voulez exécuter votre fonction en mode “avancé” qui récupère le _worker.js dans dist, ou en mode répertoire où les pages compileront le worker à partir d’un dossier de fonctions à la racine du projet.

Si aucun mode n’est défini, la valeur par défaut est “advanced”.

Mode directory : Ce mode est utilisé lorsque vous voulez exécuter votre fonction en mode “répertoire”, ce qui signifie que l’adaptateur compilera la partie client de votre application de la même manière, mais il déplacera le script worker dans un dossier functions à la racine du projet. L’adaptateur ne placera jamais qu’un [[path]].js dans ce dossier, ce qui vous permet d’ajouter des plugins et des pages middleware supplémentaires qui peuvent être vérifiés dans le contrôle de version.

export default defineConfig({
  adapter : cloudflare({ mode : "directory" }),
}) ;

Utilisation de Pages Functions

Les Pages Functions vous permettent d’exécuter du code côté serveur afin d’activer des fonctionnalités dynamiques sans avoir recours à un serveur dédié.

Pour commencer, créez un répertoire /functions à la racine de votre projet. L’écriture de vos fichiers Functions dans ce répertoire génère automatiquement un Worker avec des fonctionnalités personnalisées aux itinéraires prédéfinis. Pour en savoir plus sur l’écriture des fonctions, consultez la documentation Pages Functions.

📚 En savoir plus sur SSR in Astro (EN).

Dépannage

Si vous rencontrez des erreurs, vérifiez que la version de node que vous utilisez localement (node -v) correspond à la version que vous spécifiez dans la variable d’environnement.

Cloudflare requiert Node v16.13, qui est une version plus récente que la version minimale d’Astro, donc vérifiez que vous utilisez au moins v16.13.

L’hydratation côté client peut échouer à cause du paramètre Auto Minify de Cloudflare. Si vous voyez Hydration completed but contains mismatches dans la console, assurez-vous de désactiver Auto Minify dans les paramètres de Cloudflare.