@astrojs/ cloudflare

この Astroインテグレーション を使うことで、Cloudflareのサーバーアイランドやactions、セッションなどの機能を含む、オンデマンドレンダリングを有効にできます。

Astroを静的サイトジェネレーターとして使用している場合、このアダプターは必要ありません。

Astroサイトのデプロイ方法については、Cloudflareデプロイガイドをご覧ください。

Astro Cloudflareを選ぶ理由

Cloudflareの開発者プラットフォームを使うと、ストレージやAIなどのリソースにアクセスできるフルスタックアプリケーションを簡単に開発できます。開発したアプリは、そのままグローバルエッジネットワークへデプロイできます。

インストール

Astroには、公式インテグレーションを自動でセットアップするastro addコマンドが用意されています。これを使わない場合は、手動インストールもできます。

astro addコマンドでCloudflareアダプターを追加して、Astroプロジェクトでサーバサイドレンダリングを有効にします。これにより、@astrojs/cloudflareがインストールされ、astro.config.mjsファイルに適切な変更が1ステップで行われます。

npm

npx astro add cloudflare

pnpm

pnpm astro add cloudflare

Yarn

yarn astro add cloudflare

これで、ページごとのオンデマンドレンダリングを有効にしたり、あるいはビルド設定でoutput: 'server'を指定することで、全てのページでサーバサイドレンダリングを有効にすることができるようになります。

手動インストール

まず、お好みのパッケージマネージャーを使用して、プロジェクトの依存関係に@astrojs/cloudflareアダプターを追加します。

npm

npm install @astrojs/cloudflare

pnpm

pnpm add @astrojs/cloudflare

Yarn

yarn add @astrojs/cloudflare

次に、astro.config.mjsファイルにアダプターを追加します。

astro.config.mjs

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

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

オプション

Cloudflareアダプターは、次のオプションをサポートしています。

cloudflareModules

データ型: true | false
デフォルト値: true

‘.wasm’、‘.bin’、および ‘.txt’ モジュールのインポート を有効にします。

この機能はデフォルトで有効になっています。無効にする場合は、cloudflareModules: falseを設定します。

imageService

データ型: 'passthrough' | 'cloudflare' | 'compile' | 'custom'
デフォルト: 'compile'

アダプターが使用する画像サービスを決定します。アダプターは、互換性のない画像サービスが構成されている場合、compileモードをデフォルトとして使用します。それ以外の場合は、グローバルに構成された画像サービスを使用します。

• cloudflare: Cloudflare Image Resizingサービスを使用します。
• passthrough: 既存の ‘noop’ サービスを使用します。
• compile: Astroのデフォルトサービス(sharp)を使用しますが、ビルド時に事前にレンダリングされたルートでのみ使用されます。オンデマンドレンダリングされるページ中では、すべてのastro:assets機能が無効になります。
• custom: Image Optionsで設定したイメージサービスを常に使用します。 このオプションでは、設定された画像サービスがCloudflareのworkerdランタイムで動作するかどうかは確認されません。

astro.config.mjs

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

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

platformProxy

Cloudflareランタイムをastro devに追加するかどうか、またどのように追加するかを指定します。これはローカルのworkerdバインディングへのプロキシとCloudflare固有の値のエミュレーションを含んでおり、Node.jsの開発プロセスでランタイムをエミュレートすることができます。Cloudflare Runtimeの詳細については、こちらをご覧ください。

ノート

このプロキシは本番環境の最適なエミュレーションを提供するためのものです。できるだけ実際の環境に近づけるよう設計されていますが、若干の差異や不一致が存在する可能性があります。

platformProxy.enabled

データ型: { enabled?: boolean }
デフォルト値: { enabled: false }

有効にするとastro devでCloudflareランタイムを有効にできます。

platformProxy.configPath

データ型: { configPath?: string }
デフォルト値: { configPath: 'wrangler.toml' }

Astroプロジェクトのルートを基準にして、Wrangler設定ファイルを定義できます。

platformProxy.environment

データ型: { environment?: string }
デフォルト値: { environment: undefined }

Wrangler設定のどの環境設定を使用するかを定義できます。

platformProxy.persist

データ型: { persist?: boolean | { path: string } }
デフォルト値: { persist: true }

