Bindings

Bindings (opens in a new tab) allow your Worker to interact with resources on the Cloudflare Developer Platform. 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 (opens in a new tab) bucket.

How to configure your Next.js app so it can access bindings

Install @opennextjs/cloudflare (opens in a new tab), and then add a wrangler configuration file (opens in a new tab) in the root directory of your Next.js app, as described in Get Started.

How to access bindings in your Next.js app

You can access bindings (opens in a new tab) from any route of your Next.js app via getCloudflareContext:

import { getCloudflareContext } from "@opennextjs/cloudflare";
 
export async function GET(request) {
  const myKv = getCloudflareContext().env.MY_KV_NAMESPACE;
  await myKv.put("foo", "bar");
  const foo = await myKv.get("foo");
 
  return new Response(foo);
}

getCloudflareContext can only be used in SSG routes in "async mode" (making it return a promise), to run the function in such a way simply provide an options argument with async set to true:

const context = await getCloudflareContext({ async: true });

WARNING: During SSG caution is advised since secrets (stored in .dev.vars files) and local development values from bindings (like values saved in a local KV) will be used for the pages static generation.

How to add bindings to your Worker

Add bindings to your Worker by adding them to your wrangler configuration file (opens in a new tab).

TypeScript type declarations for bindings

To ensure that the env object from getCloudflareContext().env above has accurate TypeScript types, run the following Wrangler command to generate types that match your Worker's configuration (opens in a new tab):

npx wrangler types --env-interface CloudflareEnv

This will generate a d.ts file and save it to worker-configuration.d.ts.

To ensure that your types are always up-to-date, make sure to run wrangler types --env-interface CloudflareEnv after any changes to your config file.

Local access to bindings

As presented in the getting started your application can be both developed (next dev) and previewed (opennextjs-cloudflare preview) locally, in both cases bindings will be accessible from your application's code.

Such bindings are by default local simulation that mimic the behavior of the actual Cloudflare resources.

Remote bindings

As mentioned above, by default local emulations of the bindings are used.

However remote bindings (opens in a new tab) can also be used, allowing your application code, while still running locally, to connect to remote resources associated to your Cloudflare account.

Remote bindings are currently experimental and can be enabled it in your next.config.ts file:

- initOpenNextCloudflareForDev();
+ initOpenNextCloudflareForDev({
+  experimental: { remoteBindings: true }
+ });

When the feature is turned on all you then need to do to enable remote mode for any of your bindings is to set the experimental_remote configuration field to true, exactly as documented in the remote bindings documentation (opens in a new tab).

💡

Note that remote bindings will also be used during build, this can be very useful for example when using features such ISR (opens in a new tab) so that read production data can be used for the site's static generation

Other Cloudflare APIs (`cf`, `ctx`)

You can access context about the incoming request from the cf object (opens in a new tab), as well as lifecycle methods from the ctx object (opens in a new tab) from the return value of getCloudflareContext() (opens in a new tab):

import { getCloudflareContext } from "@opennextjs/cloudflare";
 
export async function GET(request) {
  const { env, cf, ctx } = getCloudflareContext();
 
  // ...
}