Worker Feature Template

Worker Feature Template

Use this when adding a new capability inside a worker app.

Canonical shape

workers/{name}/src/
  index.ts
  features/
    {domain}/
      process-{domain}.ts
      types.ts
      process-{domain}.test.ts
  infra/
    db/
    http/
    telemetry/
  shared/
    types.ts

Responsibilities

• index.ts: runtime dispatch only
• features/{domain}/: application logic and orchestration
• infra/: Cloudflare runtime bindings, D1, KV, queues, DOs, external clients
• shared/: narrow worker-safe types and pure helpers

Starter example

// workers/{name}/src/index.ts
import process{Domain} from "./features/{domain}/process-{domain}";

export default {
  async queue(batch: MessageBatch<unknown>, env: Env): Promise<void> {
    await process{Domain}(batch, env);
  },
} satisfies ExportedHandler<Env>;

// workers/{name}/src/features/{domain}/process-{domain}.ts
import { read{Domain}State } from "../../infra/db";

export default async function process{Domain}(
  batch: MessageBatch<unknown>,
  env: Env,
): Promise<void> {
  await read{Domain}State(env, batch.messages.length);
}

Rules

• do not access env.DB_*, env.KV_*, or other bindings from feature files
• do not place business logic inline in index.ts
• do not move pure shared worker logic into infra/ if it has no runtime dependency
• follow documented worker exceptions instead of copying legacy monoliths