@astrojs/ cloudflare

v13.1.3 GitHub npm Journal des modifications

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

Si vous utilisez Astro comme générateur de site statique, vous n’avez pas besoin d’adaptateur.

Découvrez comment déployer votre site Astro dans notre guide de déploiement Cloudflare.

Pourquoi Astro Cloudflare

La plateforme de développement de Cloudflare vous permet de développer des applications full-stack avec accès à des ressources telles que le stockage et l’IA, le tout déployé sur un réseau mondial. Cet adaptateur compile votre projet Astro pour le déploiement via Cloudflare.

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

npx astro add cloudflare

pnpm astro add cloudflare

yarn astro add cloudflare

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

Ajoutez l’adaptateur @astrojs/cloudflare aux dépendances de votre projet à l’aide de votre gestionnaire de paquets préféré.
- npm
- pnpm
- Yarn
Fenêtre du terminal
npm install @astrojs/cloudflare
Fenêtre du terminal
pnpm add @astrojs/cloudflare
Fenêtre du terminal
yarn add @astrojs/cloudflare

Ajoutez l’adaptateur à votre fichier astro.config.mjs :

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

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

Astro générera automatiquement une configuration par défaut, en utilisant le champ name du fichier package.json ou le nom du dossier comme nom du Worker. Vous pouvez également créer un fichier de configuration Wrangler si vous avez besoin de paramètres personnalisés. Cet exemple déclare les liaisons KV de Cloudflare :
wrangler.jsonc
```
{
  "name": "mon-app-astro",
  // Ajoutez vos liaisons ici, par exemple :
  // "kv_namespaces": [{ "binding": "MA_CV", "id": "<id_espace_de_noms>" }]
}
```

Options

L’adaptateur Cloudflare accepte les options suivantes de @cloudflare/vite-plugin :

auxiliaryWorkers
configPath
inspectorPort
persistState
remoteBindings
experimental.headersAndRedirectsDevModeSupport

Il accepte également les options suivantes :

`imageService`

Type : 'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' }
Par défaut : 'cloudflare-binding'

Détermine quel service d’image est utilisé par l’adaptateur. L’adaptateur utilisera par défaut le mode cloudflare-binding si un service d’image incompatible est configuré. Sinon, il utilisera le service d’image configuré globalement :

cloudflare : Utilise le service de redimensionnement d’image de Cloudflare.
cloudflare-binding : Utilise la liaison Cloudflare Images pour la transformation d’images. La liaison est automatiquement configurée lors du déploiement.
passthrough : Utilise le service existant noop.
compile : Utilise une combinaison de dépendances internes pour transformer localement les images lors de la compilation pour les routes pré-rendues. L’option passthrough sans opération est configurée pour les pages rendues à la demande.
custom : Utilise toujours le service d’image configuré dans les options d’images. Cette option ne vérifiera pas si le service d’image configuré fonctionne dans l’environnemment d’exécution workerd de Cloudflare.

Il est également possible de configurer votre service d’images comme un objet, en définissant indépendamment un service pour la compilation et un service pour l’environnement d’exécution. Actuellement, 'compile' est la seule option disponible au moment de la compilation. Les options de l’environnement d’exécution prises en charge sont 'passthrough' (par défaut) et 'cloudflare-binding'.

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

export default defineConfig({
  adapter: cloudflare({
    imageService: { build: 'compile', runtime: 'cloudflare-binding' }
  }),
});

`sessionKVBindingName`

Type : string
Par défaut : SESSION

Ajouté à la version : @astrojs/cloudflare@12.4.0

Définit le nom de la liaison KV utilisée pour le stockage des sessions. Par défaut, l’espace de noms KV est automatiquement configuré lors du déploiement et se nomme SESSION. Vous pouvez modifier ce nom en configurant manuellement la liaison dans votre configuration Wrangler. Consultez Sessions pour plus d’informations.

