better-cf

Type-safe Cloudflare Queue SDK + CLI.

better-cf removes queue binding boilerplate by scanning defineQueue exports, generating .better-cf/entry.ts, and patching Wrangler queue config.

Why better-cf

Cloudflare Queues are great, but setup usually repeats:

• Manual queue binding names.
• Manual wrangler.toml or wrangler.jsonc queue blocks.
• Manual worker queue consumer plumbing.

better-cf keeps queue code in plain functions and auto-generates runtime wiring.

Install

npm i better-cf zod
npm i -D wrangler @cloudflare/workers-types typescript

Quickstart

npx better-cf init

Create queue:

import { z } from 'zod';
import { defineQueue } from './better-cf.config';

export const signupQueue = defineQueue({
  message: z.object({ email: z.string().email(), userId: z.string() }),
  process: async (ctx, msg) => {
    await fetch('https://example.com', {
      method: 'POST',
      body: JSON.stringify(msg)
    });
  },
  retry: 3
});

Run dev:

npm run dev

Deploy:

npm run deploy

Canonical Imports

• Queue SDK: better-cf/queue
• Testing helpers: better-cf/testing

Type Safety Guarantees

createSDK<Env>() propagates Env types into ctx.env for queue and worker handlers.

import { createSDK } from 'better-cf/queue';

type Env = {
  DB: D1Database;
  EMAIL_QUEUE: Queue;
};

export const { defineQueue } = createSDK<Env>();

Payload types are inferred from Zod schemas for send, sendBatch, process, and multi-job queue APIs.

Hono Example

better-cf supports Hono default exports.

import { Hono } from 'hono';

const app = new Hono();
app.get('/', (ctx) => ctx.text('ok'));

export default app;

The generated .better-cf/entry.ts resolves fetch handlers for object/function/named exports.

Legacy Cloudflare Compatibility (Service Worker Adapter)

Set compatibility mode in better-cf.config.ts:

export const betterCfConfig = {
  legacyServiceWorker: true
};

This mode is adapter-only and not feature-parity guaranteed with module worker patterns.

CLI Commands

• better-cf init: scaffold config, worker, scripts.
• better-cf generate: scan + generate .better-cf/* + patch Wrangler config.
• better-cf dev: generate + watch + run wrangler dev (local only for queues).
• better-cf deploy: generate + run wrangler deploy.

Queue Config Mapping

Local Dev Constraints

Cloudflare queue local development does not support wrangler dev --remote for queue consumers. better-cf dev --remote is blocked intentionally.

Testing Queues

Use better-cf/testing:

import { testQueue } from 'better-cf/testing';

const result = await testQueue(queueHandle, {
  env: mockEnv,
  message: { id: '1' }
});

Compatibility Matrix

• Wrangler: >=3.91.0 <5
• Node: >=18.18
• Config formats: wrangler.toml, wrangler.json, wrangler.jsonc
• Runtime styles: module worker (first-class), service-worker adapter (compatibility mode)
• Frameworks: Workers + Hono

Not Supported (v1)

• Pull consumers / HTTP pull consumers.
• Queue create/delete lifecycle outside deploy workflow.
• Queue metrics dashboard/API abstraction.
• Runtime dynamic queue registration.
• Remote queue local-dev parity for unsupported Cloudflare modes.

Known Gaps

• Non-literal config expressions reduce static wrangler extraction quality.
• Legacy adapter mode may not match every service-worker edge case.
• Non-standard worker export patterns beyond documented variants are out of scope.
• Monorepo autodetection is basic; explicit workerEntry may be needed.

Roadmap

Planned future namespaces:

• better-cf/workflow
• better-cf/durable-object