コンテンツにスキップ

@astrojs/ cloudflare

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

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

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

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

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

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

ターミナルウィンドウ
npx astro add cloudflare

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

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

ターミナルウィンドウ
npm install @astrojs/cloudflare

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

astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare(),
});

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

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

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

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

データ型: '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'
}),
})

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

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

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

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

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

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

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

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

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

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

以下の設定は、開発サーバー実行時に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'
},
},
}),
});

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

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

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

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

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

データ型: { 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 のページ検索は、ビルド時に静的に生成
}
},
}),
});

データ型: 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ランタイムは、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.runtimeenvオブジェクトから環境変数やシークレットにアクセスできます。

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を実行する必要があります。

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

src/env.d.ts
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
declare namespace App {
interface Locals extends Runtime {
otherLocals: {
test: string;
};
}
}

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

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

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

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

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

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

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

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

public/.assetsignore
_worker.js
_routes.json

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オプションを設定することで、別の名前を選択することもできます。

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

    ターミナルウィンドウ
    npx wrangler kv namespace create "SESSION"
  2. Wrangler の設定で KV 名前空間を宣言し、名前空間 ID を前のコマンドで返されたものに設定する。

    wrangler.json
    {
    "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の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を伴わない計算集約型の処理を高速化するのに使用できます。

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ドキュメントを参照してください。

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

package.json
"preview": "wrangler dev ./dist"

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

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

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

他のインテグレーション

UIフレームワーク

SSRアダプター

その他

貢献する コミュニティ Sponsor