@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

imageService

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

Détermine quel service d’image est utilisé par l’adaptateur. L’adaptateur utilisera par défaut le mode compile 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.
custom: Utilise toujours le service d’image configuré dans Image Options. **Cette option ne vérifie pas si le service d’image configuré fonctionne dans le moteur d’exécution workerd de Cloudflare.

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

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

platformProxy

Détermine la façon dont le runtime Cloudflare est ajouté à astro dev. Il contient des proxies vers les bindings locaux workerd et des émulations de valeurs spécifiques à Cloudflare, permettant l’émulation du runtime dans le processus de développement Node.js. En savoir plus sur le Cloudflare Runtime.

platformProxy.enabled

Type : { enabled?: boolean }
Par défaut : { enabled: false }

La propriété enabled vous permet d’activer le runtime Cloudflare dans astro dev.

platformProxy.configPath

Type : { configPath?: string }
Par défaut : { configPath: 'wrangler.toml' }

Le configPath vous permet de définir votre fichier de configuration Wrangler, relatif à la racine de votre projet Astro.

platformProxy.experimentalJsonConfig

Type : { experimentalJsonConfig?: boolean }
Par défaut : { experimentalJsonConfig?: false }

La propriété experimentalJsonConfig définit si l’utilitaire lit un fichier de configuration JSON (par exemple wrangler.json).

platformProxy.persist

Type : { persist?: boolean | { path: string } }
Par défaut : { persist: true }

La propriété persist définit si et où les données des bindings sont persistantes. Par défaut, true est le même emplacement que celui utilisé par Wrangler afin que les données puissent être partagées entre les deux. Si false, aucune donnée n’est persistée ou lue depuis le système de fichiers.

La configuration suivante montre un exemple d’activation du runtime Cloudflare lors de l’exécution du serveur de développement, ainsi que l’utilisation d’un fichier de configuration wrangler.json (expérimental). Elle spécifie également un emplacement personnalisé pour la persistance des données dans le système de fichiers :

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

export default defineConfig({
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
      configPath: 'wrangler.json',
      experimentalJsonConfig: true,
      persist: './.cache/wrangler/v3',
    },
  }),
});

routes.extend

Cette option vous permet d’ajouter ou d’exclure des motifs personnalisés (par exemple /fonts/*) au fichier _routes.json généré qui détermine quelles routes sont générées à la demande. Cela peut être utile si vous avez besoin d’ajouter des modèles de route qui ne peuvent pas être générés automatiquement, ou d’exclure des routes pré-rendues.

Vous trouverez plus d’informations sur les modèles de routes personnalisées dans la documentation de routing de Cloudflare. Les routes spécifiées ne sont pas automatiquement dédupliquées et seront ajoutées telles quelles aux routes existantes.

routes.extend.include

Type : { pattern: string }[]
Par défaut : undefined

Configurez des routes supplémentaires qui seront générées à la demande par l’adaptateur Cloudflare dans le tableau routes.extend.include.

routes.extend.exclude

Type : { pattern: string }[]
Par défaut : undefined

Configure les routes à exclure du rendu à la demande dans le tableau routes.extend.exclude. Ces routes seront pré-rendues et servies statiquement à la place, et n’invoqueront pas la fonction SSR. De plus, vous pouvez utiliser cette option pour servir n’importe quel fichier statique (images, polices, css, js, html, txt, json, etc.) directement sans faire passer la requête par la fonction SSR.

export default defineConfig({
  adapter: cloudflare({
    routes: {
      extend: {
        include: [{ pattern: '/static' }], // Achemine une page pré-établie vers la fonction SSR pour l'afficher à la demande
        exclude: [{ pattern: '/pagefind/*' }], // Utilise la recherche pagefind de Starlight, qui est générée statiquement au moment de la construction.
      }
    },
  }),
});

`cloudflareModules`

Type : true | false
Par défaut : true

Active les importations des modules .wasm, .bin, et .txt.

Cette fonctionnalité est activée par défaut. Si vous souhaitez la désactiver, définissez cloudflareModules : false.

Cloudflare runtime

Le moteur d’exécution de Cloudflare vous donne accès aux variables d’environnement et aux liaisons de Cloudflare. Le moteur d’exécution de Cloudflare utilise les liaisons trouvées dans les fichiers de configuration wrangler et .dev.vars.

Utilisation

Par exemple, si vous avez une variable d’environnement configurée dans wrangler.toml :

[vars]
MY_VARIABLE = "test"

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

Vous pouvez accéder aux bindings en utilisant les localisations Astro comme suit :

---
const { env } = Astro.locals.runtime;
---

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('Un corps de réponse');
}

Pour accéder à la valeur de la liaison MY_VARIABLE, ajoutez ce qui suit à votre code :

---
const { env } = Astro.locals.runtime;
const myVariable = env.MY_VARIABLE;
---

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

Typing

wrangler fournit une commande types pour générer des types TypeScript pour les bindings. Cela vous permet de taper des éléments locaux sans avoir besoin de les taper manuellement. Référez-vous à la documentation de Cloudflare pour plus d’informations.

Chaque fois que vous modifiez vos fichiers de configuration (par exemple wrangler.toml, .dev.vars), vous devez lancer wrangler types.

Vous pouvez créer un script pnpm pour lancer wrangler types automatiquement avant d’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"
  }
}

Vous pouvez taper l’objet runtime en utilisant Runtime :

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

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

declare namespace App {
  interface Locals extends Runtime {
    otherLocals: {
      test: string;
    };
  }
}

Plate-forme Cloudflare

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

Routage de Cloudflare utilise un fichier _routes.json pour déterminer quelles requêtes sont routées vers la fonction SSR et lesquelles sont servies en tant qu’actifs statiques. Par défaut, un fichier _routes.json sera automatiquement généré pour votre projet en fonction de ses fichiers et de sa configuration.

Vous pouvez spécifier des modèles de routage supplémentaires à suivre dans la configuration de votre adaptateur, ou créer votre propre fichier _routes.json personnalisé pour ignorer complètement la génération automatique.

`_routes.json` personnalisé

La création d’un public/_routes.json personnalisé annulera la génération automatique. Voir la documentation de Cloudflare sur la création d’un _routes.json personnalisé pour plus de détails.

Importations de modules Cloudflare

Le moteur d’exécution cloudflare worker 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 affichées 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 ne prend pas en charge les API d’exécution Node.js. Avec un peu de configuration, Cloudflare prend en charge un sous-ensemble des API d’exécution Node.js. Vous pouvez trouver les API d’exécution Node.js prises en charge dans la documentation de Cloudflare.

Pour utiliser ces API, votre page ou votre point d’accès doit être affiché 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';

Vous devrez également modifier la configuration vite dans votre astro config pour autoriser la syntaxe d’importation node:* :

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

export default defineConfig({
  adapter: cloudflare({}),
  output: 'server',
  vite: {
    ssr: {
      external: ['node:buffer'],
    },
  },
})

En plus de cela, vous devrez suivre la documentation de Cloudflare sur la façon d’activer le support. Pour des conseils détaillés, veuillez vous référer à la documentation Cloudflare sur l’activation de la compatibilité Node.js.

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 aux liaisons Cloudflare, aux variables d’environnement, et à l’objet cf. Faire fonctionner le rechargement à chaud (Hot Reloading) du serveur de développement d’Astro avec Wrangler peut nécessiter une configuration personnalisée. Voir les 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,
    },
  },
});