Bindings (env) · Cloudflare Workers docs

contenido

Bindings allow your Worker to interact with resources on the Cloudflare Developer Platform.

The following bindings available today:

  • AI: Run generative AI inference and machine learning models on GPUs, without managing servers or infrastructure.
  • Analytics Engine: Write high-cardinality data and metrics at scale, directly from Workers.
  • Browser Rendering: Programmatically control and interact with a headless browser instance.
  • D1: APIs available in Cloudflare Workers to interact with D1. D1 is Cloudflare’s native serverless database.
  • Dispatcher (Workers for Platforms): Let your customers deploy their own code to your platform, and dynamically dispatch requests from your Worker to their Worker.
  • Durable Objects: A globally distributed coordination API with strongly consistent storage.
  • Environment Variables: Add string and JSON values to your Worker.
  • Hyperdrive: Connect to your existing database from Workers, turning your existing regional database into a globally distributed database.
  • KV: Global, low-latency, key-value data storage.
  • mTLS: Configure your Worker to present a client certificate to services that enforce an mTLS connection.
  • Queues: Send and receive messages with guaranteed delivery.
  • R2: APIs available in Cloudflare Workers to read from and write to R2 buckets. R2 is S3-compatible, zero egress-fee, globally distributed object storage.
  • Rate Limiting: Define rate limits and interact with them directly from your Cloudflare Worker
  • Secrets: Add encrypted secrets to your Worker.
  • Service bindings: Facilitate Worker-to-Worker communication.
  • Vectorize: APIs available in Cloudflare Workers to interact with Vectorize. Vectorize is Cloudflare’s globally distributed vector database.
  • Version metadata: Exposes Worker version metadata (versionID and versionTag). These fields can be added to events emitted from the Worker to send to downstream observability systems.

What is a binding?

When you declare a binding on your Worker, you grant it a specific capability, such as being able to read and write files to an R2 bucket. For example:

wrangler.toml { binding = "MY_BUCKET", bucket_name = "<MY_BUCKET_NAME>" }

index.js async fetch(request, env) { const key = url.pathname.slice(1); await env.MY_BUCKET.put(key, request.body); return new Response(`Put ${key} successfully!`);

You can think of a binding as a permission and an API in one piece. With bindings, you never have to add secret keys or tokens to your Worker in order to access resources on your Cloudflare account — the permission is embedded within the API itself. The underlying secret is never exposed to your Worker’s code, and therefore can’t be accidentally leaked.

Making changes to bindings

When you deploy a change to your Worker, and only change its bindings (i.e. you don’t change the Worker’s code), Cloudflare may reuse existing isolates that are already running your Worker. This improves performance — you can change an environment variable or other binding without unnecessarily reloading your code.

As a result, you must be careful when “polluting” global scope with derivatives of your bindings. Anything you create there might continue to exist despite making changes to any underlying bindings. Consider an external client instance which uses a secret API key accessed from env: if you put this client instance in global scope and then make changes to the secret, a client instance using the original value might continue to exist. The correct approach would be to create a new client instance for each request.

The following is a good approach:

 let client = new Client(env.MY_SECRET); 

Compared to this alternative, which might have surprising and unwanted behavior:

 client ??= new Client(env.MY_SECRET); 

If you have more advanced needs, explore the AsyncLocalStorage API, which provides a mechanism for exposing values down to child execution handlers.

Resumir
Bindings on Cloudflare Worker allow interaction with resources on the Cloudflare Developer Platform, offering capabilities like AI inference, analytics, browser rendering, database access, durable objects, environment variables, global data storage, mTLS configuration, message queues, rate limiting, secrets, service bindings, and more. Bindings grant specific permissions without exposing secret keys, improving security. When deploying changes to bindings without altering code, existing isolates may be reused for better performance. Care must be taken not to 'pollute' global scope with binding derivatives, as changes may not affect existing instances. It's recommended to create new instances for each request to avoid unexpected behavior. The AsyncLocalStorage API can be explored for more advanced needs in handling values across execution handlers.