export default defineConfig({
  adapter: cloudflare({
    sessionKVBindingName: 'MA_LIAISON_DE_SESSION',
  }),
});

{
  "kv_namespaces": [
    {
      "binding": "MA_LIAISON_DE_SESSION",
    }
  ]
}

`imagesBindingName`

Type : string
Par défaut : IMAGES

Définit le nom de la liaison Images utilisée lorsque imageService est défini sur cloudflare-binding. Par défaut, la liaison est automatiquement configurée sous le nom IMAGES lors du déploiement. Vous pouvez la modifier en la configurant manuellement dans votre configuration Wrangler :

export default defineConfig({
  adapter: cloudflare({
    imageService: 'cloudflare-binding',
    imagesBindingName: 'MES_IMAGES',
  }),
});

{
  "images": {
    "binding": "MES_IMAGES"
  }
}

`prerenderEnvironment`

Type : 'workerd' | 'node'
Par défaut : 'workerd'

Ajouté à la version : @astrojs/cloudflare@13.1.0 Nouveau

Contrôle quel environnement d’exécution est utilisé pour le prérendu des pages statiques au moment de la compilation et pendant le développement.

Par défaut, les pages pré-rendues sont générées à l’aide de l’environnement d’exécution workerd de Cloudflare afin de reproduire au mieux l’environnement de production. Définissez cette option sur 'node' si vos pages pré-rendues dépendent d’API Node.js ou de paquets NPM incompatibles avec workerd.

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

export default defineConfig({
  adapter: cloudflare({
    prerenderEnvironment: 'node',
  }),
});

Par exemple, si une page pré-rendue lit les fichiers depuis le système de fichiers via node:fs, définissez prerenderEnvironment sur 'node'. Les pages rendues à la demande ne sont pas affectées par cette option et s’exécutent toujours dans workerd.

Environnement d’exécution Cloudflare

L’environnement d’exécution Cloudflare vous donne accès aux variables d’environnement, aux liaisons aux ressources Cloudflare et à d’autres API spécifiques à Cloudflare.

Variables d’environnement et liaisons

Les variables d’environnement et les liaisons sont définies dans votre fichier de configuration wrangler.jsonc.

Définissez des variables d’environnement qui ne stockent pas d’informations sensibles dans wrangler.jsonc :

{
  "vars" : {
    "MA_VARIABLE": "test"
  }
}

Les secrets sont un type particulier de variable d’environnement permettant d’associer des valeurs textuelles chiffrées à votre Worker. Il est nécessaire de les définir différemment afin de garantir qu’elles ne soient pas visibles au sein de Wrangler ou dans le tableau de bord Cloudflare après leur configuration.

Pour définir des secrets, ajoutez-les via la CLI de Wrangler plutôt que dans votre fichier de configuration Wrangler.

npx wrangler secret put <KEY>

Pour définir des secrets pour le développement local, vous devez également ajouter un fichier .dev.vars à la racine du projet Astro :

DB_PASSWORD=monMotDePasse

Les variables d’environnement et les secrets de Cloudflare peuvent être importés depuis "cloudflare:workers" :

---
import { env } from 'cloudflare:workers';

const myVariable = env.MY_VARIABLE;
const myKVNamespace = env.MY_KV;
---

Elles sont également compatibles avec l’API astro:env :

import { MY_VARIABLE } from 'astro:env/server';

Consultez la liste de toutes les liaisons prises en charge dans la documentation de Cloudflare.

L’objet `cf`

L’objet cf de Cloudflare contient des métadonnées de requête telles que des informations de géolocalisation. Accédez-y directement depuis la requête :

---
const cf = Astro.request.cf;
const country = cf?.country;
---

Contexte d’exécution

Accédez au contexte d’exécution (ExecutionContext) de Cloudflare via Astro.locals.cfContext. Ceci est utile pour des opérations comme waitUntil(), ou pour accéder aux exportations d’objets durables dans votre page.

