Changelog

New updates and improvements at Cloudflare. Subscribe to RSS

← Back to all posts

Import `env` to access bindings in your Worker's global scope

Mar 17, 2025, 03:00 PM

Workers

You can now access bindings from anywhere in your Worker by importing the env object from cloudflare:workers.

Previously, env could only be accessed during a request. This meant that bindings could not be used in the top-level context of a Worker.

Now, you can import env and access bindings such as secrets or environment variables in the initial setup for your Worker:

import { env } from "cloudflare:workers";
import ApiClient from "example-api-client";

// API_KEY and LOG_LEVEL now usable in top-level scope
const apiClient = ApiClient.new({ apiKey: env.API_KEY });
const LOG_LEVEL = env.LOG_LEVEL || "info";

export default {
  fetch(req) {
    // you can use apiClient or LOG_LEVEL, configured before any request is handled
  },
};

Note

Workers do not allow I/O from outside a request context. This means that even though env is accessible from the top-level scope, you will not be able to access every binding's methods.

For instance, environment variables and secrets are accessible, and you are able to call env.NAMESPACE.get to get a Durable Object stub in the top-level context. However, calling methods on the Durable Object stub, making calls to a KV store, and calling to other Workers will not work.

Additionally, env was normally accessed as a argument to a Worker's entrypoint handler, such as fetch. This meant that if you needed to access a binding from a deeply nested function, you had to pass env as an argument through many functions to get it to the right spot. This could be cumbersome in complex codebases.

Now, you can access the bindings from anywhere in your codebase without passing env as an argument:

// helpers.js
import { env } from "cloudflare:workers";

// env is *not* an argument to this function
export async function getValue(key) {
  let prefix = env.KV_PREFIX;
  return await env.KV.get(`${prefix}-${key}`);
}

For more information, see documentation on accessing env.