Custom HTTP Response Status and Headers Per Page in Next.js App Router Mode

[Innei]

Goals

• Enable dynamic customization of HTTP response codes and headers for individual pages in App Router mode.
• Provide developers with finer control over the HTTP responses returned by their Next.js applications, improving flexibility for use cases like SEO optimization, A/B testing, and compliance with security policies.

Non-Goals

This feature request does not aim to modify the underlying HTTP server capabilities such as handling of static files, caching strategies for assets, or server-side streaming capabilities.
It is not intended to introduce changes that would affect the overall performance benchmarks established for Next.js applications under normal operation conditions.

Background

In frameworks like Remix, developers have the ability to manipulate the HTTP responses directly within route loaders using utilities like defer to set HTTP status codes and headers. This functionality is critical for applications that require dynamic response handling based on the request context or specific business logic. Currently, we can only call notFound to set response as 404 status, but if it's 403, 401, etc., there's nothing we can do. Also, we can't set http headers on the page, sometimes we need to set, for example, cache-control to control caching.

Example in remix:

export const loader = async () => {
  const aStillRunningPromise = loadSlowDataAsync();

  return defer(
    {
      critical: "data",
      slowPromise: aStillRunningPromise,
    },
    {
      status: 418,
      headers: {
        "Cache-Control": "no-store",
      },
    }
  );
};

Proposal

My idea is that a new route segement config could be added.

export const handle = async ({ params }) => {
	// fetch data or do thing
	return {
	  status: 404, // custom status code
      headers: { // custom headers
        "Cache-Control": "no-store",
      }
    }
}

or, provide a util function only for the server side.

export default async function Page() {
	
	response({
	  status: 404, // custom status code
      headers: { // custom headers
        "Cache-Control": "no-store",
      }
    })
/// 
}