---
const cfContext = Astro.locals.cfContext;
cfContext.exports.Greeter.greet('Astro');
cfContext.waitUntil(someAsyncOperation());
---

Définition de types

wrangler fournit une commande types pour générer des types TypeScript pour vos liaisons. Cela vous permet d’ajouter des types à votre environnement sans avoir besoin de définitions de type manuelles.

Exécutez wrangler types chaque fois que vous modifiez vos fichiers de configuration (par exemple wrangler.jsonc, .dev.vars).

L’exemple suivant illustre une configuration de script permettant d’exécuter automatiquement wrangler types avant les autres commandes :

{
  "scripts": {
    "dev": "wrangler types && astro dev",
    "start": "wrangler types && astro dev",
    "build": "wrangler types && astro check && astro build",
    "preview": "wrangler types && astro preview",
    "astro": "astro"
  }
}

Plate-forme Cloudflare

En-têtes

Vous pouvez attacher des en-têtes personnalisés à vos réponses en ajoutant un fichier _headers dans le dossier public/ de votre projet Astro. Ce fichier sera copié dans le répertoire de sortie de la compilation. Les en-têtes définis dans _headers ne sont pas appliqués aux réponses générées par le code de votre Worker.

Ressources

Les ressources créées par Astro sont toutes nommées avec un hachage et peuvent donc se voir attribuer de longs en-têtes de cache. Par défaut, Astro sur Cloudflare ajoutera un tel en-tête pour ces fichiers.

Redirections

Déclarez des redirections personnalisées pour les ressources statiques en ajoutant un fichier _redirects dans le dossier public/ de votre projet Astro. Ce fichier sera copié dans le répertoire de sortie de votre compilation. Pour les routes dynamiques, configurez les redirections directement dans Astro à la place.

Routes

Le routage des ressources statiques s’appuie sur la structure des fichiers du répertoire de compilation (par exemple, ./dist). En l’absence de correspondance, un rendu à la demande sera effectué par le Worker. Pour en savoir plus, consultez la documentation du routage des ressources statiques avec Cloudflare Workers.

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 Workers KV pour le stockage de session lors de l’utilisation de l’adaptateur Cloudflare. Wrangler peut automatiquement configurer l’espace de noms KV lors du déploiement, aucune configuration manuelle n’est donc requise. Vous pouvez également définir la liaison KV manuellement dans votre fichier wrangler.jsonc et définir un nom de liaison personnalisé à l’aide de l’option sessionKVBindingName de l’adaptateur.

---
export const prerender = false; // Pas nécessaire en mode `server`
const cart = await Astro.session?.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} produits</a>

Par défaut, la liaison KV est nommée SESSION. Pour utiliser un autre nom, définissez l’option sessionKVBindingName dans la configuration de l’adaptateur.

Importations de modules Cloudflare

L’environnement d’exécution workerd de Cloudflare prend en charge les importations de certains types de modules non standard. La plupart des types de fichiers supplémentaires sont également disponibles dans Astro :

.wasm ou .wasm?module : exporte un WebAssembly.Module qui peut ensuite être instancié.
.bin : exporte un ArrayBuffer du contenu binaire brut du fichier
.txt : exporte une chaîne de caractères du contenu du fichier

Tous les types de modules exportent une seule valeur par défaut. Les modules peuvent être importés à partir de pages rendues côté serveur ou de pages pré-rendues pour la génération de sites statiques.

Voici un exemple d’importation d’un module Wasm qui répond aux requêtes en additionnant les paramètres numériques de la requête.

// Importer le module WebAssembly
import mod from '../util/add.wasm';

// Instancier d'abord pour l'utiliser
const addModule: any = new WebAssembly.Instance(mod);

export async function GET(context) {
  const a = Number.parseInt(context.params.a);
  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}

