Bindings overview
Bindings are various integrations available to Cloudflare Workers that allow workers to access resources and services. The bindings documentation provides configuration guidance for workers runtime APIs.
Cloudflare Workers · Wrangler · all subjects
bindings
73 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
edge authentication with placed back-end Worker example
Example demonstrates two Workers: 'auth-worker' runs at the edge with no placement to handle authentication quickly, and 'app-worker' is placed near the database to handle data queries. The auth-worker validates authorization headers and calls the placed app-worker via RPC using a Service Binding. The app-worker extends WorkerEntrypoint and has placement configured with region 'aws:us-east-1'. RPC methods on the placed Worker execute near the database for low-latency queries.
AI binding configuration
An AI binding in metadata has type 'ai' and a name field for the variable name. Example: {"type": "ai", "name": "<VARIABLE_NAME>"}
Analytics Engine binding configuration
An Analytics Engine binding in metadata has type 'analytics_engine', a name field for the variable name, and a dataset field for the dataset name. Example: {"type": "analytics_engine", "name": "<VARIABLE_NAME>", "dataset": "<DATASET>"}
Assets binding configuration
An Assets binding in metadata has type 'assets' and a name field for the variable name. Example: {"type": "assets", "name": "<VARIABLE_NAME>"}
Browser Rendering binding configuration
A Browser Rendering binding in metadata has type 'browser_rendering' and a name field for the variable name. Example: {"type": "browser_rendering", "name": "<VARIABLE_NAME>"}
D1 binding configuration
A D1 binding in metadata has type 'd1', a name field for the variable name, and an id field for the D1 database ID. Example: {"type": "d1", "name": "<VARIABLE_NAME>", "id": "<D1_ID>"}
Durable Objects namespace binding configuration
A Durable Objects namespace binding in metadata has type 'durable_object_namespace', a name field for the variable name, and a class_name field for the Durable Object class name. Example: {"type": "durable_object_namespace", "name": "<VARIABLE_NAME>", "class_name": "<DO_CLASS_NAME>"}
Hyperdrive binding configuration
A Hyperdrive binding in metadata has type 'hyperdrive', a name field for the variable name, and an id field for the Hyperdrive ID. Example: {"type": "hyperdrive", "name": "<VARIABLE_NAME>", "id": "<HYPERDRIVE_ID>"}
KV namespace binding configuration
A KV namespace binding in metadata has type 'kv_namespace', a name field for the variable name, and a namespace_id field for the KV namespace ID. Example: {"type": "kv_namespace", "name": "<VARIABLE_NAME>", "namespace_id": "<KV_ID>"}
mTLS Certificate binding configuration
An mTLS Certificate binding in metadata has type 'mtls_certificate', a name field for the variable name, and a certificate_id field for the mTLS certificate ID. Example: {"type": "mtls_certificate", "name": "<VARIABLE_NAME>", "certificate_id": "<MTLS_CERTIFICATE_ID>"}
Plain text binding configuration
A plain text binding in metadata has type 'plain_text', a name field for the variable name, and a text field for the variable value. Example: {"type": "plain_text", "name": "<VARIABLE_NAME>", "text": "<VARIABLE_VALUE>"}
Queue binding configuration
A Queue binding in metadata has type 'queue', a name field for the variable name, and a queue_name field for the queue name. Example: {"type": "queue", "name": "<VARIABLE_NAME>", "queue_name": "<QUEUE_NAME>"}
R2 bucket binding configuration
An R2 bucket binding in metadata has type 'r2_bucket', a name field for the variable name, and a bucket_name field for the R2 bucket name. Example: {"type": "r2_bucket", "name": "<VARIABLE_NAME>", "bucket_name": "<R2_BUCKET_NAME>"}
Secret text binding configuration
A secret text binding in metadata has type 'secret_text', a name field for the variable name, and a text field for the secret value. Example: {"type": "secret_text", "name": "<VARIABLE_NAME>", "text": "<SECRET_VALUE>"}
Service binding configuration
A service binding in metadata has type 'service', a name field for the variable name, a service field for the service name, and an environment field specifying 'production'. Example: {"type": "service", "name": "<VARIABLE_NAME>", "service": "<SERVICE_NAME>", "environment": "production"}
Version metadata binding configuration
A version metadata binding in metadata has type 'version_metadata' and a name field for the variable name. Example: {"type": "version_metadata", "name": "<VARIABLE_NAME>"}
Vectorize binding configuration
A Vectorize binding in metadata has type 'vectorize', a name field for the variable name, and an index_name field for the index name. Example: {"type": "vectorize", "name": "<VARIABLE_NAME>", "index_name": "<INDEX_NAME>"}
Metadata bindings configuration
The bindings array contains binding objects that allow Workers to interact with resources on the Cloudflare Developer Platform. Each binding object has a type field specifying the binding type and a name field for the variable name. The supported binding types are: ai, analytics_engine, assets, browser_rendering, d1, durable_object_namespace, hyperdrive, kv_namespace, mtls_certificate, plain_text, queue, r2_bucket, secret_text, service, vectorize, and version_metadata.
Custom Domain enables same-zone Worker-to-Worker fetch without service bindings
On the same zone, a Worker can communicate with another Worker on a route or workers.dev subdomain only via service bindings. However, if a Worker is attempting to communicate with a target Worker running on a Custom Domain, fetch requests will succeed without requiring a service binding.
Import env from cloudflare:workers for global access
You can import env from 'cloudflare:workers' to access environment variables from anywhere in your code, including outside of request handlers. This is useful for initializing configuration or API clients at the top level of your Worker and for accessing environment variables from deeply nested functions without passing env through every function call.
Environment variables via dashboard: Variables and Secrets section
To add environment variables via the Cloudflare dashboard: go to the Workers & Pages page, select your Worker, select Settings, and under Variables and Secrets, select Add. Select a Type, input a Variable name and Value, then select Deploy. You can add multiple variables by selecting Add variable multiple times.
Secrets are exposed via process.env
Because secrets are a form of environment variable within the runtime, secrets are also exposed via process.env when nodejs_compat and nodejs_compat_populate_process_env are enabled.
Example: Access environment variable in Worker code
Example showing how to access environment variables in Worker code: JavaScript: export default { async fetch(request, env, ctx) { return new Response(`API host: ${env.API_HOST}`); }, }; TypeScript: export interface Env { API_HOST: string; } export default { async fetch(request, env, ctx): Promise<Response> { return new Response(`API host: ${env.API_HOST}`); }, } satisfies ExportedHandler<Env>; Python: from workers import WorkerEntrypoint, Response class Default(WorkerEntrypoint): async def fetch(self, request): return Response(f"API host: {self.env.API_HOST}")
Example: Import env from cloudflare:workers
Example showing how to import env from cloudflare:workers for global access: import { env } from "cloudflare:workers"; // Access environment variables at the top level const apiHost = env.API_HOST; export default { async fetch(request: Request): Promise<Response> { return new Response(`API host: ${apiHost}`); }, };
Access environment variables via env parameter
Environment variables are available on the env parameter passed to your Worker's fetch event handler. They can be accessed directly from the env object, such as env.API_HOST.
Environment variables are a type of binding
Environment variables are a type of binding that attach text strings or JSON values to your Worker. Text strings and JSON values are not encrypted and are useful for storing application configuration.
Example: access DB_CONNECTION_STRING secret via cloudflare:workers import
import { env } from "cloudflare:workers"; import postgres from "postgres"; const sql = postgres(env.DB_CONNECTION_STRING); export default { async fetch(request: Request): Promise<Response> { const result = await sql`SELECT * FROM products;`; return new Response(JSON.stringify(result), { headers: { "Content-Type": "application/json" }, }); }, };
Secrets binding definition and purpose
Secrets are a type of binding that allow you to attach encrypted text values to your Worker. They are used for storing sensitive information like API keys and auth tokens.
Access secrets via env parameter in fetch handler
Secrets can be accessed in your Worker code through the env parameter passed to your Worker's fetch event handler. For example, given a DB_CONNECTION_STRING secret, you can access it as env.DB_CONNECTION_STRING.
Access secrets via cloudflare:workers import
Secrets can be imported from cloudflare:workers using import { env } from 'cloudflare:workers' to access secrets from anywhere in your code, including outside of request handlers.
Access secrets via process.env in Node.js compatibility
Secrets can be accessed through process.env in Workers that have Node.js compatibility enabled.
Example: access DB_CONNECTION_STRING secret from fetch handler
import postgres from "postgres"; export default { async fetch(request, env, ctx) { const sql = postgres(env.DB_CONNECTION_STRING); const result = await sql`SELECT * FROM products;`; return new Response(JSON.stringify(result), { headers: { "Content-Type": "application/json" }, }); }, };
Service Worker pattern for serving static assets (deprecated)
Service Workers are deprecated but still supported. The Service Worker pattern imports getAssetFromKV from @cloudflare/kv-asset-handler and uses addEventListener('fetch') with event.respondWith(handleEvent(event)) to serve assets. An async handleEvent function calls getAssetFromKV(event) and returns a 404 Response if assets are not found.
__STATIC_CONTENT_MANIFEST special import for asset manifest
The __STATIC_CONTENT_MANIFEST is a special import that provides a JSON string containing the manifest of static assets. This manifest must be parsed and passed to getAssetFromKV in the ASSET_MANIFEST option to map asset URLs to their stored locations.
__STATIC_CONTENT_MANIFEST import for asset manifest
In Module Workers, import __STATIC_CONTENT_MANIFEST as a special string and parse it as JSON to create an assetManifest object. This manifest is passed to getAssetFromKV() in the options object as the ASSET_MANIFEST value.
getAssetFromKV function import and usage
The @cloudflare/kv-asset-handler package provides a getAssetFromKV() function that can be imported and used in Worker code to serve static assets. For Module Workers, the function accepts a request object, context.waitUntil binding, and options including ASSET_NAMESPACE (env.__STATIC_CONTENT) and ASSET_MANIFEST (parsed from the __STATIC_CONTENT_MANIFEST). For Service Workers, it can be called with just the fetch event.
Module Worker static asset serving example
Example of serving static assets in a Module Worker: ```js import { getAssetFromKV } from "@cloudflare/kv-asset-handler"; import manifestJSON from "__STATIC_CONTENT_MANIFEST"; const assetManifest = JSON.parse(manifestJSON); export default { async fetch(request, env, ctx) { try { return await getAssetFromKV( { request, waitUntil: ctx.waitUntil.bind(ctx), }, { ASSET_NAMESPACE: env.__STATIC_CONTENT, ASSET_MANIFEST: assetManifest, }, ); } catch (e) { let pathname = new URL(request.url).pathname; return new Response(`"${pathname}" not found`, { status: 404, statusText: "not found", }); } }, }; ```
Service Worker static asset serving example
Example of serving static assets in a Service Worker: ```js import { getAssetFromKV } from "@cloudflare/kv-asset-handler"; addEventListener("fetch", (event) => { event.respondWith(handleEvent(event)); }); async function handleEvent(event) { try { return await getAssetFromKV(event); } catch (e) { let pathname = new URL(event.request.url).pathname; return new Response(`"${pathname}" not found`, { status: 404, statusText: "not found", }); } } ```
Install @cloudflare/kv-asset-handler package
The @cloudflare/kv-asset-handler package must be installed as a development dependency in the project using 'npm i -D @cloudflare/kv-asset-handler' to provide the getAssetFromKV function for serving static assets.
env.__STATIC_CONTENT binding for asset namespace
The env.__STATIC_CONTENT binding provides the asset namespace (KV namespace) where static content is stored and must be passed as ASSET_NAMESPACE option to getAssetFromKV().
mtls_certificates binding configuration
The `mtls_certificates` field in the wrangler.toml configuration file binds an mTLS certificate for use in Worker subrequests. The configuration requires a `binding` (the variable name) and a `certificate_id` (the ID returned from uploading the certificate). Example: `{"mtls_certificates": [{"binding": "MY_CERT", "certificate_id": "99f5fef1-6cc1-46b8-bd79-44a0d5082b8d"}]}`
mTLS certificates for Worker subrequests
mTLS certificates managed via the `mtls-certificate` commands can be used in `mtls_certificate` bindings to allow a Worker to present the certificate when establishing a connection with an origin that requires client authentication (mTLS).
Certificates for Hyperdrive configurations
Certificates managed via the `cert` commands (both mTLS client certificates and CA chain certificates) are primarily used with Hyperdrive configurations. These enable Hyperdrive to present the certificate when connecting to an origin database that requires client authentication (mTLS) or a custom Certificate Authority (CA).
getPlatformProxy supported bindings
getPlatformProxy supports these bindings: environment variables, service bindings, KV namespace bindings, R2 bucket bindings, Queue bindings, D1 database bindings, Hyperdrive bindings (values are passthrough), Workers AI bindings, Durable Object bindings (must always specify script_name in configuration).
getPlatformProxy Durable Object binding configuration
To use a Durable Object binding with getPlatformProxy, always specify a script_name in the configuration. The Durable Object must be declared in another Worker. That external Worker needs its own Wrangler configuration file with name, main, and compatibility_date fields. If using RPC, build the application and run both Workers in the same Wrangler dev session. If using Pages, run: wrangler pages dev -c path/to/pages/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc. If using Workers with Assets, run: wrangler dev -c path/to/workers-assets/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc.
Hyperdrive certificate management
mTLS client certificates and CA chain certificates used by Hyperdrive are managed through Certificate commands, not Hyperdrive commands.
Durable Objects bindings with containers
Durable Objects bindings for containers are declared in the durable_objects.bindings array, with each binding having name (string) and class_name (string) fields.
durable_objects binding configuration
The durable_objects field is an optional non-inheritable object that specifies a list of Durable Objects that the Worker should be bound to. To bind Durable Objects, assign an array to the durable_objects.bindings key. Each binding object contains: name (required string) - The name of the binding used to refer to the Durable Object. class_name (required string) - The exported class name of the Durable Object. script_name (optional string) - The name of the Worker where the Durable Object is defined, if external to this Worker. environment (optional string) - The environment of the script_name to bind to.
exports configuration field for Durable Objects
The exports field declares the Durable Object classes this Worker exports and their lifecycle state. It is mutually exclusive with migrations. Each entry is keyed by Durable Object class name. Fields on each entry: type (required string) - For Durable Object class entries, set to "durable-object". state (optional string) - The lifecycle state. One of "created" (default - a live class), "deleted", "renamed", "transferred", or "expecting-transfer". storage (conditional string) - Required when state is "created" or "expecting-transfer". One of "sqlite" (recommended; required for new namespaces) or "legacy-kv" (only for existing key-value-backed namespaces). renamed_to (conditional string) - Required when state is "renamed". The destination class name, which must also appear as a live entry in the same exports map. transferred_to (conditional string) - Required when state is "transferred". The name of the target Worker that will receive the namespace. transfer_from (conditional string) - Required when state is "expecting-transfer". The name of the source Worker the namespace is being transferred from.
migrations configuration field for Durable Objects (legacy)
The migrations field is the legacy imperative configuration for managing Durable Object class lifecycle. For new Workers, the declarative exports field is preferred. migrations and exports are mutually exclusive. When making changes to Durable Object classes, a migration must be performed. Each migration object contains: tag (required string) - A unique identifier for this migration. new_sqlite_classes (optional string array) - New Durable Object classes being defined with the SQLite storage backend. new_classes (optional string array) - New Durable Object classes being defined with the legacy key-value storage backend. renamed_classes (optional array of {from: string, to: string}) - The Durable Object classes being renamed. deleted_classes (optional string array) - The Durable Object classes being removed. transferred_classes (optional array of {from: string, from_script: string, to: string}) - The Durable Object classes being transferred from another Worker.
kv_namespaces binding configuration
The kv_namespaces field is an optional non-inheritable array that specifies KV namespaces the Worker should be bound to. Each namespace object contains: binding (required string) - The binding name used to refer to the KV namespace. id (required string) - The ID of the KV namespace. preview_id (optional string) - The preview ID of this KV namespace. This option is required when using wrangler dev --remote to develop against remote resources (but is not required with remote bindings). If developing locally, this is optional. wrangler dev will use this ID for the KV namespace. Otherwise, wrangler dev will use id.
r2_buckets binding configuration
The r2_buckets field is an optional non-inheritable array that specifies R2 buckets the Worker should be bound to. Each bucket object contains: binding (required string) - The binding name used to refer to the R2 bucket. bucket_name (required string) - The name of this R2 bucket. jurisdiction (optional string) - The jurisdiction where this R2 bucket is located, if a jurisdiction has been specified. preview_bucket_name (optional string) - The preview name of this R2 bucket. If provided, wrangler dev will use this name for the R2 bucket. Otherwise, it will use bucket_name. This option is required when using wrangler dev --remote.
d1_databases binding configuration
The d1_databases field is an optional array that specifies D1 databases the Worker should be bound to. Each database object is assigned to the [[d1_databases]] key and contains: binding (required string) - The binding name used to refer to the D1 database. Must be a valid JavaScript variable name. database_name (required string) - The name of the database. database_id (required string) - The ID of the database. preview_database_id (optional string) - The preview ID of this D1 database. If provided, wrangler dev uses this ID. Otherwise, it uses database_id. Required when using wrangler dev --remote. migrations_dir (optional string) - The migration directory containing migration files. Default is migrations folder created by wrangler d1 migrations create. migrations_pattern (optional string) - A glob pattern (relative to Wrangler config file) used to discover migration files. Defaults to migrations/*.sql. Use for nested layouts produced by ORMs like Drizzle (e.g., migrations/*/migration.sql). When set, migrations_dir must also be set, and migrations_pattern must start with whatever migrations_dir is set to.
services binding configuration
The services field is an optional non-inheritable array that specifies service bindings the Worker should be bound to. Each service binding object contains: binding (required string) - The binding name used to refer to the bound Worker. service (required string) - The name of the Worker. To bind to a Worker in a specific environment, append the environment name to the Worker name in format <worker-name>-<environment-name>. For example, to bind to a Worker called worker-name in its staging environment, service should be worker-name-staging. entrypoint (optional string) - The name of the entrypoint to bind to. If not specified, the default export of the Worker will be used.
queues binding configuration - producers
The queues.producers field is an optional non-inheritable array that specifies Queue producers. To bind Queues to a producer Worker, assign an array to the [[queues.producers]] key. Each producer object contains: queue (required string) - The name of the queue, used on the Cloudflare dashboard. binding (required string) - The binding name used to refer to the queue. Must be a valid JavaScript variable name. delivery_delay (optional number) - The number of seconds to delay messages sent to a queue for by default. This can be overridden on a per-message or per-batch basis.
queues binding configuration - consumers
The queues.consumers field is an optional non-inheritable array that specifies Queue consumers. To bind Queues to a consumer Worker, assign an array to the [[queues.consumers]] key. Each consumer object contains: queue (required string) - The name of the queue. max_batch_size (optional number) - The maximum number of messages allowed in each batch. max_batch_timeout (optional number) - The maximum number of seconds to wait for messages to fill a batch before sending to the consumer Worker. max_retries (optional number) - The maximum number of retries for a message if it fails or retryAll() is invoked. dead_letter_queue (optional string) - The name of another queue to send a message if it fails processing at least max_retries times. If not defined, failed messages are discarded. If the queue does not exist, it will be created automatically. max_concurrency (optional number) - The maximum number of concurrent consumers allowed to run at once. Leaving unset means invocations will scale to the currently supported maximum. retry_delay (optional number) - The number of seconds to delay retried messages by default, before they are re-delivered to the consumer. Can be overridden on a per-message or per-batch basis.
ai_search_namespaces binding configuration
The ai_search_namespaces field is an optional non-inheritable array that specifies AI Search namespaces the Worker should be bound to. A namespace is a logical grouping of AI Search instances, and the binding grants full access to all instances within the namespace. Each namespace object contains: binding (required string) - The binding name used to refer to the AI Search namespace. namespace (required string) - The name of the AI Search namespace. A default namespace is created automatically for every account. If the namespace does not exist, Wrangler creates it on deploy.
ai_search binding configuration for instances
The ai_search field is an optional non-inheritable array that binds directly to pre-existing AI Search instances in the default namespace. This binding does not support namespace-level operations like list(), create(), or delete(). Each instance object contains: binding (required string) - The binding name used to refer to the AI Search instance. instance_name (required string) - The name of the AI Search instance. Must exist in the default namespace at deploy time.
vectorize binding configuration
The vectorize field is an optional non-inheritable array that specifies Vectorize indexes the Worker should be bound to. Each index object contains: binding (required string) - The binding name used to refer to the bound index. index_name (required string) - The name of the index to bind.