feat: add option to align header priorization execution order (opennextjs#981)

* feat: add option to align header priorization execution order

Fixes opennextjs#973

* chore: add initial changeset file

* chore: pick open-next.config.local.ts changes as well

* chore: fix feedback

* chore: improve comment on test

Author: dirkdev98

.changeset/shiny-plants-remember.md

@@ -0,0 +1,5 @@
+---
+"@opennextjs/aws": minor
+---
+
+feat: Add option to align with Next.js execution order for headers in middleware and next.config.js

examples/app-router/middleware.ts

@@ -50,6 +50,12 @@ export function middleware(request: NextRequest) {
   // Response headers should show up in the client's response headers
   responseHeaders.set("response-header", "response-header");
 
+  // For dangerous.middlewareHeadersOverrideNextConfigHeaders we need to verify that middleware headers override next.config.js headers.
+  if (path === "/headers/override-from-middleware") {
+    responseHeaders.set("e2e-headers", "middleware");
+    return NextResponse.json({}, { headers: responseHeaders });
+  }
+
   // Set the cache control header with custom swr
   // For: isr.test.ts
   if (path === "/isr" && !request.headers.get("x-prerender-revalidate")) {

examples/app-router/open-next.config.local.ts

@@ -11,6 +11,10 @@ export default {
     },
   },
 
+  dangerous: {
+    middlewareHeadersOverrideNextConfigHeaders: true,
+  },
+
   imageOptimization: {
     override: {
       wrapper: "dummy",

examples/app-router/open-next.config.ts

@@ -8,6 +8,9 @@ const config = {
     },
   },
   functions: {},
+  dangerous: {
+    middlewareHeadersOverrideNextConfigHeaders: true,
+  },
   buildCommand: "npx turbo build",
 };
 

packages/open-next/src/core/routingHandler.ts

@@ -129,10 +129,22 @@ export default async function routingHandler(
       return middlewareEventOrResult;
     }
 
-    headers = {
-      ...middlewareEventOrResult.responseHeaders,
-      ...headers,
-    };
+    const middlewareHeadersPrioritized =
+      globalThis.openNextConfig.dangerous
+        ?.middlewareHeadersOverrideNextConfigHeaders ?? false;
+
+    if (middlewareHeadersPrioritized) {
+      headers = {
+        ...headers,
+        ...middlewareEventOrResult.responseHeaders,
+      };
+    } else {
+      headers = {
+        ...middlewareEventOrResult.responseHeaders,
+        ...headers,
+      };
+    }
+
     let isExternalRewrite = middlewareEventOrResult.isExternalRewrite ?? false;
     eventOrResult = middlewareEventOrResult;
 

packages/open-next/src/types/open-next.ts

@@ -86,6 +86,17 @@ export interface DangerousOptions {
   headersAndCookiesPriority?: (
     event: InternalEvent,
   ) => "middleware" | "handler";
+
+  /**
+   * Configuration option to prioritize headers set via middleware over headers set via the option in the Next config.
+   *
+   * The default will change to 'true' in v4.
+   *
+   * See also {@link https://nextjs.org/docs/app/api-reference/file-conventions/middleware#execution-order}
+   *
+   * @default false
+   */
+  middlewareHeadersOverrideNextConfigHeaders?: boolean;
 }
 
 export type BaseOverride = {

packages/tests-e2e/tests/appRouter/headers.test.ts

@@ -28,3 +28,20 @@ test("Headers", async ({ page }) => {
   // Request ID header should be set
   expect(headers["x-opennext-requestid"]).not.toBeFalsy();
 });
+
+/**
+ * Tests that the middleware headers are applied after next.config.js headers. Requires 'dangerous.middlewareHeadersOverrideNextConfigHeaders' to be set.
+ */
+test("Middleware headers override next.config.js headers", async ({ page }) => {
+  const responsePromise = page.waitForResponse((response) => {
+    return response.status() === 200;
+  });
+  await page.goto("/headers/override-from-middleware");
+
+  const response = await responsePromise;
+  // Response header should be set
+  const headers = response.headers();
+
+  // The next.config.js headers is overwritten by the middleware
+  expect(headers["e2e-headers"]).toEqual("middleware");
+});