Bien que cet exemple soit trivial, Wasm peut être utilisé pour accélérer des opérations de calcul intensif qui n’impliquent pas d’E/S importantes, comme l’intégration d’une bibliothèque de traitement d’images, ou l’intégration d’une petite base de données pré-indexée pour la recherche sur un ensemble de données en lecture seule.

Compatibilité Node.js

Cloudflare Workers prend en charge la plupart des API de l’environnement d’exécution Node.js grâce à l’option de compatibilité nodejs_compat. Cela inclut des modules couramment utilisés comme node:buffer, node:crypto, node:path et bien d’autres. Consultez la liste complète des API Node.js prises en charge dans la documentation de Cloudflare.

Pour activer la compatibilité avec Node.js, ajoutez l’indicateur nodejs_compat à votre configuration Wrangler :

{
  "compatibility_flags": ["nodejs_compat"],
}

Utilisez ensuite la syntaxe d’importation node:* dans votre code côté serveur :

export const prerender = false; // Pas nécessaire en mode `server`
import { Buffer } from 'node:buffer';

Pour les API Node.js qui ne sont pas encore prises en charge dans l’environnement d’exécution Workers, Wrangler peut injecter des polyfills (nécessite nodejs_compat et une date de compatibilité démarrant au 23/09/2024).

Consultez la documentation de Cloudflare sur la compatibilité Node.js pour obtenir la liste complète des API prises en charge et les détails de configuration.

Aperçu local

Après avoir compilé votre projet avec astro build, utilisez astro preview pour tester localement votre application Cloudflare Workers. L’aperçu s’exécute avec l’environnement d’exécution workerd de Cloudflare, reproduisant fidèlement le comportement en production.

Messages d’erreur significatifs

Par défaut, les erreurs survenant lors de l’exécution de votre application dans Wrangler sont minifiées. Pour un débogage plus efficace, ajoutez vite.build.minify = false à votre fichier astro.config.mjs :

export default defineConfig({
  adapter: cloudflare(),
  vite: {
    build: {
      minify: false,
    },
  },
});

Mise à niveau vers v13 et Astro 6

Astro 6 apporte des améliorations significatives à l’expérience de développement avec Cloudflare et nécessite @astrojs/cloudflare v13 ou une version ultérieure. Désormais, astro dev utilise le module d’extension Vite de Cloudflare et l’environnement d’exécution workerd pour reproduire fidèlement le comportement en production.

Consultez le guide de mise à niveau vers Astro 6 (EN) pour obtenir des instructions complètes sur la façon de mettre à niveau Astro de manière générale.

Le serveur de développement utilise désormais workerd

Le changement le plus important pour les utilisateurs de Cloudflare avec Astro 6 est que les commandes astro dev et astro preview utilisent désormais le module d’extension Vite de Cloudflare pour exécuter votre site en utilisant le véritable environnement d’exécution de Workers (workerd) au lieu de Node.js. Cela signifie que votre environnement de développement est désormais une réplique beaucoup plus fidèle de votre environnement de production, avec le même environnement d’exécution, les mêmes API et le même comportement.

Ce changement vous aide à détecter les problèmes pendant le développement qui n’apparaissaient auparavant qu’en production, et des fonctionnalités comme Durable Objects, les liaisons R2 et Workers AI fonctionnent désormais exactement comme lorsqu’elles sont déployées sur la plateforme Cloudflare.

Ce changement est transparent pour la plupart des projets. Si votre projet comportait une configuration spéciale pour astro dev ou s’appuyait sur un comportement spécifique à Node.js en développement, ajustez votre code ou votre configuration en conséquence.

Nouveau : Option `prerenderEnvironment`

Dans Astro 6, les pages pré-rendues s’exécutent désormais par défaut dans l’environnement d’exécution workerd de Cloudflare pendant le développement et la compilation. Auparavant, ces pages s’exécutaient toujours dans Node.js.

Si vos pages prérendues dépendent d’API Node.js (par exemple node:fs) ou de paquets NPM qui ne sont pas compatibles avec workerd, définissez prerenderEnvironment: 'node' dans la configuration de votre adaptateur Cloudflare pour rétablir le comportement précédent de prérendu.

