introduce new initOpenNextCloudflareForDev utility and make getCloudflareContext synchronous

Author: dario-piotrowicz

.changeset/chilly-dryers-begin.md

@@ -0,0 +1,47 @@
+---
+"@opennextjs/cloudflare": patch
+---
+
+introduce new `initOpenNextCloudflareForDev` utility and make `getCloudflareContext` synchronous
+
+introduce a new `initOpenNextCloudflareForDev` function that when called in the [Next.js config file](https://nextjs.org/docs/app/api-reference/config/next-config-js) integrates the Next.js dev server with the open-next Cloudflare adapter. Most noticeably this enables `getCloudflareContext` to work in
+the edge runtime (including middlewares) during development.
+
+Moving forward we'll recommend that all applications include the use of this 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";
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+initOpenNextCloudflareForDev();
+
+export default nextConfig;
+```
+
+thanks to this new utility we are also able to make `getCloudflareContext` synchronous, so `await`ing such function is no longer necessary
+
+Example:
+
+- Before:
+
+  ```js
+  import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+  const cloudflareContext = await getCloudflareContext();
+  // cloudflareContext use
+  ```
+
+- After:
+
+  ```js
+  import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+  const cloudflareContext = getCloudflareContext();
+  // cloudflareContext use
+  ```

examples/api/e2e/playwright.config.ts

@@ -49,5 +49,8 @@ export default defineConfig({
     command: "pnpm preview:worker",
     url: "http://localhost:8770",
     reuseExistingServer: !process.env.CI,
+    // the app uses the `initOpenNextCloudflareForDev` which in CI apparently makes the boot up take slightly longer,
+    // that's why we need a longer timeout here (we just add 10 seconds to the default 60)
+    timeout: !process.env.CI ? undefined : 60 * 1000 + 10 * 1000,
   },
 });

examples/api/next.config.mjs

@@ -1,3 +1,7 @@
+import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
+
+initOpenNextCloudflareForDev();
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 

examples/create-next-app/e2e/playwright.config.ts

@@ -49,5 +49,8 @@ export default defineConfig({
     command: "pnpm preview:worker",
     url: "http://localhost:8771",
     reuseExistingServer: !process.env.CI,
+    // the app uses the `initOpenNextCloudflareForDev` which in CI apparently makes the boot up take slightly longer,
+    // that's why we need a longer timeout here (we just add 10 seconds to the default 60)
+    timeout: !process.env.CI ? undefined : 60 * 1000 + 10 * 1000,
   },
 });

examples/create-next-app/next.config.mjs

@@ -1,3 +1,7 @@
+import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
+
+initOpenNextCloudflareForDev();
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 

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>
+    </>
+  );
 }

examples/middleware/e2e/cloudflare-context.spec.ts

@@ -0,0 +1,14 @@
+import { test, expect } from "@playwright/test";
+
+test("cloudflare context env object is populated", async ({ page }) => {
+  await page.goto("/middleware");
+  const cloudflareContextHeaderElement = page.getByTestId("cloudflare-context-header");
+  // Note: the text in the span is "keys of `cloudflareContext.env`: MY_VAR, MY_KV, ASSETS" for previews
+  //       and "keys of `cloudflareContext.env`: MY_VAR, MY_KV" in dev (`next dev`)
+  //       that's why we use `toContain` instead of `toEqual`, this is incorrect and the `ASSETS` binding
+  //       should ideally also be part of the dev cloudflare context
+  //       (this is an upstream wrangler issue: https://github.com/cloudflare/workers-sdk/issues/7812)
+  expect(await cloudflareContextHeaderElement.textContent()).toContain(
+    "keys of `cloudflareContext.env`: MY_VAR, MY_KV"
+  );
+});

examples/middleware/e2e/playwright.config.ts

@@ -49,5 +49,8 @@ export default defineConfig({
     command: "pnpm preview:worker",
     url: "http://localhost:8774",
     reuseExistingServer: !process.env.CI,
+    // the app uses the `initOpenNextCloudflareForDev` which in CI apparently makes the boot up take slightly longer,
+    // that's why we need a longer timeout here (we just add 10 seconds to the default 60)
+    timeout: !process.env.CI ? undefined : 60 * 1000 + 10 * 1000,
   },
 });

examples/middleware/e2e/playwright.dev.config.ts

@@ -0,0 +1,53 @@
+import { defineConfig, devices } from "@playwright/test";
+
+declare var process: { env: Record<string, string> };
+
+/**
+ * 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,
+  },
+});

examples/middleware/middleware.ts

@@ -1,7 +1,9 @@
 import { NextRequest, NextResponse, NextFetchEvent } from "next/server";
 import { clerkMiddleware } from "@clerk/nextjs/server";
 
-export function middleware(request: NextRequest, event: NextFetchEvent) {
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+export async function middleware(request: NextRequest, event: NextFetchEvent) {
   console.log("middleware");
   if (request.nextUrl.pathname === "/about") {
     return NextResponse.redirect(new URL("/redirected", request.url));
@@ -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",
+    `keys of \`cloudflareContext.env\`: ${Object.keys(cloudflareContext.env).join(", ")}`
+  );
+
+  return NextResponse.next({
+    request: {
+      headers: requestHeaders,
+    },
+  });
 }
 
 export const config = {