workers-frameworks

Workers フレームワークの統合

最新のフレームワークを使用して、Cloudflare Workers 上にフルスタックアプリケーションを構築します。

クイックスタート：フレームワークを選択

フレームワーク	最適な用途	SSR	静的	Workers ネイティブ
Hono	API、軽量アプリ	✅	✅	✅ ネイティブ
Remix	フルスタックアプリ	✅	✅	✅ アダプター
Next.js	React アプリ	✅	✅	⚠️ OpenNext
Astro	コンテンツサイト	✅	✅	✅ アダプター
SvelteKit	Svelte アプリ	✅	✅	✅ アダプター
Qwik	再開可能なアプリ	✅	✅	✅ アダプター
Nuxt	Vue アプリ	✅	✅	✅ Nitro

フレームワーク選択ツリー

Need an API only?
  └─ Yes → Hono (fastest, smallest)
  └─ No → Building a full app?
           └─ React → Next.js (OpenNext) or Remix
           └─ Vue → Nuxt
           └─ Svelte → SvelteKit
           └─ Content-heavy → Astro
           └─ Max performance → Qwik

フレームワークでよくあるエラー 10 選

エラー	フレームワーク	原因	解決策
No matching export "default"	すべて	エクスポート形式の誤り	module.exports ではなく export default app を使用します
Worker exceeded CPU limit	Next.js	SSR の負荷が高い	ISR を使用し、バンドルサイズを小さくします
Cannot read properties of undefined (reading 'env')	Remix	コンテキストが不足	context を loader/action に渡します
globalThis is not defined	すべて	Node.js のグローバル変数	nodejs_compat フラグを使用します
Dynamic require not supported	すべて	ESM 内の CJS	ESM の import に変換します
Response body is locked	すべて	本文がすでに読み込まれている	読み込む前にレスポンスを複製します
Bindings not available	すべて	wrangler の設定が不足	wrangler.jsonc にバインディングを追加します
404 on static assets	すべて	assets の設定が誤っている	wrangler.jsonc で assets を設定します
Hydration mismatch	React/Vue	サーバーとクライアントの差異	一貫性のあるレンダリングを確保します
Maximum call stack exceeded	すべて	循環インポート	モジュール構成を再設計します

Hono クイックスタート（推奨）

// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';

interface Env {
  DB: D1Database;
  KV: KVNamespace;
}

const app = new Hono<{ Bindings: Env }>();

// Middleware
app.use('*', logger());
app.use('/api/*', cors());

// Routes
app.get('/', (c) => c.text('Hello Workers!'));

app.get('/api/users', async (c) => {
  const { results } = await c.env.DB.prepare('SELECT * FROM users').all();
  return c.json(results);
});

app.post('/api/users', async (c) => {
  const { name, email } = await c.req.json();
  await c.env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
    .bind(name, email)
    .run();
  return c.json({ success: true }, 201);
});

export default app;

// wrangler.jsonc
{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-01",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "xxx" }
  ]
}

静的アセットの設定

// wrangler.jsonc - Serving static files
{
  "name": "my-app",
  "main": "src/index.ts",
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  }
}

// Serve static with fallback to app
import { Hono } from 'hono';

const app = new Hono<{ Bindings: { ASSETS: Fetcher } }>();

// API routes
app.get('/api/*', apiHandler);

// Static assets fallback
app.get('*', async (c) => {
  return c.env.ASSETS.fetch(c.req.raw);
});

export default app;

リファレンスを読み込むタイミング

ユーザーが次の操作を行う場合は、該当するフレームワークのリファレンスを読み込みます。

リファレンス	読み込むタイミング
references/hono.md	API、マイクロサービス、または軽量アプリを構築する場合
references/remix.md	loader/action を使用したフルスタック React を構築する場合
references/nextjs.md	OpenNext を介して Workers 上で Next.js App Router を使用する場合
references/astro.md	コンテンツサイト、ブログ、ドキュメント、マーケティングページを構築する場合
references/sveltekit.md	Workers 上で Svelte アプリケーションを構築する場合
references/qwik.md	再開可能なアプリや即時読み込みを実現する場合
references/nuxt.md	Nitro を使用した Vue 3 アプリケーションを構築する場合

フレームワーク共通のパターン

環境バインディングへのアクセス

// Hono
app.get('/', (c) => c.env.DB.prepare('...'));

// Remix
export async function loader({ context }) {
  return context.cloudflare.env.DB.prepare('...');
}

// Astro
const db = Astro.locals.runtime.env.DB;

// SvelteKit
export async function load({ platform }) {
  return platform.env.DB.prepare('...');
}

// Nuxt
const { cloudflare } = useRuntimeConfig();
// Or via nitro: event.context.cloudflare.env.DB

エラーハンドリングのパターン

// Universal error boundary pattern
app.onError((err, c) => {
  console.error(`[${c.req.path}] ${err.message}`);

  if (err instanceof HTTPException) {
    return err.getResponse();
  }

  return c.json(
    { error: 'Internal Server Error' },
    500
  );
});

パフォーマンスのヒント

1. バンドルサイズ：圧縮後 1MB 未満に抑えます
2. コールドスタート：トップレベルのコードを最小限にします
3. ストリーミング：利用可能な場合はストリーミング SSR を使用します
4. キャッシュ：Cache API と CDN を活用します
5. コード分割：ルートには動的インポートを使用します

関連項目

• workers-performance - 最適化の手法
• workers-runtime-apis - Workers API のリファレンス
• cloudflare-worker-base - Workers の基本設定