@astrojs/ cloudflare

v12.4.0 GitHub npm Journal des modifications

Cet adaptateur permet à Astro de déployer vos routes rendues à la demande sur Cloudflare.

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

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 construit 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 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 de redimensionnement d’image de Cloudflare.
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 les options d’images. Cette option ne vérifiera 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 si et comment le moteur d’exécution Cloudflare est ajouté à astro dev. Il contient des proxys vers les liaisons workerd locales et des émulations de valeurs spécifiques à Cloudflare, permettant l’émulation du moteur d’exécution dans le processus de développement Node.js. En savoir plus sur le moteur d’exécution de Cloudflare.

platformProxy.enabled

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

La propriété enabled vous permet d’activer le moteur d’exécution de Cloudflare dans astro dev.

platformProxy.configPath

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

La propriété 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 de liaison sont persistantes. true correspond par défaut à l’emplacement utilisé par Wrangler, ce qui permet le partage des données entre les deux. Si false, aucune donnée n’est conservée ni lue sur le système de fichiers.

La configuration suivante montre un exemple d’activation du moteur d’exécution de 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: {
        path: './.cache/wrangler/v3'
      },
    },
  }),
});

routes.extend

Cette option vous permet d’ajouter ou d’exclure des motifs personnalisés (par exemple /fonts/*) au fichier généré _routes.json 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.

Plus d’informations sur les modèles de route personnalisés sont disponibles dans la documentation sur le routage 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é-rendue vers la fonction SSR pour un rendu à 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.

Moteur d’exécution de Cloudflare

Utilisation

Le moteur d’exécution de Cloudflare vous donne accès aux variables d’environnement et aux liaisons aux ressources Cloudflare. Le moteur d’exécution Cloudflare utilise les liaisons trouvées dans le fichier de configuration wrangler.toml/wrangler.json.

Vous pouvez accéder aux liaisons depuis Astro.locals.runtime :

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

Vous pouvez accéder au moteur d’exécution à partir des points de terminaison de l’API via context.locals :

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

  return new Response('Un corps de réponse');
}

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

Variables d’environnement et secrets

Le moteur d’exécution de Cloudflare traite les variables d’environnement comme un type de liaison.

Par exemple, vous pouvez définir une variable d’environnement dans wrangler.json comme suit :

{
  "vars" : {
    "MY_VARIABLE": "test"
  }
}

Les secrets sont un type particulier de variable d’environnement qui vous permet d’attacher des valeurs textuelles chiffrées à votre Worker. Ils doivent être définis différemment pour garantir qu’ils ne soient pas visibles après leur définition.

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

Vous pouvez ensuite accéder aux variables d’environnement, y compris les secrets, à partir de l’objet env disponible depuis Astro.locals.runtime :

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

Les variables d’environnement et les secrets Cloudflare sont compatibles avec l’API astro:env.

Définition de types

wrangler fournit une commande types pour générer des types TypeScript pour les liaisons. Cela vous permet de définir des types pour locals sans avoir à les saisir 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 définir un type pour l’objet runtime en utilisant Runtime :

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

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

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.

Ceci est disponible sur Cloudflare Workers et Pages.

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

Vous pouvez déclarer des redirections personnalisées pour rediriger les requêtes vers une URL différente. Pour ce faire, ajoutez un fichier _redirects dans le dossier public/ de votre projet Astro. Ce fichier sera copié dans votre répertoire de sortie de construction.

Ceci est disponible sur Cloudflare Workers et Pages.

Routes

Routage sur Cloudflare Workers

Le routage des ressources statiques est basé sur la structure des fichiers dans le répertoire de construction (par exemple, ./dist). Si aucune correspondance n’est trouvée, le Worker sera utilisé pour le rendu côté serveur. En savoir plus sur le routage des ressources statiques avec Cloudflare Workers.

Contrairement à Cloudflare Pages, avec Workers, vous n’avez pas besoin d’un fichier _routes.json.

Routage sur Cloudflare Pages

Pour Cloudflare Pages, le routage utilise un fichier _routes.json pour déterminer les requêtes acheminées vers la fonction serveur et celles servies comme ressources 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 remplacer complètement la génération automatique.

La création d’un fichier 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 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 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 point de terminaison 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';

Vous devrez également modifier la configuration vite dans votre configuration Astro 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 :

Pour Workers :

"preview": "wrangler dev ./dist"

Pour Pages :

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

Développer avec 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,
    },
  },
});