Les pages rendues à la demande ne sont pas affectées par cette option et continuent de s’exécuter dans workerd.

Consultez prerenderEnvironment pour plus de détails sur la configuration.

Certaines dépendances peuvent nécessiter une précompilation.

Le nouvel environnement workerd ne prend pas en charge la syntaxe CommonJS, notamment la syntaxe spécifique à Node.js comme require et module.exports. Cela signifie que certaines dépendances de votre projet peuvent générer des erreurs dans le serveur de développement ou lors de la compilation.

Si vous avez le contrôle sur la dépendance, vous pouvez créer un module d’extension pour Vite et précompiler la dépendance à l’aide de l’option optimizeDeps.include.

Par exemple, vous pouvez créer un module d’extension pour Vite afin de précompiler la dépendance postcss et d’utiliser le colorateur syntaxique Expressive Code :

function noExternalPlugin() {
  return {
    name: "optimiser-les-dependances",
    configEnvironment(environment) {
      // Nous nous intéressons uniquement aux environnements serveur.
      if (environment !== 'client') {
        return {
          optimizeDeps: {
            include: [
              "postcss"
              // Vous pouvez également utiliser cette syntaxe si vous ne dépendez pas directement d'une dépendance.
              // "expressive-code > postcss"
            ]
          }
        }
      }
    }
  }
}

Modifié : Configuration du point d’entrée de Wrangler

Auparavant, le champ main de votre configuration Wrangler pointait vers le fichier worker compilé (par exemple, dist/_worker.js/index.js). Avec Astro 6, ce champ pointe désormais vers un nouveau point d’entrée unifié fourni par l’adaptateur Cloudflare : @astrojs/cloudflare/entrypoints/server.

Mettez à jour votre fichier wrangler.jsonc pour utiliser le nouveau point d’entrée :

{
  "main": "dist/_worker.js/index.js",
  "main": "@astrojs/cloudflare/entrypoints/server",
  "name": "mon-app-astro",
  // ... le reste de la config
}

Ce point d’entrée unique gère à la fois les déploiements astro dev et de production.

Supprimé : API `Astro.locals.runtime`

L’objet Astro.locals.runtime a été supprimé au profit d’un accès direct aux API de Cloudflare Workers. Accédez directement aux variables d’environnement, à l’objet cf, aux caches et au contexte d’exécution via les interfaces fournies.

Accéder aux variables d’environnement :

Auparavant, les variables d’environnement étaient accessibles via Astro.locals.runtime.env. Désormais, importez directement env :

const { env } = Astro.locals.runtime;
import { env } from 'cloudflare:workers';

Accéder à l’objet cf :

Auparavant, l’objet cf était accessible via Astro.locals.runtime.cf. Désormais, accédez-y directement depuis la requête :

const { cf } = Astro.locals.runtime;
const cf = Astro.request.cf;

Accès à l’API des caches :

Auparavant, l’API des caches était accessible via Astro.locals.runtime.caches. Utilisez désormais directement l’objet global caches :

const { caches } = Astro.locals.runtime;

caches.default.put(request, response);

Accès au contexte d’exécution :

L’objet Astro.locals.runtime.ctx est remplacé par Astro.locals.cfContext, qui contient le contexte d’exécution (ExecutionContext) de Cloudflare :

const ctx = Astro.locals.runtime.ctx;
const ctx = Astro.locals.cfContext;

Modifié : Le fichier de configuration Wrangler est désormais optionnel

Le fichier de configuration Wrangler est désormais facultatif pour les projets simples. Si vous ne disposez pas d’une configuration personnalisée, telle que des liaisons Cloudflare (KV, D1, Durable Objects, etc.), Astro générera automatiquement une configuration par défaut pour vous.

Si votre fichier wrangler.jsonc ne contient qu’une configuration de base comme celle-ci :

