@astrojs/ cloudflare

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

Si vous utilisez Astro comme constructeur de sites statiques, vous n’avez pas besoin d’adaptateur.

Découvrez comment déployer votre site Astro dans notre Guide de déploiement des pages Cloudflare.

Pourquoi Astro Cloudflare

Cloudflare fournit des CDN, de la sécurité web et d’autres services. Cet adaptateur améliore le processus de construction d’Astro pour préparer votre projet à être déployé 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 SSR 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

Installation manuelle

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

npm install @astrojs/cloudflare

pnpm add @astrojs/cloudflare

yarn add @astrojs/cloudflare

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

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

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

Options

mode

Type : 'advanced' | 'directory'
Par défaut : 'advanced'

Cette option de configuration définit la manière dont votre projet Astro est déployé sur les pages Cloudflare.

Le mode advanced récupère le fichier _worker.js dans le dossier dist.
Le mode directory récupère les fichiers dans le dossier functions, par défaut un seul fichier [[path]].js est généré.

Le passage en mode répertoire vous permet d’ajouter manuellement des fichiers supplémentaires tels que Cloudflare Pages Plugins, Cloudflare Pages Middleware ou des fonctions personnalisées à l’aide de Cloudflare Pages Functions Routing.

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

Pour compiler un bundle séparé pour chaque page, définissez l’option functionPerRoute dans la configuration de votre adaptateur Cloudflare. Cette option nécessite une maintenance manuelle du dossier functions. Les fichiers émis par Astro écraseront les fichiers existants avec des noms identiques dans le dossier functions, vous devez donc choisir des noms de fichiers uniques pour chaque fichier que vous ajoutez manuellement. De plus, l’adaptateur ne videra jamais le dossier functions des fichiers obsolètes, vous devez donc nettoyer le dossier manuellement lorsque vous supprimez des pages.

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

export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    functionPerRoute: true
  })
})

Cet adaptateur ne supporte pas l’option edgeMiddleware.

routes.strategy

Type : 'auto' | 'include' | 'exclude'
Par défaut : 'auto'

Détermine comment routes.json sera généré si aucun _routes.json personnalisé n’est fourni.

Il y a trois options disponibles :

"auto" (par défaut) : Sélectionne automatiquement la stratégie qui génère le moins d’entrées. Cela devrait presque toujours être suffisant, donc choisissez cette option à moins que vous n’ayez une raison spécifique de ne pas le faire.
include : Les pages et les points de terminaison (endpoints) qui ne sont pas pré-rendus sont listés en tant qu’entrées include indiquant à Cloudflare d’invoquer ces routes en tant que fonctions. Les entrées exclude ne sont utilisées que pour résoudre les conflits. C’est généralement la meilleure stratégie lorsque votre site web a principalement des pages statiques et seulement quelques pages dynamiques ou points de terminaison.

Exemple : Pour src/pages/index.astro (statique), src/pages/company.astro (statique), src/pages/users/faq.astro (statique) et /src/pages/users/[id].astro (SSR) cela produira les _routes.json suivantes :
```
{
  "version": 1,
  "include": [
    "/_image", // Point de terminaison pour les images
    "/users/*" // Route dynamique
  ],
  "exclude": [
    // Routes statiques qui doivent être exemptées de la route dynamique à caractères génériques ci-dessus
    "/users/faq/",
    "/users/faq/index.html"
  ]
}
```
exclude : Les pages pré-rendues sont listées en tant qu’entrées exclude (indiquant à Cloudflare de traiter ces routes comme des actifs statiques). C’est généralement la meilleure stratégie lorsque votre site web a principalement des pages dynamiques ou des points de terminaison et seulement quelques pages statiques.

Exemple : Pour les mêmes pages que dans l’exemple précédent, cela produira le _routes.json suivant :
```
{
  "version": 1,
  "include": [
    "/*" // Tout se déroule comme prévu, à l'exception des routes ci-dessous
  ],
  "exclude": [
    // Tous les contenus actifs
    "/",
    "/company/",
    "/index.html",
    "/users/faq/",
    "/favicon.png",
    "/company/index.html",
    "/users/faq/index.html"
  ]
}
```

routes.include

Type : string[]
Par défaut : []

Si vous voulez utiliser la génération automatique de _routes.json, mais que vous voulez inclure des routes supplémentaires (par exemple, lorsque vous avez des fonctions personnalisées dans le dossier functions), vous pouvez utiliser l’option routes.include pour ajouter des routes supplémentaires au tableau include.

routes.exclude

Type : string[]
Par défaut : []

Si vous voulez utiliser la génération automatique de _routes.json, mais que vous voulez exclure des routes supplémentaires, vous pouvez utiliser l’option routes.exclude pour ajouter des routes supplémentaires au tableau exclude.

L’exemple suivant génère automatiquement _routes.json en incluant et en excluant des routes supplémentaires. Notez que cela n’est nécessaire que si vous avez des fonctions personnalisées dans le dossier functions qui ne sont pas gérées par Astro.

