Pages Functions

ファイルベースルーティングによるサーバーレス API エンドポイント

概要

Pages Functions は、静的サイトと一緒にデプロイされるサーバーレス関数です。プロジェクトルートの functions/ ディレクトリからファイルベースのルーティングを使用します。

ファイルベースルーティング

ファイルパスが URL に対応します：

functions/api/search.ts      → /api/search
functions/api/users/[id].ts  → /api/users/:id
functions/pj/my-site/api/search.ts → /pj/my-site/api/search

関数のフォーマット

関数は onRequest ハンドラー（またはメソッド固有の onRequestGet、onRequestPost など）をエクスポートします：

interface Env {
  KEYWORD_LOGS: KVNamespace;
}

export const onRequestGet: PagesFunction<Env> = async (context) => {
  const url = new URL(context.request.url);
  const query = url.searchParams.get("q");

  // KV バインディングへのアクセス
  const logs = context.env.KEYWORD_LOGS;

  return new Response(JSON.stringify({ results: [] }), {
    headers: { "Content-Type": "application/json" },
  });
};

バインディング

Pages Functions は wrangler.toml で定義されたバインディングを通じて Cloudflare サービスにアクセスします：

compatibility_date = "2024-12-01"

[[kv_namespaces]]
binding = "KEYWORD_LOGS"
id = "abc123def456"

TypeScript コードの Env インターフェースはバインディング名と一致させる必要があります：

interface Env {
  KEYWORD_LOGS: KVNamespace;   // wrangler.toml のバインディング名と一致
  DB: D1Database;              // D1 バインディング
  FILES: R2Bucket;             // R2 バインディング
}

モジュールのインポート

関数は node_modules からインポートできます。ただし、バンドラーの挙動は通常の Node.js とは異なります：

// 動作する -- npm パッケージのインポート
import MiniSearch from 'minisearch';

// 動作する -- JSON のインポート（型安全のため @ts-expect-error を使用）
// @ts-expect-error JSON import bundled by esbuild
import searchData from './search-data.json';

pnpm add -w minisearch  # 依存関係を追加
pnpm dlx wrangler@4 pages deploy deploy --project-name=my-site

ローカル開発

ローカルで関数をテストするには：

npx wrangler pages dev dist --port 8788

これにより、静的ファイルと関数の両方を配信するローカルサーバーが起動します。