{
  "main": "@astrojs/cloudflare/entrypoints/server",
  "compatibility_date": "2025-05-21",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
  },
}

Vous pouvez supprimer ce fichier sans risque. Astro gère cette configuration automatiquement. Sinon, créez un fichier wrangler.jsonc minimal contenant uniquement le nom de votre projet et vos autres paramètres personnalisés :

{
  "name": "mon-app-astro",
}

Modifié : Point d’entrée d’API personnalisé

Si vous utilisiez une configuration workerEntryPoint personnalisée dans les options de l’adaptateur, celle-ci a été supprimée. Spécifiez plutôt votre point d’entrée personnalisé dans votre configuration Wrangler et créez directement un objet d’exportation Cloudflare Worker standard, plutôt que d’utiliser la fonction createExports().

Supprimez l’option workerEntryPoint de la configuration de votre adaptateur :

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

export default defineConfig({
  adapter: cloudflare({
    workerEntryPoint: {
      path: 'src/worker.ts',
      namedExports: ['MyDurableObject'],
    },
  }),
});

Indiquez plutôt le point d’entrée dans wrangler.jsonc :
wrangler.jsonc
```
{
  "main": "./src/worker.ts"
}
```

Mettez à jour votre fichier d’entrée Worker personnalisé pour utiliser la syntaxe Worker standard. Importez le gestionnaire depuis @astrojs/cloudflare/handler et exportez un objet Cloudflare Worker standard, ainsi que toutes les exportations personnalisées telles que les objets durables :

import { handle } from '@astrojs/cloudflare/handler';
import { DurableObject } from 'cloudflare:workers';

export class MyDurableObject extends DurableObject<Env> {
  // ...
}

export default {
  async fetch(request, env, ctx) {
    await env.MY_QUEUE.send('message');
    return handle(request, env, ctx);
  },
  async queue(batch, _env) {
    let messages = JSON.stringify(batch.messages);
    console.log(`consommé depuis notre file d'attente : ${messages}`);
  },
} satisfies ExportedHandler<Env>;

Le manifeste est désormais créé en interne par l’adaptateur, il n’est donc plus nécessaire de le transmettre à votre gestionnaire.

Supprimé : Option `cloudflareModules`

L’option cloudflareModules de l’adaptateur a été supprimée car elle n’est plus nécessaire. Cloudflare prend en charge nativement l’importation de modules .sql, .wasm et d’autres types de modules.

Supprimez l’option cloudflareModules de la configuration de votre adaptateur Cloudflare si vous l’utilisiez :

import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    cloudflareModules: true
  })
});

Nouveau : Prise en charge d’`astro preview`

Utilisez astro preview pour tester localement votre application Cloudflare Workers avant son déploiement. L’aperçu s’exécute avec l’environnement d’exécution workerd de Cloudflare, reproduisant fidèlement le comportement en production. Exécutez astro build puis astro preview pour démarrer le serveur de prévisualisation.

Supprimée : Prise en charge de Cloudflare Pages

L’adaptateur Cloudflare d’Astro ne prend plus en charge le déploiement sur Cloudflare Pages. Pour une expérience optimale et une prise en charge complète des fonctionnalités, vous devriez migrer vers Cloudflare Workers.

Consultez le guide de migration de Pages vers Workers de Cloudflare pour obtenir des instructions de migration détaillées.

Modifiée : Valeur par défaut de `imageService`

La valeur par défaut de imageService est passée de 'compile' à 'cloudflare-binding' pour une expérience améliorée lors de la manipulation d’images.

Le service cloudflare-binding utilise la liaison Cloudflare Images pour transformer les images au moment de l’exécution, et la liaison est automatiquement configurée lors du déploiement.

Pour revenir au comportement précédent, où la transformation d’image n’était disponible que sur les routes pré-rendues au moment de la compilation, définissez explicitement imageService: 'compile' dans la configuration de votre adaptateur.