389 API D0567127

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

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

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