claude-skills/cloudflare/references/bindings/api.md

Bindings API Reference

TypeScript Types

Cloudflare generates binding types via npx wrangler types. This creates .wrangler/types/runtime.d.ts with your Env interface.

Generated Env Interface

After running wrangler types, TypeScript knows your bindings:

interface Env {
  // From wrangler.jsonc bindings
  MY_KV: KVNamespace;
  MY_BUCKET: R2Bucket;
  DB: D1Database;
  MY_SERVICE: Fetcher;
  AI: Ai;
  
  // From vars
  API_URL: string;
  
  // From secrets (set via wrangler secret put)
  API_KEY: string;
}

Binding Types

Config	TypeScript Type	Package
kv_namespaces	KVNamespace	@cloudflare/workers-types
r2_buckets	R2Bucket	@cloudflare/workers-types
d1_databases	D1Database	@cloudflare/workers-types
durable_objects.bindings	DurableObjectNamespace	@cloudflare/workers-types
vectorize	VectorizeIndex	@cloudflare/workers-types
queues.producers	Queue	@cloudflare/workers-types
services	Fetcher	@cloudflare/workers-types
ai	Ai	@cloudflare/workers-types
browser	Fetcher	@cloudflare/workers-types
analytics_engine_datasets	AnalyticsEngineDataset	@cloudflare/workers-types
hyperdrive	Hyperdrive	@cloudflare/workers-types
rate_limiting	RateLimit	@cloudflare/workers-types
workflows	Workflow	@cloudflare/workers-types
mtls_certificates / vars / text_blobs / data_blobs	string	Built-in
wasm_modules	WebAssembly.Module	Built-in

Accessing Bindings

Method 1: fetch() Handler (Recommended)

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const value = await env.MY_KV.get('key');
    return new Response(value);
  }
}

Why: Type-safe, aligns with Workers API, supports ctx for waitUntil/passThroughOnException.

Method 2: Hono Framework

import { Hono } from 'hono';

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

app.get('/', async (c) => {
  const value = await c.env.MY_KV.get('key');
  return c.json({ value });
});

export default app;

Why: c.env auto-typed, ergonomic for routing-heavy apps.

Method 3: Module Workers (Legacy)

export async function handleRequest(request: Request, env: Env): Promise<Response> {
  const value = await env.MY_KV.get('key');
  return new Response(value);
}

addEventListener('fetch', (event) => {
  // env not directly available - requires workarounds
});

Avoid: Use fetch() handler instead (Method 1).

Type Generation Workflow

Initial Setup

# Install wrangler
npm install -D wrangler

# Generate types from wrangler.jsonc
npx wrangler types

After Changing Bindings

# Added/modified binding in wrangler.jsonc
npx wrangler types

# TypeScript now sees updated Env interface

Note: wrangler types outputs to .wrangler/types/runtime.d.ts. TypeScript picks this up automatically if @cloudflare/workers-types is in tsconfig.json "types" array.

Key Binding Methods

KV:

await env.MY_KV.get(key, { type: 'json' });  // text|json|arrayBuffer|stream
await env.MY_KV.put(key, value, { expirationTtl: 3600 });
await env.MY_KV.delete(key);
await env.MY_KV.list({ prefix: 'user:' });

R2:

await env.BUCKET.get(key);
await env.BUCKET.put(key, value);
await env.BUCKET.delete(key);
await env.BUCKET.list({ prefix: 'images/' });

D1:

await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
await env.DB.batch([stmt1, stmt2]);

Service:

await env.MY_SERVICE.fetch(new Request('https://fake/path'));

Workers AI:

await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' });

Queues:

await env.MY_QUEUE.send({ userId: 123, action: 'process' });

Durable Objects:

const id = env.MY_DO.idFromName('user-123');
const stub = env.MY_DO.get(id);
await stub.fetch(new Request('https://fake/increment'));

Runtime vs Build-Time Types

Type Source	When Generated	Use Case
@cloudflare/workers-types	npm install	Base Workers APIs (Request, Response, etc.)
wrangler types	After config change	Your specific bindings (Env interface)

Install both:

npm install -D @cloudflare/workers-types
npx wrangler types

Type Safety Best Practices

1. Never use any for env:

// ❌ BAD
async fetch(request: Request, env: any) { }

// ✅ GOOD
async fetch(request: Request, env: Env) { }

2. Run wrangler types after config changes:

# After editing wrangler.jsonc
npx wrangler types

3. Check generated types match config:

# View generated Env interface
cat .wrangler/types/runtime.d.ts

See Also

• Workers Types Package
• Wrangler Types Command