export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    routes: {
      strategy: 'include',
      include: ['/users/*'], // géré par une fonction personnalisée : functions/users/[id].js
      exclude: ['/users/faq'], // géré par une page statique : pages/users/faq.astro
    },
  }),
});

imageService

Type : 'passthrough' | 'cloudflare' | 'compile'
Par défaut : 'passthrough'

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

cloudflare: Utilise le service Cloudflare Image Resizing.
passthrough: Utilise le service existant noop.
compile: Utilise le service par défaut d’Astro (sharp), mais seulement sur les routes pré-rendues au moment de la compilation. Pendant le SSR pour les pages rendues à la demande, toutes les fonctionnalités de astro:assets sont désactivées.

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

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

wasmModuleImports

Type : true | false
Par défaut : false

Importer ou non les fichiers .wasm directement en tant que modules ES.

Ajouter wasmModuleImports: true à astro.config.mjs pour l’activer à la fois dans la version Cloudflare et dans le serveur de développement Astro. En savoir plus sur l’utilisation des modules Wasm.

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

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

runtime

Type:

{ mode: 'off' }
| { mode: 'local'; type: 'pages'; persistTo?: string; bindings?: Record<string, CF_BINDING> }
| { mode: 'local'; type: 'workers'; persistTo?: string; };

(CF_BINDING type reference)
Default: { mode: 'off', persistTo: '' }

Détermine si et comment le Cloudflare Runtime est ajouté à astro dev. En savoir plus sur le moteur d’exécution Cloudflare.

La propriété type définit où votre projet Astro est déployé :

pages : Déployé sur Cloudflare Pages
workers : Déployé sur Cloudflare Workers

La propriété mode définit ce que vous voulez que le runtime supporte dans astro dev :

off : pas d’accès au runtime en utilisant astro dev. Vous pouvez choisir Preview with Wrangler quand vous avez besoin d’accéder au runtime, pour simuler l’environnement de production localement.
local : utilise un runtime local alimenté par miniflare et workerd, qui supporte les Bindings de Cloudflare. Seulement si vous voulez utiliser des fonctionnalités non supportées, comme eval, les bindings sans support local choisissent Preview with Wrangler

En mode : local, vous avez accès à la propriété persistTo qui définit où l’état des bindings locaux est sauvegardé. Cela permet d’éviter d’avoir de nouvelles bindings à chaque redémarrage du serveur de développement. Cette valeur est un répertoire relatif à votre chemin d’exécution astro dev. Par défaut, il est positionné à .wrangler/state/v3 pour permettre l’utilisation des commandes clientes wrangler (par exemple pour les migrations). Ajoutez ce chemin à votre .gitignore.

Cloudflare runtime

Le runtime de Cloudflare vous donne accès aux variables d’environnement et aux bindings de Cloudflare. Vous pouvez trouver plus d’informations dans les documents de Cloudflare Workers et Pages. Selon votre type de déploiement (pages ou workers), vous devez configurer les bindings différemment.

Liaisons actuellement prises en charge :

Config

Cloudflare Pages

Cloudflare Pages ne prend pas en charge un fichier de configuration.

Pour déployer votre projet de pages en production, vous devez configurer les bindings en utilisant le Dashboard de Cloudflare. Pour pouvoir accéder aux bindings localement, vous devez les configurer en utilisant l’option runtime de l’adaptateur.

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    runtime: {
      mode: 'local',
      type: 'pages',
      bindings: {
        // exemple de liaison var (variable d'environnement)
        "URL": {
          type: "var",
          value: "https://example.com",
        },
        // exemple de liaison KV
        "KV": {
          type: "kv",
        },
        // exemple de liaison D1
        "D1": {
          type: "d1",
        },
        // exemple de liaison R2
        "R2": {
          type: "r2",
        },
        // exemple de liaison avec Durable Object binding
        "DO": {
          type: "durable-object",
          className: "DO",
        },
      },
    },
  }),
});

Si vous avez besoin de définir des secrets en plus des variables d’environnement, vous devez ajouter un fichier .dev.vars à la racine du projet Astro :

DB_PASSWORD=myPassword

Si vous voulez utiliser wrangler pour des commandes clientes, par exemple les migrations D1, vous devez également ajouter un wrangler.toml à la racine du projet Astro avec le contenu correct. Consultez la documentation de Cloudflare pour plus de détails.

name = "example"
compatibility_date = "2023-06-14"

# exemple pour D1 Binding
[[d1_databases]]
binding = "D1"
database_name = "D1"
database_id = "D1"
preview_database_id = "D1"

Cloudflare Workers

Pour déployer votre projet workers en production, vous devez configurer les bindings en utilisant un fichier de configuration wrangler.toml dans le répertoire racine de votre projet Astro. Pour pouvoir accéder aux bindings localement, l’adaptateur @astrojs/cloudflare lira également le fichier wrangler.toml.

name = "example"

