RFC: unstable_setHeaders() API for App Router - Before Streaming Begins

[diego-toress]

Problem

Many of us migrating from Pages Router need to set response headers dynamically based on fetched data:

• CDN cache tagging (Surrogate-Key for Fastly/Cloudflare purging)
• Dynamic Cache-Control based on content expiration dates
• Security headers that depend on page content
• Custom headers for load balancing/routing

The current recommendation is Middleware, but:

1. Middleware runs before data fetching, so we can't set headers based on fetched data
2. Middleware has limited Node.js runtime support
3. It's not ideal for heavy I/O operations

Proposed Solution

What about an API that sets headers before streaming begins?

// app/products/[id]/page.tsx
import { unstable_setHeaders } from 'next/headers';

export default async function ProductPage({ params }) {
  const product = await getProduct(params.id);
  
  // Set headers BEFORE the component renders/streams
  unstable_setHeaders({
    'Surrogate-Key': product.id,
    'Cache-Control': `s-maxage=${product.cacheTime}`,
  });

  return <ProductDetails product={product} />;
}

Questions for the Team

1. Is this technically feasible with the streaming architecture?
2. Could this be limited to page.tsx and layout.tsx only (not nested components)?
3. Any timeline for addressing this gap?

[mvpcraft]

Based on the research, here are the current solutions for setting response headers in App Router:

---

✅ Working Solutions

1. Use Route Handlers (API Routes)

// app/api/product/[id]/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request, { params }) {
  const product = await getProduct(params.id);
  
  return NextResponse.json(product, {
    headers: {
      'Surrogate-Key': product.id,
      'Cache-Control': `s-maxage=${product.cacheTime}`,
    },
  });
}

2. Use Middleware (when headers don't depend on fetched data)

// middleware.ts
import { NextResponse } from 'next/server';

export function middleware(request) {
  const response = NextResponse.next();
  response.headers.set('X-Custom-Header', 'value');
  return response;
}

3. Use next.config.js (for static headers)

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/products/:id',
        headers: [{ key: 'Cache-Control', value: 's-maxage=3600' }],
      },
    ];
  },
};

---

❌ Not Possible (by design)

Setting headers inside Server Components based on fetched data — because React streaming may have already started sending the response body.

---

🎯 Best Workaround for Dynamic Headers

Fetch data in a Route Handler, set headers there, then either:

• Return JSON and fetch client-side, OR
• Use the Route Handler as a proxy/redirect

This is the architectural limitation of streaming SSR.