opennextjs · vicb · Feb 14, 2025 · Feb 12, 2025 · Feb 12, 2025 · Feb 12, 2025
diff --git a/.changeset/tough-tables-talk.md b/.changeset/tough-tables-talk.md
@@ -0,0 +1,10 @@
+---
+"@opennextjs/cloudflare": patch
+---
+
+add "async mode" to `getCloudflareContext`
+
+Add an `async` option to `getCloudflareContext({async})` to run it in "async mode", the difference being that the returned value is a
+promise of the Cloudflare context instead of the context itself
+
+The main of this is that it allows the function to also run during SSG (since the missing context can be created on demand).
diff --git a/examples/common/apps.ts b/examples/common/apps.ts
@@ -6,6 +6,7 @@ const apps = [
   "middleware",
   "vercel-blog-starter",
   "vercel-commerce",
+  "ssg-app",
   // e2e
   "app-pages-router",
   "app-router",

diff --git a/examples/ssg-app/.dev.vars b/examples/ssg-app/.dev.vars
@@ -0,0 +1 @@
+MY_SECRET = "psst... this is a secret!"
diff --git a/examples/ssg-app/.gitignore b/examples/ssg-app/.gitignore
@@ -0,0 +1,47 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
diff --git a/examples/ssg-app/app/favicon.ico b/examples/ssg-app/app/favicon.ico
diff --git a/examples/ssg-app/app/globals.css b/examples/ssg-app/app/globals.css
@@ -0,0 +1,14 @@
+html,
+body {
+  max-width: 100vw;
+  overflow-x: hidden;
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+footer {
+  padding: 1rem;
+  display: flex;
+  justify-content: end;
+}
diff --git a/examples/ssg-app/app/layout.tsx b/examples/ssg-app/app/layout.tsx
@@ -0,0 +1,28 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+export const metadata: Metadata = {
+  title: "SSG App",
+  description: "An app in which all the routes are SSG'd",
+};
+
+export default async function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  const cloudflareContext = await getCloudflareContext({
+    async: true,
+  });
+
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <footer data-testid="app-version">{cloudflareContext.env.APP_VERSION}</footer>
+      </body>
+    </html>
+  );
+}
diff --git a/examples/ssg-app/app/page.module.css b/examples/ssg-app/app/page.module.css
@@ -0,0 +1,17 @@
+.page {
+  display: grid;
+  grid-template-rows: 20px 1fr 20px;
+  align-items: center;
+  justify-items: center;
+  flex: 1;
+  border: 3px solid gray;
+  margin: 1rem;
+  margin-block-end: 0;
+}
+
+.main {
+  display: flex;
+  flex-direction: column;
+  gap: 32px;
+  grid-row-start: 2;
+}
diff --git a/examples/ssg-app/app/page.tsx b/examples/ssg-app/app/page.tsx
@@ -0,0 +1,17 @@
+import styles from "./page.module.css";
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+export default async function Home() {
+  const cloudflareContext = await getCloudflareContext({
+    async: true,
+  });
+
+  return (
+    <div className={styles.page}>
+      <main className={styles.main}>
+        <h1>Hello from a Statically generated page</h1>
+        <p data-testid="my-secret">{cloudflareContext.env.MY_SECRET}</p>
+      </main>
+    </div>
+  );
+}
diff --git a/examples/ssg-app/e2e/base.spec.ts b/examples/ssg-app/e2e/base.spec.ts
@@ -0,0 +1,17 @@
+import { test, expect } from "@playwright/test";
+
+test("the index page should work", async ({ page }) => {
+  await page.goto("/");
+  await expect(page.getByText("Hello from a Statically generated page")).toBeVisible();
+});
+
+test("the APP_VERSION var from the cloudflare context should be displayed", async ({ page }) => {
+  await page.goto("/");
+  await expect(page.getByTestId("app-version")).toHaveText("1.2.345");
+});
+
+// Note: secrets from .dev.vars are also part of the SSG output, this is expected and nothing we can avoid
+test("the MY_SECRET secret from the cloudflare context should be displayed", async ({ page }) => {
+  await page.goto("/");
+  await expect(page.getByTestId("my-secret")).toHaveText("psst... this is a secret!");
+});
diff --git a/examples/ssg-app/e2e/playwright.config.ts b/examples/ssg-app/e2e/playwright.config.ts
@@ -0,0 +1,3 @@
+import { configurePlaywright } from "../../common/config-e2e";
+
+export default configurePlaywright("ssg-app", { isCI: !!process.env.CI });
diff --git a/examples/ssg-app/next.config.ts b/examples/ssg-app/next.config.ts
@@ -0,0 +1,10 @@
+import type { NextConfig } from "next";
+import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
+
+initOpenNextCloudflareForDev();
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;
diff --git a/examples/ssg-app/open-next.config.ts b/examples/ssg-app/open-next.config.ts
@@ -0,0 +1,26 @@
+// default open-next.config.ts file created by @opennextjs/cloudflare
+
+import cache from "@opennextjs/cloudflare/kv-cache";
+
+const config = {
+  default: {
+    override: {
+      wrapper: "cloudflare-node",
+      converter: "edge",
+      incrementalCache: async () => cache,
+      tagCache: "dummy",
+      queue: "dummy",
+    },
+  },
+
+  middleware: {
+    external: true,
+    override: {
+      wrapper: "cloudflare-edge",
+      converter: "edge",
+      proxyExternalRequest: "fetch",
+    },
+  },
+};
+
+export default config;
diff --git a/examples/ssg-app/package.json b/examples/ssg-app/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "ssg-app",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "build:worker": "opennextjs-cloudflare",
+    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "e2e": "playwright test -c e2e/playwright.config.ts"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "next": "15.1.7"
+  },
+  "devDependencies": {
+    "@opennextjs/cloudflare": "workspace:*",
+    "@playwright/test": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "typescript": "catalog:",
+    "wrangler": "catalog:"
+  }
+}
diff --git a/examples/ssg-app/tsconfig.json b/examples/ssg-app/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
diff --git a/examples/ssg-app/worker-configuration.d.ts b/examples/ssg-app/worker-configuration.d.ts
@@ -0,0 +1,5 @@
+interface CloudflareEnv {
+  APP_VERSION: "1.2.345";
+  MY_SECRET: string;
+  ASSETS: Fetcher;
+}
diff --git a/examples/ssg-app/wrangler.json b/examples/ssg-app/wrangler.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "main": ".open-next/worker.js",
+  "name": "ssg-app",
+  "compatibility_date": "2025-02-04",
+  "compatibility_flags": ["nodejs_compat"],
+  "assets": {
+    "directory": ".open-next/assets",
+    "binding": "ASSETS"
+  },
+  "vars": {
+    "APP_VERSION": "1.2.345"
+  },
+  "kv_namespaces": [
+    // Create a KV binding with the binding name "NEXT_CACHE_WORKERS_KV"
+    // to enable the KV based caching:
+    // {
+    //   "binding": "NEXT_CACHE_WORKERS_KV",
+    //   "id": "<BINDING_ID>"
+    // }
+  ]
+}
diff --git a/packages/cloudflare/src/api/cloudflare-context.ts b/packages/cloudflare/src/api/cloudflare-context.ts
@@ -45,6 +45,14 @@ type InternalGlobalThis<
   __NEXT_DATA__: Record<string, unknown>;
 };
 