# Exemple d'une liaison KV
kv_namespaces = [
    { binding = "KV", id = "KV", preview_id = "KV" },
]

# Exemple de liaison var (variables d'environnement)
[vars]
URL = "example.com"

# Exemple d'une liaison D1
[[d1_databases]]
binding = "D1"
database_name = "D1"
database_id = "D1"
preview_database_id = "D1"

# Exemple d'une liaison R2
[[r2_buckets]]
binding = 'R2'
bucket_name = 'R2'

#Exemple de liaison avec Durable Object Binding
[[durable_objects.bindings]]
name = "DO"
class_name = "DO"

Si vous avez besoin de définir des secrets en plus des variables d’environnement, vous devez ajouter un fichier .dev.vars à la racine du projet Astro :

DB_PASSWORD=myPassword

Utilisation

Vous pouvez accéder au runtime à partir des composants Astro via Astro.locals à l’intérieur de n’importe quel fichier .astro.

---
const runtime = Astro.locals.runtime;
---

<pre>{JSON.stringify(runtime.env)}</pre>

Vous pouvez accéder à l’exécution à partir des points d’extrémité de l’API par l’intermédiaire de context.locals :

export function GET(context) {
  const runtime = context.locals.runtime;

  return new Response('Some body');
}

Typing

Si vous avez configuré mode : advanced, vous pouvez taper l’objet runtime en utilisant AdvancedRuntime :

/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

type Runtime = import('@astrojs/cloudflare').AdvancedRuntime<ENV>;

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}

Si vous avez configuré mode : directory, vous pouvez taper l’objet runtime en utilisant DirectoryRuntime :

/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

type Runtime = import('@astrojs/cloudflare').DirectoryRuntime<ENV>;

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}

Plate-forme

Headers

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.

Assets

Les assets construits par Astro sont tous nommés avec un hash et peuvent donc se voir attribuer de longs en-têtes de cache. Par défaut, Astro sur Cloudflare ajoutera un en-tête de ce type pour ces fichiers.

Redirects

Vous pouvez déclarer des redirections personnalisées en utilisant les pages Cloudflare. Cela vous permet de rediriger les requêtes vers une URL différente. Vous pouvez ajouter un fichier _redirects dans le dossier public/ de votre projet Astro. Ce fichier sera copié dans le répertoire de sortie de votre build.

Routes

Vous pouvez définir quelles routes invoquent des fonctions et lesquelles sont des actifs statiques, en utilisant Cloudflare routing via un fichier _routes.json. Ce fichier est généré automatiquement par Astro.

`_routes.json` personnalisé

Par défaut, @astrojs/cloudflare va générer un fichier _routes.json avec des règles include et exclude basées sur les routes dynamiques et statiques de vos applications. Cela permettra à Cloudflare de servir des fichiers et de traiter des redirections statiques sans invocation de fonction. La création d’un _routes.json personnalisé annulera cette optimisation automatique. Voir la documentation de Cloudflare sur la création d’un routes.json personnalisé pour plus de détails.

Utilisation des modules Wasm

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.

import mod from '../util/add.wasm?module';

// instanciation à l'avance pour partager le module
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.

Compatibilité Node.js

L’adaptateur Cloudflare d’Astro vous permet d’utiliser n’importe quelle API d’exécution Node.js prise en charge par Cloudflare :

assert
AsyncLocalStorage
Buffer
Crypto
Diagnostics Channel
EventEmitter
path
process
Streams
StringDecoder
util

Pour utiliser ces API, votre page ou votre point d’accès doit être rendu côté serveur (et non pré-rendu) et doit utiliser la syntaxe d’importation import {} from 'node:*'.

export const prerender = false;
import { Buffer } from 'node:buffer';

En outre, vous devez activer le drapeau de compatibilité dans Cloudflare. La configuration de ce drapeau peut varier en fonction de l’endroit où vous déployez votre site Astro. Pour des conseils détaillés, veuillez consulter la documentation Cloudflare sur l’activation de la compatibilité Node.js.

Support des modules Cloudflare

Tous les paquets Cloudflare (par exemple cloudflare:sockets) sont autorisés à être utilisés. Notez que le paquet cloudflare:sockets ne fonctionne pas localement sans utiliser le mode dev de Wrangler.

Aperçu avec Wrangler

Pour utiliser wrangler afin d’exécuter votre application localement, mettez à jour le script de prévisualisation :

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

wrangler vous donne accès à Cloudflare bindings, environment variables, et à l’objet cf. Faire fonctionner le rechargement à chaud (Hot Reloading) ou le serveur de développement Astro avec Wrangler peut nécessiter une configuration personnalisée. Voir exemples de la communauté.

Messages d’erreur significatifs

Actuellement, les erreurs lors de l’exécution de votre application dans Wrangler ne sont pas très utiles, en raison de la minification de votre code. Pour un meilleur débogage, vous pouvez ajouter le paramètre vite.build.minify = false à votre astro.config.mjs.

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