introduce new initOpenNextCloudflareForDev utility and make getCloudflareContext synchronous (#265)

dario-piotrowicz · vicb · web-flow · commit 8de2c0422e3d · 2025-01-27T10:30:02.000Z
Co-authored-by: Victor Berchet &lt;victor@suumit.com&gt;
diff --git a/.changeset/chilly-dryers-begin.md b/.changeset/chilly-dryers-begin.md
@@ -0,0 +1,28 @@
+---
+"@opennextjs/cloudflare": minor
+---
+
+introduce new `initOpenNextCloudflareForDev` utility and make `getCloudflareContext` synchronous
+
+this change introduces a new `initOpenNextCloudflareForDev` function that must called in the [Next.js config file](https://nextjs.org/docs/app/api-reference/config/next-config-js) to integrate the Next.js dev server with the open-next Cloudflare adapter.
+
+Also makes `getCloudflareContext` synchronous.
+
+Additionally the `getCloudflareContext` can now work during local development (`next dev`) in the edge runtime (including middlewares).
+
+Moving forward we'll recommend that all applications include the use of the `initOpenNextCloudflareForDev` utility in their config file (there is no downside in doing so and it only effect local development).
+
+Example:
+
+```js
+// next.config.mjs
+
+import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
+
+initOpenNextCloudflareForDev();
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;
+```
diff --git a/examples/api/app/api/hello/route.ts b/examples/api/app/api/hello/route.ts
@@ -11,9 +11,8 @@ export async function GET() {
     return new Response("Hello World!");
   }
 
-  // Retrieve the bindings defined in wrangler.toml
-  const { env } = await getCloudflareContext();
-  return new Response(env.hello);
+  // Retrieve the bindings defined in wrangler.json
+  return new Response(getCloudflareContext().env.hello);
 }
 
 export async function POST(request: Request) {
diff --git a/examples/api/e2e/playwright.config.ts b/examples/api/e2e/playwright.config.ts
@@ -1,6 +1,7 @@
 import { defineConfig, devices } from "@playwright/test";
+import type nodeProcess from "node:process";
 
-declare var process: { env: Record<string, string> };
+declare const process: typeof nodeProcess;
 
 /**
  * See https://playwright.dev/docs/test-configuration.
@@ -49,5 +50,6 @@ export default defineConfig({
     command: "pnpm preview:worker",
     url: "http://localhost:8770",
     reuseExistingServer: !process.env.CI,
+    timeout: 70_000,
   },
 });
diff --git a/examples/api/e2e/playwright.dev.config.ts b/examples/api/e2e/playwright.dev.config.ts
@@ -1,6 +1,7 @@
 import { defineConfig, devices } from "@playwright/test";
+import type nodeProcess from "node:process";
 
-declare var process: { env: Record<string, string> };
+declare const process: typeof nodeProcess;
 
 /**
  * See https://playwright.dev/docs/test-configuration.
diff --git a/examples/api/next.config.mjs b/examples/api/next.config.mjs
@@ -1,3 +1,7 @@
+import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
+
+initOpenNextCloudflareForDev();
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 
diff --git a/examples/create-next-app/e2e/playwright.config.ts b/examples/create-next-app/e2e/playwright.config.ts
@@ -1,6 +1,7 @@
 import { defineConfig, devices } from "@playwright/test";
+import type nodeProcess from "node:process";
 
-declare const process: { env: Record<string, string> };
+declare const process: typeof nodeProcess;
 
 /**
  * See https://playwright.dev/docs/test-configuration.
@@ -49,5 +50,6 @@ export default defineConfig({
     command: "pnpm preview:worker",
     url: "http://localhost:8771",
     reuseExistingServer: !process.env.CI,
+    timeout: 70_000,
   },
 });
diff --git a/examples/create-next-app/next.config.mjs b/examples/create-next-app/next.config.mjs
@@ -1,3 +1,7 @@
+import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
+
+initOpenNextCloudflareForDev();
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 
diff --git a/examples/middleware/app/middleware/page.tsx b/examples/middleware/app/middleware/page.tsx
@@ -1,3 +1,25 @@
+import { headers } from "next/headers";
+
 export default function MiddlewarePage() {
-  return <h1>Via middleware</h1>;
+  const cloudflareContextHeader = headers().get("x-cloudflare-context");
+
+  return (
+    <>
+      <h1>Via middleware</h1>
+      <p>
+        The value of the <i>x-cloudflare-context</i> header is: <br />
+        <span
+          style={{
+            display: "inline-block",
+            margin: "1rem 2rem",
+            color: "grey",
+            fontSize: "1.2rem",
+          }}
+          data-testid="cloudflare-context-header"
+        >
+          {cloudflareContextHeader}
+        </span>
+      </p>
+    </>
+  );
 }
diff --git a/examples/middleware/e2e/cloudflare-context.spec.ts b/examples/middleware/e2e/cloudflare-context.spec.ts
@@ -0,0 +1,9 @@
+import { test, expect } from "@playwright/test";
+
+test("middlewares have access to the cloudflare context", async ({ page }) => {
+  await page.goto("/middleware");
+  const cloudflareContextHeaderElement = page.getByTestId("cloudflare-context-header");
+  expect(await cloudflareContextHeaderElement.textContent()).toContain(
+    "typeof `cloudflareContext.env` = object"
+  );
+});
diff --git a/examples/middleware/e2e/playwright.config.ts b/examples/middleware/e2e/playwright.config.ts
@@ -1,6 +1,7 @@
 import { defineConfig, devices } from "@playwright/test";
+import type nodeProcess from "node:process";
 
-declare const process: { env: Record<string, string> };
+declare const process: typeof nodeProcess;
 
 /**
  * See https://playwright.dev/docs/test-configuration.
@@ -49,5 +50,6 @@ export default defineConfig({
     command: "pnpm preview:worker",
     url: "http://localhost:8774",
     reuseExistingServer: !process.env.CI,
+    timeout: 70_000,
   },
 });
diff --git a/examples/middleware/e2e/playwright.dev.config.ts b/examples/middleware/e2e/playwright.dev.config.ts
@@ -0,0 +1,54 @@
+import { defineConfig, devices } from "@playwright/test";
+import type nodeProcess from "node:process";
+
+declare const process: typeof nodeProcess;
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: "./",
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: "html",
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL: "http://localhost:3334",
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: "on-first-retry",
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  webServer: {
+    command: "pnpm dev --port 3334",
+    url: "http://localhost:3334",
+    reuseExistingServer: !process.env.CI,
+  },
+});
diff --git a/examples/middleware/middleware.ts b/examples/middleware/middleware.ts
@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse, NextFetchEvent } from "next/server";
 import { clerkMiddleware } from "@clerk/nextjs/server";
 
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
 export function middleware(request: NextRequest, event: NextFetchEvent) {
   console.log("middleware");
   if (request.nextUrl.pathname === "/about") {
@@ -16,7 +18,19 @@ export function middleware(request: NextRequest, event: NextFetchEvent) {
     })(request, event);
   }
 
-  return NextResponse.next();
+  const requestHeaders = new Headers(request.headers);
+  const cloudflareContext = getCloudflareContext();
+
+  requestHeaders.set(
+    "x-cloudflare-context",
+    `typeof \`cloudflareContext.env\` = ${typeof cloudflareContext.env}`
+  );
+
+  return NextResponse.next({
+    request: {
+      headers: requestHeaders,
+    },
+  });
 }
 
 export const config = {
diff --git a/examples/middleware/next.config.mjs b/examples/middleware/next.config.mjs
@@ -1,3 +1,7 @@
+import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
+
+initOpenNextCloudflareForDev();
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 
diff --git a/examples/middleware/package.json b/examples/middleware/package.json
@@ -9,7 +9,8 @@
     "build:worker": "pnpm opennextjs-cloudflare",
     "dev:worker": "wrangler dev --port 8774 --inspector-port 9334",
     "preview:worker": "pnpm build:worker && pnpm dev:worker",
-    "e2e": "playwright test -c e2e/playwright.config.ts"
+    "e2e": "playwright test -c e2e/playwright.config.ts",
+    "e2e:dev": "playwright test -c e2e/playwright.dev.config.ts"
   },
   "dependencies": {
     "@clerk/nextjs": "6.9.6",
diff --git a/examples/middleware/wrangler.json b/examples/middleware/wrangler.json
@@ -7,5 +7,9 @@
   "assets": {
     "directory": ".open-next/assets",
     "binding": "ASSETS"
-  }
+  },
+  "vars": {
+    "MY_VAR": "my-var"
+  },
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "<id>" }]
 }
diff --git a/package.json b/package.json
@@ -13,6 +13,7 @@
     "prettier:fix": "prettier --write .",
     "lint:check": "pnpm -r lint:check",
     "lint:fix": "pnpm -r lint:fix",
+    "fix": "pnpm prettier:fix && pnpm lint:fix",
     "ts:check": "pnpm -r ts:check",
     "test": "pnpm -r test",
     "code:checks": "pnpm prettier:check && pnpm lint:check && pnpm ts:check",
diff --git a/packages/cloudflare/README.md b/packages/cloudflare/README.md
@@ -6,72 +6,7 @@ Deploy Next.js apps to Cloudflare!
 
 ## Get started
 
-You can use [`create-next-app`](https://nextjs.org/docs/pages/api-reference/cli/create-next-app) to start a new application or take an existing Next.js application and deploy it to Cloudflare using the following few steps:
-
-## Configure your app
-
-- add the following `devDependencies` to the `package.json`:
-
-  ```bash
-  npm add -D wrangler@latest @opennextjs/cloudflare
-  # or
-  pnpm add -D wrangler@latest @opennextjs/cloudflare
-  # or
-  yarn add -D wrangler@latest @opennextjs/cloudflare
-  # or
-  bun add -D wrangler@latest @opennextjs/cloudflare
-  ```
-
-- add a `wrangler.json` at the root of your project
-
-```json
-{
-  "$schema": "node_modules/wrangler/config-schema.json",
-  "main": ".open-next/worker.js",
-  "name": "<your-app-name>",
-  "compatibility_date": "2024-12-30",
-  "compatibility_flags": ["nodejs_compat"],
-  "assets": {
-    "directory": ".open-next/assets",
-    "binding": "ASSETS"
-  }
-}
-```
-
-- add a `open-next.config.ts` at the root of your project:
-
-```ts
-import type { OpenNextConfig } from "open-next/types/open-next";
-
-const config: OpenNextConfig = {
-  default: {
-    override: {
-      wrapper: "cloudflare-node",
-      converter: "edge",
-      // Unused implementation
-      incrementalCache: "dummy",
-      tagCache: "dummy",
-      queue: "dummy",
-    },
-  },
-
-  middleware: {
-    external: true,
-    override: {
-      wrapper: "cloudflare-edge",
-      converter: "edge",
-      proxyExternalRequest: "fetch",
-    },
-  },
-};
-
-export default config;
-```
-
-## Known issues
-
-- `▲ [WARNING] Suspicious assignment to defined constant "process.env.NODE_ENV" [assign-to-define]` can safely be ignored
-- Maybe more, still experimental...
+To get started with the adapter visit the [official get started documentation](https://opennext.js.org/cloudflare/get-started).
 
 ## Local development
 
diff --git a/packages/cloudflare/src/api/cloudflare-context.ts b/packages/cloudflare/src/api/cloudflare-context.ts
diff --git a/packages/cloudflare/src/api/get-cloudflare-context.ts b/packages/cloudflare/src/api/get-cloudflare-context.ts
diff --git a/packages/cloudflare/src/api/index.ts b/packages/cloudflare/src/api/index.ts
diff --git a/packages/cloudflare/src/api/kvCache.ts b/packages/cloudflare/src/api/kvCache.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml

Original file line number	Diff line number	Diff line change
`@@ -11,9 +11,8 @@ export async function GET() {`
`11`	`11`	`return new Response("Hello World!");`
`12`	`12`	`}`
`13`	`13`
`14`		`- // Retrieve the bindings defined in wrangler.toml`
`15`		`- const { env } = await getCloudflareContext();`
`16`		`- return new Response(env.hello);`
	`14`	`+ // Retrieve the bindings defined in wrangler.json`
	`15`	`+ return new Response(getCloudflareContext().env.hello);`
`17`	`16`	`}`
`18`	`17`
`19`	`18`	`export async function POST(request: Request) {`