+type GetCloudflareContextOptions = {
+  /**
+   * When `true`, `getCloudflareContext` returns a promise of the cloudflare context instead of the context,
+   * this is needed to access the context from statically generated routes.
+   */
+  async: boolean;
+};
+
 /**
  * Utility to get the current Cloudflare context
  *
@@ -53,26 +61,48 @@ type InternalGlobalThis<
 export function getCloudflareContext<
   CfProperties extends Record<string, unknown> = IncomingRequestCfProperties,
   Context = ExecutionContext,
->(): CloudflareContext<CfProperties, Context> {
+>(options: { async: true }): Promise<CloudflareContext<CfProperties, Context>>;
+export function getCloudflareContext<
+  CfProperties extends Record<string, unknown> = IncomingRequestCfProperties,
+  Context = ExecutionContext,
+>(options?: { async: false }): CloudflareContext<CfProperties, Context>;
+export function getCloudflareContext<
+  CfProperties extends Record<string, unknown> = IncomingRequestCfProperties,
+  Context = ExecutionContext,
+>(
+  options: GetCloudflareContextOptions = { async: false }
+): CloudflareContext<CfProperties, Context> | Promise<CloudflareContext<CfProperties, Context>> {
   const global = globalThis as InternalGlobalThis<CfProperties, Context>;
 
   const cloudflareContext = global[cloudflareContextSymbol];
 
+  // whether `getCloudflareContext` is run in "async mode"
+  const asyncMode = options.async;
+
   if (!cloudflareContext) {
-    // For SSG Next.js creates (jest) workers that run in parallel, those don't get the current global
-    // state so they can't get access to the cloudflare context, unfortunately there isn't anything we
-    // can do about this, so the only solution is to error asking the developer to opt-out of SSG
-    // Next.js sets globalThis.__NEXT_DATA__.nextExport to true for the worker, so we can use that to detect
-    // that the route is being SSG'd (source: https://github.com/vercel/next.js/blob/4e394608423/packages/next/src/export/worker.ts#L55-L57)
-    if (global.__NEXT_DATA__?.nextExport === true) {
+    // The sync mode of `getCloudflareContext`, relies on the context being set on the global state
+    // by either the worker entrypoint (in prod) or by `initOpenNextCloudflareForDev` (in dev), neither
+    // can work during SSG since for SSG Next.js creates (jest) workers that don't get access to the
+    // normal global state so we throw with a helpful error message.
+    // Note: Next.js sets globalThis.__NEXT_DATA__.nextExport to true for SSG routes
+    // source: https://github.com/vercel/next.js/blob/4e394608423/packages/next/src/export/worker.ts#L55-L57)
+    if (!asyncMode && global.__NEXT_DATA__?.nextExport === true) {
       throw new Error(
         `\n\nERROR: \`getCloudflareContext\` has been called in a static route` +
-          ` that is not allowed, please either avoid calling \`getCloudflareContext\`` +
-          ` in the route or make the route non static (for example by exporting the` +
-          ` \`dynamic\` route segment config set to \`'force-dynamic'\`.\n`
+          ` that is not allowed, this can be solved in different ways:\n\n` +
+          ` - call \`getCloudflareContext({async: true})\` to use the \`async\` mode\n` +
+          ` - avoid calling \`getCloudflareContext\` in the route\n` +
+          ` - make the route non static\n`
       );
     }
 
+    if (options.async) {
+      return getCloudflareContextFromWrangler<CfProperties, Context>().then((context) => {
+        addCloudflareContextToNodejsGlobal(context);
+        return context;
+      });
+    }
+
     // the cloudflare context is initialized by the worker and is always present in production/preview
     // during local development (`next dev`) it might be missing only if the developers hasn't called
     // the `initOpenNextCloudflareForDev` function in their Next.js config file
@@ -127,12 +157,15 @@ function shouldContextInitializationRun(): boolean {
 }
 
 /**
- * Adds the cloudflare context to the global scope in which the Next.js dev node.js process runs in, enabling
+ * Adds the cloudflare context to the global scope of the current node.js process, enabling
  * future calls to `getCloudflareContext` to retrieve and return such context
  *
  * @param cloudflareContext the cloudflare context to add to the node.sj global scope
  */
-function addCloudflareContextToNodejsGlobal(cloudflareContext: CloudflareContext<CfProperties, Context>) {
+function addCloudflareContextToNodejsGlobal<
+  CfProperties extends Record<string, unknown> = IncomingRequestCfProperties,
+  Context = ExecutionContext,
+>(cloudflareContext: CloudflareContext<CfProperties, Context>) {
   const global = globalThis as InternalGlobalThis<CfProperties, Context>;
   global[cloudflareContextSymbol] = cloudflareContext;
 }
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		import { configurePlaywright } from "../../common/config-e2e";

		export default configurePlaywright("ssg-app", { isCI: !!process.env.CI });
dario-piotrowicz marked this conversation as resolved. Outdated Show resolved Hide resolved