Bindings API Reference

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