persistプロパティは、バインディングデータを永続化するかどうか、およびその保存先を定義します。

trueに設定すると、Wranglerと同じ場所にデータが保存され、両者間でデータを共有できます。 falseの場合、データはファイルシステムに永続化されず、読み込みも行われません。 指定したパスにバインディングデータを保存したい場合は{ path: string }を使用します。

ノート

wranglerの--persist-toオプションは内部的にv3というサブディレクトリを追加しますが、@astrojs/cloudflareのpersistプロパティはそれを行いません。例えば、wrangler dev --persist-to ./my-directoryと同じ場所を再利用するには、persist: { path: "./my-directory/v3" }と指定する必要があります。

以下の設定は、開発サーバー実行時にCloudflareランタイムを有効にする例と、wrangler.json設定ファイルを使用する例を示しています。また、ファイルシステムにデータを永続化するためのカスタムの場所も指定しています。

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

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

routes.extend

CloudflareのWorkersでは、このオプションは適用されません。詳細についてはCloudflare Workersでのルーティングをご覧ください。

CloudflareのPagesでは、このオプションを使用して、オンデマンドで生成されるルートを決定する_routes.jsonファイルにカスタムパターン（例：/fonts/*）を追加したり除外したりできます。これは、自動的に生成できないルートパターンを追加する場合や、事前レンダリングされたルートを除外する場合に便利です。

カスタムルートパターンの詳細については、Cloudflareのルーティングドキュメントをご覧ください。指定されたルートは自動的に重複排除されず、既存のルートにそのまま追加されます。

routes.extend.include

データ型: { pattern: string }[]
デフォルト値: undefined

Cloudflareアダプターでオンデマンド生成される追加ルートをroutes.extend.include配列で設定できます。

routes.extend.exclude

データ型: { pattern: string }[]
デフォルト値: undefined

routes.extend.exclude配列に定義したルートは、オンデマンドレンダリングから除外されます。これらのルートは事前レンダリングされて静的に提供され、サーバ関数を呼び出しません。また、このオプションを使用して静的アセット（画像、フォント、CSS、JS、HTML、TXT、JSONなど）をサーバー関数を経由せずに直接提供することもできます。

astro.config.mjs

export default defineConfig({
  adapter: cloudflare({
    routes: {
      extend: {
        include: [{ pattern: '/static' }], // 静的ページをオンデマンドレンダリング用のサーバー関数にルーティング
        exclude: [{ pattern: '/pagefind/*' }], // Starlight のページ検索は、ビルド時に静的に生成
      }
    },
  }),
});

sessionKVBindingName

データ型: string
デフォルト値: SESSION

追加： astro@5.6.0

sessionKVBindingName オプションを使用すると、セッションストレージに使用するKVバインディングの名前を指定できます。デフォルトでは SESSION に設定されていますが、独自のKVバインディング名に変更することができます。詳細についてはセッションをご覧ください。

astro.config.mjs

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

Cloudflareランタイム

使用方法

Cloudflareランタイムでは、環境変数やCloudflareリソースへのバインディングにアクセスできます。 Cloudflareランタイムは、wrangler.toml/wrangler.json設定ファイルに定義されたバインディングを使用します。

バインディングにはAstro.locals.runtimeからアクセスできます。

src/pages/index.astro

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

APIエンドポイントからは、context.localsを介してアクセスできます。

src/pages/api/someFile.js

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

  return new Response('Some body');
}

サポートされている全てのバインディングについては、Cloudflareのドキュメントにあるバインディング一覧をご覧ください。

環境変数とシークレット

Cloudflareランタイムでは、環境変数はバインディングの一種として扱われます。

たとえば、以下のように環境変数をwrangler.jsonに定義できます。

wrangler.json

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

シークレットは、暗号化されたテキスト値をWorkersに渡すための特殊な環境変数です。値があとから表示されないよう、通常の環境変数とは別の手順で定義します。

secretsを定義するには、設定ファイルではなく、Wrangler CLIを使用します。

npx wrangler secret put <KEY>

ローカル開発用にシークレットを設定したい場合、.dev.varsファイルをプロジェクトのルートに追加する必要があります。

.dev.vars

DB_PASSWORD=myPassword

これで、Astro.locals.runtimeのenvオブジェクトから環境変数やシークレットにアクセスできます。

src/pages/index.astro

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

Cloudflareの環境変数とシークレットはastro:env APIと互換性があります。

型

wranglerはバインディングに使用するTypeScriptの型を生成するためのtypesコマンドを提供します。これにより、手動で型を指定することなくlocalsオブジェクトを型付けできます。詳細については、Cloudflareのドキュメントを参照してください。

毎回、設定ファイル（例：wrangler.toml、.dev.vars）を変更するたびに、wrangler typesを実行する必要があります。

ノート

pnpmスクリプトを作成して、他のコマンドの前にwrangler typesを自動的に実行できます。

package.json

{
  "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"
  }
}

runtimeオブジェクトにはRuntimeを使用して入力できます。

src/env.d.ts

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

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

Cloudflareプラットフォーム

ヘッダー

プロジェクトのpublic/フォルダに_headersファイルを追加することで、レスポンスにカスタムヘッダーを追加できます。このファイルはビルド出力ディレクトリにコピーされます。

Cloudflare WorkersとPagesで利用できます。

アセット

Astroによるアセットのビルドはすべてハッシュ付きの名前が付けられているため、長いキャッシュヘッダーを付けることができます。デフォルトでは、CloudflareでのAstroはこれらのファイルにそのようなヘッダーを追加します。

リダイレクト

プロジェクトのpublic/フォルダに_redirectsファイルを追加することで、custom redirectsを使用してリクエストを別のURLにリダイレクトできます。このファイルはビルド出力ディレクトリにコピーされます。

この機能はCloudflare WorkersとPagesで利用可能です。

ルーティング

Cloudflare Workersでのルーティング

静的アセットのルーティングは、ビルドディレクトリ（例：./dist）のファイル構造に基づいています。マッチが見つからない場合、オンデマンドレンダリングのためにWorkerにフォールバックします。より詳しい情報はCloudflare Workersの静的アセットのルーティングもご覧ください。

Cloudflare Pagesとは異なり、Workersでは_routes.jsonファイルは必要ありません。

現在、Cloudflareアダプターは常にこのファイルを生成します。これを回避するには、public/フォルダに.assetsignoreファイルを作成し、以下の行を追加してください。

public/.assetsignore

_worker.js
_routes.json

Cloudflare Pagesでのルーティング

Cloudflare Pagesでは、ルーティングに_routes.jsonファイルを使用して、どのリクエストがサーバー関数にルーティングされ、どのリクエストが静的アセットとして提供されるかを決定します。デフォルトでは、プロジェクトのファイルと設定に基づいて_routes.jsonファイルが自動的に生成されます。

アダプターの設定で追加のルーティングパターンを指定したり、独自のカスタム_routes.jsonファイルを作成して自動生成を完全に上書きしたりすることもできます。

カスタムpublic/_routes.jsonを作成すると、自動生成が上書きされます。詳細についてはカスタム_routes.jsonファイル作成に関するCloudflareのドキュメントをご覧ください。

セッション

AstroのセッションAPIを使用すると、リクエスト間でユーザーデータを簡単に保存できます。これはユーザーデータや設定、ショッピングカート、認証情報などの保存に使用できます。Cookieストレージとは異なり、データサイズに制限がなく、異なるデバイスでも復元できます。

Astroは、Cloudflareアダプターを使用する際に、セッションストレージ用のWorkers KVを自動的に設定します。セッションを使用する前に、データを保存するためのKVネームスペースを作成し、Wrangler設定ファイルでKVバインディングを構成する必要があります。デフォルトでは、AstroはKVバインディングがSESSIONという名前であることを想定していますが、アダプター設定のsessionKVBindingNameオプションを設定することで、別の名前を選択することもできます。

1. Wrangler CLIを使用してKV名前空間を作成し、新しい名前空間のIDをメモする。

   npx wrangler kv namespace create "SESSION"

2. Wranglerの設定でKV名前空間を宣言し、名前空間IDを前のコマンドで返されたものに設定する。

   wrangler.json

   wrangler.json

   {
     "kv_namespaces": [
       {
         "binding": "SESSION",
         "id": "<KV_NAMESPACE_ID>"
       }
     ]
   }

   wrangler.toml

   wrangler.toml

   kv_namespaces = [
     { binding = "SESSION", id = "<KV_NAMESPACE_ID>" }
   ]

3. サーバーサイドのコードでセッションを使用する。

   src/components/CartButton.astro

   ---
   export const prerender = false;
   const cart = await Astro.session?.get('cart');
   ---
   
   <a href="/checkout">🛒 {cart?.length ?? 0} items</a>

ノート

Cloudflare KVへの書き込みは、リージョン間で結果整合性を持っています。つまり、変更は同じリージョン内ですぐに利用可能になりますが、グローバルに伝播するには最大60秒かかる場合があります。これはほとんどのユーザーには影響しませんが、VPNユーザーなど、リクエスト間でリージョンを切り替える可能性がある場合には考慮すべき点かもしれません。

モジュールのインポート

Cloudflareのworkerdランタイムは、一部の非標準モジュールタイプのインポートをサポートしています。ほとんどの追加ファイルタイプはAstroでも利用できます。

• .wasm / .wasm?module: WebAssembly.Moduleをエクスポートし、インスタンス化。
• .bin: ファイルの生のバイナリ内容のArrayBufferをエクスポート。
• .txt: ファイル内容の文字列をエクスポート。

すべてのモジュールタイプはデフォルト値を1つエクスポートします。モジュールは、サーバーサイドレンダリングのページからでも、静的サイト生成用の事前レンダリングのページからでもインポートできます。

以下は、Wasmモジュールをインポートして、リクエストの数値パラメータを足し合わせて応答する例です。

pages/add/[a]/[b].js

// WebAssembly モジュールのインポート
import mod from '../util/add.wasm';

// 最初にインスタンス化しておく
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)}`);
}

これは単純な例ですが、Wasmは、画像処理ライブラリの埋め込みや、読み取り専用データセットの検索用にインデックス付けされた小さなデータベースの埋め込みなど、大きなI/Oを伴わない計算集約型の処理を高速化するのに使用できます。

Node.jsとの互換性

CloudflareはデフォルトではNode.jsランタイムAPIをサポートしていません。ただし、設定によってNode.jsランタイムAPIのサブセットをサポートすることができます。サポートされているNode.jsランタイムAPIについては、Cloudflareのドキュメントを参照してください。

これらのAPIを使用するには、ページまたはエンドポイントがサーバーサイドレンダリングされる必要があり（事前レンダリングではなく）、import {} from 'node:*'のインポート構文を使用する必要があります。

pages/api/endpoint.js

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

また、Astroの設定でvite設定を変更して、node:*インポート構文を許可する必要があります。

astro.config.mjs

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

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

また、サポートを有効にするには、Cloudflareのドキュメントに従う必要があります。詳細については、Node.js互換性を有効にするためのCloudflareドキュメントを参照してください。

パッケージの互換性への影響

プロジェクトがNode.jsランタイムAPIを使用するパッケージをサーバーにインポートすると、Cloudflareへのデプロイ時に問題が発生する可能性があります。この問題は、node:*インポート構文を使用していないパッケージで発生します。パッケージの作者に連絡して、上記のインポート構文をサポートしているかどうかを確認することをお勧めします。パッケージがこれをサポートしていない場合は、別のパッケージを使用する必要があるかもしれません。

Wranglerによるプレビュー

wranglerを使用して、アプリケーションをローカルで実行するには、プレビュースクリプトを更新します。

Worker

package.json

"preview": "wrangler dev ./dist"

Pages

package.json

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

wranglerを使用した開発では、Cloudflareバインディング、環境変数、およびcfオブジェクトにアクセスできます。AstroのDEVサーバーのホットリロードをWranglerで動作させるには、カスタムセットアップが必要になる場合があります。詳しくはコミュニティのサンプルをご覧ください。

エラーメッセージの説明

現在、Wranglerでアプリケーションを実行中に発生するエラーは、コードが縮小化されているため、あまり役立ちません。デバッグをしやすくするために、astro.config.mjsにvite.build.minify = false設定を追加することができます。

astro.config.mjs

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

他のインテグレーション

UIフレームワーク

• 

  @astrojs/alpinejs

• 

  @astrojs/react

• 

  @astrojs/preact

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSRアダプター

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

その他

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap