From d8044ec3a2ea210f82e44c9f9496f113bd98679c Mon Sep 17 00:00:00 2001 From: munahartanto Date: Fri, 6 Nov 2026 16:03:41 +0700 Subject: [PATCH] docs: note that getCloudflareContext() in a page/layout requires dynamic rendering Calling getCloudflareContext() in a page or layout (not a route handler) is only safe when the route renders dynamically. If Next.js can statically prerender the route, next build will try to do so and fail, or the context will reflect build time rather than the incoming request. --- pages/cloudflare/bindings.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/pages/cloudflare/bindings.mdx b/pages/cloudflare/bindings.mdx index 5fd42db..ceb1eb9 100644 --- a/pages/cloudflare/bindings.mdx +++ b/pages/cloudflare/bindings.mdx @@ -35,6 +35,24 @@ export async function GET(request) { + + In a page or layout (as opposed to a route handler), `getCloudflareContext()` can only be used if the route renders dynamically. If Next.js is able to statically prerender the route, `next build` will try to do so and fail (or the context will reflect build time rather than the incoming request). + + Force the route to render dynamically by awaiting one of Next.js's [Dynamic APIs](https://nextjs.org/docs/app/api-reference/functions/headers) before calling `getCloudflareContext()`: + ```js + import { headers } from "next/headers"; + import { getCloudflareContext } from "@opennextjs/cloudflare"; + + export default async function Page() { + await headers(); // forces dynamic rendering + const myKv = getCloudflareContext().env.MY_KV_NAMESPACE; + // ... + } + ``` + + Alternatively, export `export const dynamic = "force-dynamic";` from the page or layout. + + #### How to add bindings to your Worker Add bindings to your Worker by adding them to your [wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/).