env
@rtorcato/cf-common/env reads bindings and vars off the env argument
Cloudflare passes to your handlers. A missing value fails loudly, with a clear
message, instead of turning up later as undefined is not a function.
import { getBinding, getEnv, requireEnv } from '@rtorcato/cf-common/env'
Bindings
const sessions = getBinding<KVNamespace>(env, 'SESSIONS')
const bucket = getBinding<R2Bucket>(env, 'UPLOADS')
const db = getBinding<D1Database>(env, 'DB')
getBinding works for any binding: KV, R2, D1, queues, services or Durable
Objects. The type parameter names what you expect, so the rest of your code is
typed against it.
If the binding is missing, getBinding throws a non-exposed 500
CloudflareError. That is a deploy mistake, such as a binding left out of
wrangler.jsonc, not something the client did. The client sees
Internal error, and your logs show Missing Cloudflare binding: SESSIONS.
Required vars and secrets
const apiKey = requireEnv(env, 'STRIPE_KEY')
requireEnv returns the string or throws a non-exposed 500 when the var is
unset or empty. Use it for secrets the Worker can't run without.
Optional vars
const region = getEnv(env, 'REGION', 'us') // 'us' when unset
const label = getEnv(env, 'BUILD_LABEL') // string | undefined
getEnv never throws. An empty string counts as unset, so it returns the
fallback.
Typing env
The helpers take an Env, which is Record<string, unknown>. If you declare
your own interface for defineFetch<Env>, give it an index signature so it
fits:
interface Env {
[key: string]: unknown
SESSIONS: KVNamespace
STRIPE_KEY: string
}
Locally
Under wrangler dev, vars come from .dev.vars, and KV, R2 and D1 bindings
are simulated, so you don't need a Cloudflare account. A binding you forgot to
declare fails the same way it would in production.
See the env API reference.