@astrojs/ cloudflare
この Astroインテグレーション を使うことで、Cloudflareのサーバーアイランド (EN)やactions (EN)、セッション (EN)などの機能を含む、オンデマンドレンダリング (EN)を有効にできます。
Astroを静的サイトジェネレーターとして使用している場合、このアダプターは必要ありません。
Astroサイトのデプロイ方法については、Cloudflareデプロイガイドをご覧ください。
Astro Cloudflareを選ぶ理由
セクションタイトル: Astro Cloudflareを選ぶ理由Cloudflareの開発者プラットフォームを使うと、ストレージやAIなどのリソースにアクセスできるフルスタックアプリケーションを簡単に開発できます。開発したアプリは、そのままグローバルエッジネットワークへデプロイできます。
インストール
セクションタイトル: インストールAstroには、公式インテグレーションを自動でセットアップするastro add
コマンドが用意されています。これを使わない場合は、手動インストールもできます。
astro add
コマンドでCloudflareアダプターを追加して、Astroプロジェクトでサーバサイドレンダリングを有効にします。これにより、@astrojs/cloudflare
がインストールされ、astro.config.mjs
ファイルに適切な変更が1ステップで行われます。
npx astro add cloudflare
pnpm astro add cloudflare
yarn astro add cloudflare
これで、ページごとのオンデマンドレンダリング (EN)を有効にしたり、あるいはビルド設定でoutput: 'server'
を指定することで、全てのページでサーバサイドレンダリングを有効にする (EN)ことができるようになります。
手動インストール
セクションタイトル: 手動インストールまず、お好みのパッケージマネージャーを使用して、プロジェクトの依存関係に@astrojs/cloudflare
アダプターを追加します。
npm install @astrojs/cloudflare
pnpm add @astrojs/cloudflare
yarn add @astrojs/cloudflare
次に、astro.config.mjs
ファイルにアダプターを追加します。
import { defineConfig } from 'astro/config';import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ adapter: cloudflare(),});
オプション
セクションタイトル: オプションCloudflareアダプターは、次のオプションをサポートしています。
cloudflareModules
セクションタイトル: cloudflareModulesデータ型: true | false
デフォルト値: true
’.wasm’、‘.bin’、および ‘.txt’ モジュールのインポート を有効にします。
この機能はデフォルトで有効になっています。無効にする場合は、cloudflareModules: false
を設定します。
imageService
セクションタイトル: imageServiceデータ型: 'passthrough' | 'cloudflare' | 'compile' | 'custom'
デフォルト: 'compile'
アダプターが使用する画像サービスを決定します。アダプターは、互換性のない画像サービスが構成されている場合、compile
モードをデフォルトとして使用します。それ以外の場合は、グローバルに構成された画像サービスを使用します。
cloudflare
: Cloudflare Image Resizingサービスを使用します。passthrough
: 既存の ‘noop’ サービスを使用します。compile
: Astroのデフォルトサービス(sharp)を使用しますが、ビルド時に事前にレンダリングされたルートでのみ使用されます。オンデマンドレンダリングされるページ中では、すべてのastro:assets
機能が無効になります。custom
: Image Optionsで設定したイメージサービスを常に使用します。 このオプションでは、設定された画像サービスがCloudflareのworkerd
ランタイムで動作するかどうかは確認されません。
import { defineConfig } from "astro/config";import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ adapter: cloudflare({ imageService: 'cloudflare' }),})
platformProxy
セクションタイトル: platformProxyCloudflareランタイムをastro dev
に追加するかどうか、またどのように追加するかを指定します。これはローカルのworkerdバインディングへのプロキシとCloudflare固有の値のエミュレーションを含んでおり、Node.jsの開発プロセスでランタイムをエミュレートすることができます。Cloudflare Runtimeの詳細については、こちらをご覧ください。
このプロキシは本番環境の最適なエミュレーションを提供するためのものです。できるだけ実際の環境に近づけるよう設計されていますが、若干の差異や不一致が存在する可能性があります。
platformProxy.enabled
セクションタイトル: platformProxy.enabledデータ型: { enabled?: boolean }
デフォルト値: { enabled: false }
有効にするとastro dev
でCloudflareランタイムを有効にできます。
platformProxy.configPath
セクションタイトル: platformProxy.configPathデータ型: { configPath?: string }
デフォルト値: { configPath: 'wrangler.toml' }
Astroプロジェクトのルートを基準にして、Wrangler設定ファイルを定義できます。
platformProxy.environment
セクションタイトル: platformProxy.environmentデータ型: { environment?: string }
デフォルト値: { environment: undefined }
Wrangler設定のどの環境設定を使用するかを定義できます。
platformProxy.persist
セクションタイトル: 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
セクションタイトル: routes.extendCloudflareのWorkersでは、このオプションは適用されません。詳細についてはCloudflare Workersでのルーティングをご覧ください。
CloudflareのPagesでは、このオプションを使用して、オンデマンドで生成されるルートを決定する_routes.json
ファイルにカスタムパターン(例:/fonts/*
)を追加したり除外したりできます。これは、自動的に生成できないルートパターンを追加する場合や、事前レンダリングされたルートを除外する場合に便利です。
カスタムルートパターンの詳細については、Cloudflareのルーティングドキュメントをご覧ください。指定されたルートは自動的に重複排除されず、既存のルートにそのまま追加されます。
routes.extend.include
セクションタイトル: routes.extend.includeデータ型: { pattern: string }[]
デフォルト値: undefined
Cloudflareアダプターでオンデマンド生成される追加ルートをroutes.extend.include
配列で設定できます。
routes.extend.exclude
セクションタイトル: routes.extend.excludeデータ型: { pattern: string }[]
デフォルト値: undefined
routes.extend.exclude
配列に定義したルートは、オンデマンドレンダリングから除外されます。これらのルートは事前レンダリングされて静的に提供され、サーバ関数を呼び出しません。また、このオプションを使用して静的アセット(画像、フォント、CSS、JS、HTML、TXT、JSONなど)をサーバー関数を経由せずに直接提供することもできます。
export default defineConfig({ adapter: cloudflare({ routes: { extend: { include: [{ pattern: '/static' }], // 静的ページをオンデマンドレンダリング用のサーバー関数にルーティング exclude: [{ pattern: '/pagefind/*' }], // Starlight のページ検索は、ビルド時に静的に生成 } }, }),});
sessionKVBindingName
セクションタイトル: sessionKVBindingNameデータ型: string
デフォルト値: SESSION
astro@5.6.0
sessionKVBindingName
オプションを使用すると、セッションストレージに使用するKVバインディングの名前を指定できます。デフォルトでは SESSION
に設定されていますが、独自のKVバインディング名に変更することができます。詳細についてはセッションをご覧ください。
export default defineConfig({ adapter: cloudflare({ sessionKVBindingName: 'MY_SESSION_BINDING', }),});
Cloudflareランタイム
セクションタイトル: Cloudflareランタイム使用方法
セクションタイトル: 使用方法Cloudflareランタイムでは、環境変数やCloudflareリソースへのバインディングにアクセスできます。
Cloudflareランタイムは、wrangler.toml
/wrangler.json
設定ファイルに定義されたバインディングを使用します。
バインディングには Astro.locals.runtime からアクセスできます。
---const { env } = Astro.locals.runtime;---
API エンドポイントからは、context.locals
を介してアクセスできます。
export function GET(context) { const runtime = context.locals.runtime;
return new Response('Some body');}
サポートされている全てのバインディングについては、Cloudflareのドキュメントにあるバインディング一覧をご覧ください。
環境変数とシークレット
セクションタイトル: 環境変数とシークレットCloudflareランタイムでは、環境変数はバインディングの一種として扱われます。
たとえば、以下のように環境変数をwrangler.json
に定義できます。
{ "vars" : { "MY_VARIABLE": "test" }}
シークレットは、暗号化されたテキスト値をWorkers
に渡すための特殊な環境変数です。値があとから表示されないよう、通常の環境変数とは別の手順で定義します。
secrets
を定義するには、設定ファイルではなく、Wrangler CLIを使用します。
npx wrangler secret put <KEY>
ローカル開発用にシークレットを設定したい場合、.dev.vars
ファイルをプロジェクトのルートに追加する必要があります。
DB_PASSWORD=myPassword
これで、Astro.locals.runtime
のenv
オブジェクトから環境変数やシークレットにアクセスできます。
---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
を自動的に実行できます。
{ "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
を使用して入力できます。
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
declare namespace App { interface Locals extends Runtime { otherLocals: { test: string; }; }}
Cloudflareプラットフォーム
セクションタイトル: Cloudflareプラットフォームヘッダー
セクションタイトル: ヘッダープロジェクトのpublic/
フォルダに_headers
ファイルを追加することで、レスポンスにカスタムヘッダーを追加できます。このファイルはビルド出力ディレクトリにコピーされます。
Cloudflare WorkersとPagesで利用できます。
アセット
セクションタイトル: アセットAstroによるアセットのビルドはすべてハッシュ付きの名前が付けられているため、長いキャッシュヘッダーを付けることができます。デフォルトでは、CloudflareでのAstroはこれらのファイルにそのようなヘッダーを追加します。
リダイレクト
セクションタイトル: リダイレクトプロジェクトのpublic/
フォルダに_redirects
ファイルを追加することで、custom redirectsを使用してリクエストを別のURLにリダイレクトできます。このファイルはビルド出力ディレクトリにコピーされます。
この機能はCloudflare WorkersとPagesで利用可能です。
ルーティング
セクションタイトル: ルーティングCloudflare Workersでのルーティング
セクションタイトル: Cloudflare Workersでのルーティング静的アセットのルーティングは、ビルドディレクトリ(例:./dist
)のファイル構造に基づいています。マッチが見つからない場合、オンデマンドレンダリングのためにWorkerにフォールバックします。より詳しい情報はCloudflare Workersの静的アセットのルーティングもご覧ください。
Cloudflare Pagesとは異なり、Workersでは_routes.json
ファイルは必要ありません。
現在、Cloudflareアダプターは常にこのファイルを生成します。これを回避するには、public/
フォルダに.assetsignore
ファイルを作成し、以下の行を追加してください。
_worker.js_routes.json
Cloudflare Pagesでのルーティング
セクションタイトル: Cloudflare PagesでのルーティングCloudflare Pagesでは、ルーティングに_routes.json
ファイルを使用して、どのリクエストがサーバー関数にルーティングされ、どのリクエストが静的アセットとして提供されるかを決定します。デフォルトでは、プロジェクトのファイルと設定に基づいて_routes.json
ファイルが自動的に生成されます。
アダプターの設定で追加のルーティングパターンを指定したり、独自のカスタム_routes.json
ファイルを作成して自動生成を完全に上書きしたりすることもできます。
カスタムpublic/_routes.json
を作成すると、自動生成が上書きされます。詳細についてはカスタム_routes.json
ファイル作成に関するCloudflareのドキュメントをご覧ください。
セッション
セクションタイトル: セッションAstroのセッションAPI (EN)を使用すると、リクエスト間でユーザーデータを簡単に保存できます。これはユーザーデータや設定、ショッピングカート、認証情報などの保存に使用できます。Cookieストレージとは異なり、データサイズに制限がなく、異なるデバイスでも復元できます。
Astroは、Cloudflareアダプターを使用する際に、セッションストレージ用のWorkers KVを自動的に設定します。セッションを使用する前に、データを保存するためのKVネームスペースを作成し、Wrangler設定ファイルでKVバインディングを構成する必要があります。デフォルトでは、AstroはKVバインディングがSESSION
という名前であることを想定していますが、アダプター設定のsessionKVBindingName
オプションを設定することで、別の名前を選択することもできます。
-
Wrangler CLI を使用して KV 名前空間を作成し、新しい名前空間の ID をメモする。
ターミナルウィンドウ npx wrangler kv namespace create "SESSION" -
Wrangler の設定で KV 名前空間を宣言し、名前空間 ID を前のコマンドで返されたものに設定する。
wrangler.json {"kv_namespaces": [{"binding": "SESSION","id": "<KV_NAMESPACE_ID>"}]}wrangler.toml kv_namespaces = [{ binding = "SESSION", id = "<KV_NAMESPACE_ID>" }] -
サーバーサイドのコードでセッションを使用する。
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モジュールをインポートして、リクエストの数値パラメータを足し合わせて応答する例です。
// 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との互換性
セクションタイトル: Node.jsとの互換性CloudflareはデフォルトではNode.jsランタイムAPIをサポートしていません。ただし、設定によってNode.jsランタイムAPIのサブセットをサポートすることができます。サポートされているNode.jsランタイムAPIについては、Cloudflareのドキュメントを参照してください。
これらのAPIを使用するには、ページまたはエンドポイントがサーバーサイドレンダリングされる必要があり(事前レンダリングではなく)、import {} from 'node:*'
のインポート構文を使用する必要があります。
export const prerender = false;import { Buffer } from 'node:buffer';
また、Astroの設定でvite
設定を変更して、node:*
インポート構文を許可する必要があります。
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によるプレビューwranglerを使用して、アプリケーションをローカルで実行するには、プレビュースクリプトを更新します。
"preview": "wrangler dev ./dist"
"preview": "wrangler pages dev ./dist"
wrangler
を使用した開発では、Cloudflareバインディング、環境変数、およびcfオブジェクトにアクセスできます。AstroのDEVサーバーのホットリロードをWranglerで動作させるには、カスタムセットアップが必要になる場合があります。詳しくはコミュニティのサンプルをご覧ください。
エラーメッセージの説明
セクションタイトル: エラーメッセージの説明現在、Wranglerでアプリケーションを実行中に発生するエラーは、コードが縮小化されているため、あまり役立ちません。デバッグをしやすくするために、astro.config.mjs
にvite.build.minify = false
設定を追加することができます。
export default defineConfig({ adapter: cloudflare(), vite: { build: { minify: false, }, },});