メインコンテンツまでスキップ

Cloudflare Workersではじめる

このガイドでは、Cloudflare Workers上でZeltアプリケーションをゼロから構築する方法を説明します。

前提条件​

インストール​

pnpm add @zeltjs/core @zeltjs/adapter-cloudflare-workers
pnpm add -D wrangler @cloudflare/workers-types

プロジェクト構成​

my-worker/
├── src/
│   ├── app.ts
│   ├── index.ts
│   └── controllers/
│       └── hello.controller.ts
├── package.json
├── tsconfig.json
└── wrangler.toml

Hello World​

ステップ1: コントローラーの作成​

コントローラーは受信HTTPリクエストを処理し、レスポンスを返します。各コントローラーは@Controllerでデコレートされたクラスで、ルートプレフィックスを定義します。

src/controllers/hello.controller.tsを作成:

import { Controller, Get, pathParam } from '@zeltjs/core';

@Controller('/hello')
export class HelloController {
  @Get('/:name')
  greet(name = pathParam('name')) {
    return { message: `Hello, ${name}!` };
  }
}
  • @Controller('/hello') — このコントローラー内のすべてのルートのベースパスを設定
  • @Get('/:name') — /hello/:nameへのGETリクエストを処理
  • pathParam('name') — URLパスからnameパラメータを抽出

ステップ2: アプリケーションの作成​

src/app.tsを作成してコントローラーを接続:

import { createHttpApp } from '@zeltjs/core';
import { HelloController } from './controllers/hello.controller';

export const app = createHttpApp({
  controllers: [HelloController],
});

ステップ3: Workerエントリーポイントの作成​

Cloudflare Workersのエントリーポイントsrc/index.tsを作成:

import { onCloudflareWorkers } from '@zeltjs/adapter-cloudflare-workers';
import { app } from './app';

export default onCloudflareWorkers(app);

onCloudflareWorkers()関数は、アプリをWorkersランタイム用にラップします。デフォルトでは遅延初期化を使用します — コントローラーは起動時ではなく最初のリクエスト時に解決されます。これにより、サーバーレス環境でのコールドスタート時間が最適化されます。

ステップ4: Wranglerの設定​

wrangler.tomlを作成:

name = "my-zelt-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]

[vars]
API_HOST = "https://api.example.com"

ステップ5: TypeScriptの設定​

tsconfig.jsonを作成:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "experimentalDecorators": true,
    "skipLibCheck": true,
    "types": ["@cloudflare/workers-types"]
  },
  "include": ["src"]
}

ステップ6: ローカルで実行​

npx wrangler dev

http://localhost:8787/hello/worldにアクセスすると:

{ "message": "Hello, world!" }

設定​

環境変数​

Cloudflare Workersでは、環境変数はwrangler.tomlで設定し、EnvService経由でアクセスします。

import { Controller, Get, inject, EnvService } from '@zeltjs/core';

@Controller('/config')
export class ConfigController {
  constructor(private env = inject(EnvService)) {}

  @Get('/api-host')
  getApiHost() {
    return { apiHost: this.env.get('API_HOST') ?? 'localhost' };
  }
}

アプリにEnvConfigを登録:

import { createHttpApp, EnvConfig } from '@zeltjs/core';

export const app = createHttpApp({
  controllers: [ConfigController],
  configs: [EnvConfig],
});

重要: EnvConfigを登録してonCloudflareWorkers()を使用すると、アダプターが自動的にCloudflareWorkersEnvConfigに置換します。これにより、process.envではなくWorkersランタイム（cloudflare:workersモジュール）から環境変数を読み取ります。

シークレット​

機密性の高い値には、[vars]の代わりにWranglerシークレットを使用:

npx wrangler secret put DATABASE_URL

EnvService経由で同じ方法でアクセスできます:

const dbUrl = this.env.get('DATABASE_URL');

サービス​

サービスはNode.jsと同じように動作します。@Injectableを使用してクラスをサービスとしてマークします。

import { Injectable } from '@zeltjs/core';

@Injectable()
export class GreetingService {
  greet(name: string): string {
    return `Hello, ${name}!`;
  }
}

コントローラーに注入:

import { Controller, Get, pathParam, inject } from '@zeltjs/core';
import { GreetingService } from '../services/greeting.service';

@Controller('/hello')
export class HelloController {
  constructor(private greetingService = inject(GreetingService)) {}

  @Get('/:name')
  greet(name = pathParam('name')) {
    return { message: this.greetingService.greet(name) };
  }
}

デプロイ​

Cloudflareのグローバルネットワークにワーカーをデプロイ:

npx wrangler deploy

ワーカーはhttps://my-zelt-worker.<your-subdomain>.workers.devで利用可能になります。

上級: Warmupオプション​

デフォルトでは、onCloudflareWorkers()は遅延初期化（warmup: false）を使用してコールドスタート時間を最小化します。コントローラーは最初のリクエスト時に解決されます。

すべてのコントローラーを初期化時に解決したい場合（デバッグや、コールドスタート時間があまり重要でない場合に便利）、warmup: trueを設定:

export default onCloudflareWorkers(app, { warmup: true });
オプション動作ユースケース
warmup: false（デフォルト）最初のリクエスト時にコントローラーを解決コールドスタートの最適化
warmup: true初期化時にすべてのコントローラーを解決デバッグ、ウォーム環境

次のステップ​

基本的なワーカーが動作するようになったら、さらに多くの機能を探索しましょう: