App Router Custom Header Use Cases

[gnoff]

We’ve noticed questions and an interest in being able to set headers on the Response during an App Router render. We wanted to clarify why we don’t provide a generic solution for this at this time and ask for a certain kind of feedback that may influence our path forward here in the future.

Background

The Pages Router, unlike the App Router, does not stream responses. Because of this, the Pages Router can set any headers discovered during rendering before we send the Response body.

The App Router uses React streaming for Server Side Rendering (SSR) and React Server Components (RSC). With streaming, we may have already starting sending a portion of the body before a component could attempt to set headers. This makes traditional APIs where you set a header while rendering impractical for App Router.

Our current solution

We recommend setting headers in Middleware today when using the App Router. While this works, we believe there’s still some opportunities for improvement here:

• Middleware does not yet support the full Node.js runtime, but only a subset of available APIs. Some community packages may use Node.js APIs to derive header values, which can cause incompatibility issues (Discussion).
• I/O that happens during Middleware needs to finish before rendering can start, and then may need to be repeated while rendering.

Why not a generic solution yet?

We could offer an API like generateHeaders() {...} . This API could block the stream until the function resolved. Further, it would share a Request cache with the render process and run concurrently with it.

While this would solve some of the tradeoffs of the current Middleware solution, we are concerned about the unintentional performance impacts and footguns.

Properly setting headers can have a massive performance impact. Further, generic APIs to set headers would not be integrated with other purpose designed APIs for caching and revalidating, like Incremental Static Regeneration (ISR).

For example, if you used a generic headers API and also ISR on the same page, you would have unexpected behavior. Combining these together may cause browsers to avoid refetching even after an ISR revalidation is triggered.

This is why ISR does set Cache-Control headers, but it derives through values from higher level abstractions that can be discovered (and possible errored on) during build time.

Purpose of this discussion

We’d like to use this discussion to understand the underlying use cases that lead folks to look for a generic headers API beyond Middleware. In some cases we may find that a purpose-fit API is necessary to provide the optimal experience and avoid footguns leading to poor performance and frustration. We may also discover there are cases where a generic and simple headers API is really the right fit.

Before posting, please consider whether the use case actually requires concurrent-with-render-time derivation. Middleware is a great place for headers that don't have an IO component. Additionally if your use-case is that you need to use Node.js APIs please still be specific about what you are trying to accomplish, not just that you are using a tool which is incompatible with Middleware.

Additionally, many hosts (including Vercel) allow you to statically assign headers by route. If your header use case can be satisfied by one of these techniques, then it doesn't need to be documented in this discussion.

A use case here should convey the following information:

1. What capability do you want to achieve? (i.e. I'd like my pages to be cached by the browser)
2. What header or headers are necessary to coordinate this behavior?
3. What makes Middleware and or static headers insufficient

We are aware there is a need for many potential users that isn't yet being met as well as we'd like.

I do not want to have this discussion turn into one about what the right API is. Please keep the discussion focussed on what use cases need to be served which are currently impossible or impractical today.

[ucola]

Thanks for the discussion, I'll try to explain our case

What capability are you aiming to achieve? (For example, "I want my web pages to be cached by the browser.")
We use Drupal as the backend and Varnish for frontend caching. Both Drupal and Varnish are equipped to handle Cache-Tags. Since Next.js is also capable of utilizing Cache-Tags, our goal is to use it to invalidate the Caches more efficient.

Each piece of content in Drupal has different cache tags. We transfer these cache tags to Next.js and use them there for cache invalidation, which is currently working well. However, we also need to pass these cache tags to Varnish (via headers) so that Varnish can utilize them as well.

Which header or headers are necessary to coordinate this behavior?
The headers could be Cache-Tags, X-Drupal-Cache-Tags, or X-Cache-Tags.

Why are middleware and static headers insufficient?
Our approach involves accessing Drupal via the JsonAPI. We fetch the data in the page files (app folder), etc. Our cache tags are included in the fetch response from Drupal. Middleware operates too early in the process—by the time we have the JsonAPI data, the request has already passed through the middleware and onto Next.js. The response goes directly to the client and does not pass through the middleware again. Therefore, middleware is not a viable option for us. We also tried to use the fs library to read the cache tags from a static file in the middleware, but using fs in middleware isn't possible. The content is dynamic, which means our cache tags are dynamic and cannot be hardcoded into the Next.js configuration.

[nsmith7989]

Almost identical to our use case: Our API layer will return the cache tags for a given resource, a "page" may be composed of multiple resources and the cache tag is a location of the data.

We then stitch together all cache tags from API (deduped) and that becomes the header Edge-Cache-Tag that tag is used by our CDN to for cache clearing purposes.

For example if someone updates content in our CMS that is needs to clear the cache on any page that displays that data, the CMS will send a request to our CDN to clear that specific code.

[gnoff]

Thanks @ucola !

So it sounds like your pages are set up as dynamic pages, meaning you don't have any caching features active which cause Next to produce the pages at build time. Then you are using Varnish in front of Next so that only when a page expires does a new dynamic request hit the Next server. And then Drupal can invalidate cache tags and communicate that to varnish so that on the next request a new dynamic render will happen.

Is that an accurate description of what you want your setup to be?

If so, Is there a meaningful value you are getting out of the streaming capabilities of App Router? It sounds like for initial page load most of the time users will get an entirely static payload (even if it was generated without Next's static capabilities). And only during the MISS would any meaningful streaming occur.

Is there a reason using static pages isn't workable for this situation?

Also, for client navigations, are you caching the RSC payload similarly using varnish?

@mattvb91 @nsmith7989 If this sounds similar to your setup as well, would love to also hear from you here on the above points.

[ucola]

@gnoff our feedback

We attempted to use static export at the outset of our project. However, our specific requirements necessitate functionalities not supported by static export. We require Rewrite, Redirects, Headers, and Draft Mode, as well as API routes for POSTing FormData and retrieving data from secured APIs. Furthermore, we plan to implement on-demand page cache revalidation in the future.

Up until now, we have encountered numerous challenges with caching pages using the default Next.js cache. There have been some fixes related to this issue since version 13.5. To mitigate caching problems, we initially experimented with using the NGINX cache. However, this approach lacks the ability to revalidate routes or tags. Consequently, when dealing with pagination, we must revalidate each pagination path individually.

Now, with Varnish, we can leverage Drupal's 'TAG' cache functionality in conjunction with Next.js to effectively manage caching.

[ucola]

@gnoff any updates about the state of this issue? We would be happy to receive a short feedback

[Javimtib92]

We have the exact same use case 😓Is there any solution?

[andrekrakvk]

What capability are you aiming to achieve? (For example, "I want my web pages to be cached by the browser.")

We use a headless API as the backend that follows a page model approach (send in pathname as parameter). We use a catchall approach with dynamic routing and have no static routes. And we have two usecases

1. The API returns a 200 OK if the requested page cannot be found, but with information about the 404 page (which layout, text, header menu information etc). I want to set a statuscode for specific pages in a catchall route that is dynamically driven by the API.
2. The API returns some information that requires a different header. Our current usecase is to apply a custom CSP header when the API response contains a certain flag. This is due to third parties demanding a stricter CSP for pages with sensitive information, while for regular content pages, a less strict version is needed to keep things like Google analytics intact.

CSP is just an example of an header which you might want to set dynamically. I can imagine other headers, for example response headers from the API that you want to forward to the frontend for traceability (correlationid, idempotentcy, open trace id, x-sentry, x-service, x-app, x-team custom headers)

Which header or headers are necessary to coordinate this behavior?
the statuscode of the response, content-security-policy content-security-policty-report-only

Why are middleware and static headers insufficient?
Static header is not sufficient because the FE has no knowledge about which URLSs there are and what the CSP might be (configurable in the backend)
Middleware might work, but would not be efficient. You would do the same (in our case BIG) API call in the middleware, the metadata, the page. Since the middleware lives on edge, Next will not cache it like it does with metadata and page (See the 'good to know' part of https://nextjs.org/docs/app/building-your-application/optimizing/metadata#dynamic-metadata)

[andrekrakvk]

Perhaps unrelated. But I wanted to mention it. When using clientside navigation (next/link), navigating to a page with different (CSP) headers does not work as expected. Since only javascript is loaded after the initial load with clientside navigation, the previous headers remain intact. A refresh on that page, loads the correct headers. I wouldve expected perhaps that Next would discover that the response headers are different and use a serverside navigation instead. This is the case with app and pages router

[ghankerson]

This part seems to behave as expected since your not loading the page again - just getting more data and updating the dom with it. You could get headers on the fetch/xhr request to get data though.

[gnoff]

@andrekrakvk it sounds like you conceptually could use Middleware if the performance characteristics were better. For instance if it could somehow share a fetch cache with the render so that if the page is not a 404 or whatever then during the render the saem big API call wouldn't need to be made. Does that sound right?

When thinking about setting headers from a render there is a before starting to stream and after. If the page is dynamically generated from a backing API and it's possible that no render should happen at all it would be best to model that as "before render". However if the tool you have access to for "before render" is going to be inefficient I can see why it'd be tempting to move it to during render.

In your particular use case it sounds like you only need to do this validation step (fetch the API and make sure you can respond with a 200) at the Root Layout level. Meaning it's not a feature you need access to at arbitrary layout depths or in the page file itself. Is that also correct?

Regarding the CSP needs, Middleware supports setting CSP headers and if you configure it to use a nonce then all the scripts that Next emits will be properly nonced. Similar to my ask above, if Middleware did not have the performance challenges it does when needing to do heavy IO woudl you still reach for custom headers if you could just configure these in Middleware?

[andrekrakvk]

@gnoff

It sounds like you conceptually could use Middleware if the performance characteristics were better. For instance if it could somehow share a fetch cache with the render so that if the page is not a 404 or whatever then during the render the saem big API call wouldn't need to be made. Does that sound right?

That sounds right, I think we could use the middleware if the fetch cached was shared with the middleware. From the pages router perspective this would be similar to doing the API call in the getServersideProps, followed by header adjustments and the passing the API response as object to the page.

However, I would feel that a cache like this is more hidden then passing a serverside prop object. It would help with debugging if somehow this cache hit or miss is clear if following this route. Some API calls you dont want to call twice. I understand that this can be solved outside Nextjs, but I mention it here as it's not an issue with the pages router approach. Something to keep in mind.

When thinking about setting headers from a render there is a before starting to stream and after. If the page is dynamically generated from a backing API and it's possible that no render should happen at all it would be best to model that as "before render". However if the tool you have access to for "before render" is going to be inefficient I can see why it'd be tempting to move it to during render.

I find this hard to follow because the streaming proces is hidden behind Next. It's not something I see. How would I model doing the API call and set the headers in a 'before render'. That would be the middleware or the getServersideProps right?

In your particular use case it sounds like you only need to do this validation step (fetch the API and make sure you can respond with a 200) at the Root Layout level. Meaning it's not a feature you need access to at arbitrary layout depths or in the page file itself. Is that also correct?

Correct. We only need to do the API call and send the header at the highest level, before any rendering. I can't imagine a usecase in which you want to adjust the response headers on a deeper level (component rendering).

Regarding the CSP needs, Middleware supports setting CSP headers and if you configure it to use a nonce then all the scripts that Next emits will be properly nonced. Similar to my ask above, if Middleware did not have the performance challenges it does when needing to do heavy IO woudl you still reach for custom headers if you could just configure these in Middleware?

Yes I could configure them in the middleware instead. But I would be mindful of not having a large function with all the logic in 1 place (cognitve complex). Perhaps in a more composing matter (something like this https://stackoverflow.com/questions/76603369/how-to-use-multiple-middlewares-in-next-js-using-the-middleware-ts-file) . The catchall approach of our application enforces that for us anyway (we have 1 getServersideprops).

But if I could express a preference, I particalurly like the generateMetadata api. One could say that metadata is something you want to set once (at least for some of the metadata), and only serverside (you dont want to set nofollow for example client side or change it once rendered). So in that sense it shares some characteristics with a header. I would not mind a generateHeader method. So that could also be a way, atleast for CSP (I think CSP also exists as meta tag).

[ryami333]

woudl you still reach for custom headers if you could just configure these in Middleware

@gnoff I would just like to add that for my use-case middleware was not appropriate because I can't actually derive the actual response status-code in middleware (because NextResponse.next() returns a generic/fake 200 response object). So when I was trying to set custom Cache-Control headers on certain routes I wasn't able to exclude 404 non-existing pages/routes.

Put another way: the problem with middleware is in the name: it's in the middle, and therefore has no context of the app's response otherwise.

[ghankerson]

Your reasoning on streaming content makes sense, but when you run a public website where content is usually the same but occasionally updated and you want to use a CDN - the app router almost leaves you without options.

1. What capability do you want to achieve? (i.e. I'd like my pages to be cached by the browser)

Here is what I am looking for

Cache-control: public, max-age: 60
Etag: abc123xyz 

So in this scenario I want the browser to send an if none match header to the CDN with etag in this case abc123xyz. If the 60 seconds have not expired, the CDN just says nothing new here and sends a 304 not modified response.

If it's been over 60 seconds the CDN then contacts the site sending the same if none match header and then the site sends a response if the etag is still the same from the webserver ( abc123xyz in this case), the CDN still sends a 304. If the etag from the server has changed then the CDN sends the new content to the browser and the 60 second cache starts over. (Of over the cache ttl doesn't have to be exactly 60 seconds this is just an example - it can be 120 seconds or 600 seconds - or whatever the developer decides is best).

2. What header or headers are necessary to coordinate this behavior?. Cache-Control and Etag

3. Why are middleware and static headers insufficient?

As far as I can tell there is no way to do this in the app router. Middleware let's you set Cache-control but if you set Cache-Control in middle it wipes out the etag. Since Middleware runs before the response there isn't a good way for me to set an etag based on the content of the page being served. I understand app router is trying to stream content as it becomes available, but that is at odds with what you need to serve content via a CDN in my view.

As far as I can tell on app router I can either get Cache-Control: private; max-age: 0; must revalidate and no etag OR I can get an et tag with cache-control: public; s-max-age: 31,600,000. (one year!) OR override cache-control in middleware but then get no etag.
This is really inflexible.

If you think I'm doing it wrong - let me know as it is - I might go back to pages router.

It seems app router is great for an app that doesn't use a CDN and servers customized content to a logged in user but when you want to serve the same content to everyone and use a CDN you are out of luck.

Can't emphasize enough how much setting cache-control in middleware nuking the etag is a disappointment and a problem. If setting cache-control in middleware didn't clobber the etag then there would be a solution.

[gnoff]

@ghankerson Thanks for your feedback!

It sounds like you are doing dynamic renders and then want to cache the results in a CDN and that streaming isn't particularly relevant to your use case. Is that right?

Is there something that makes ISR not suitable for your application?

One thing to consider is that if you are streaming a response to your CDN and caching it you are actually caching the stream which includes things like fallbacks, as well as script tags to reveal the primary content. Since you are caching the page it would be preferable if you could cache the final resolved state of the page so the intermediate states and extra javascript instructions aren't sent along to everyone who gets a cache HIT. Using the static generation features of Next should get you that behavior out of the box I believe so if you've run into trouble with taking advantage of this it could be really interesting for us to learn about how and why

[ghankerson]

Thanks for the comments. Really appreciate it. Haven't gone down the path of ISR mostly because we have historically done dynamic publishing and used http caching to good success and haven't completely wrapped my head around ISR. I'm not against it.

I am not really looking to regenerate a page after x seconds so much check if it is stale after x seconds and regenerate if it's stale.

Does app router support the On demand regeneration. That would take some work with our CMS team to send a revalidate request on publish of updated content but would give us all the benefits of static with dynamic updates.

I'll start testing ISR as soon as I can but have a big deadline next week so it might take me a while.

[ghankerson]

From what I am seeing ISR still won't generate cache-control headers with max-age.

[ghankerson]

So i have implemented ISR on one route on our site. Here is an example: https://www.thecurrent.org/song/the-current/708443. This is a route that I can afford to cache for a long time as updates to content are not frequent. Here is the issue: the etag varies per Kubernetes pod (we typically have 6) so the CDN caches it per pod. How can I assure the same etag per pod or just set the etag myself?

[nicholasgriffintn]

Just in terms of "What makes Middleware and or static headers insufficient":

• The middleware file is too early.
• Using it for some purposes may slow down your entire app to a halt
• The API is messy for anything that doesn't effect all pages (targeting individual pages would require a massive if statement)
• It doesn't have the ability to set headers based on page specific data (at least not in a readable manner)
• Controlling pages outside of the reason (code) for that control is a smell and asking for trouble
• It doesn't have access to Node APIs

[gnoff]

Hi @nicholasgriffintn thanks for commenting! I appreciate that there are situations where Middleware doesn't work for everyone however I'd like to keep the discussion focussed on use cases rather than our current or potentially new APIs.

Do you have use cases that would be enabled by having the ability to set custom headers during a render in App Router?

[rashidul0405]

We have two use cases:

1. Ability to set the Last-modified header for every resource for SEO benefits. This cannot be resolved through middleware because we do not know the last modified time until we fetch the data from the API backend.
2. Most of the articles are behind a paywall. For a specific URL, such as this one, the server can have two versions of the response. Visitor will either see the paywalled version or the full version, and which version to deliver is determined by the JWT auth cookie. By default, the App router marks these as dynamic responses with no cache. We have a Cloudfront function that extracts information from the JWT cookie and sets an appropriate cache key. In other words, Cloudfront can cache two different versions of a particular URL based on whether the visitor is subscribed or not. This issue might be resolved through middleware but would mostly involve static cache-control headers for all, lacking fine-grain control.
   UPDATE: (2): Looks like it's not possible to set cache-control header from middleware. @gnoff

Both can be solved using dynamic metadata. The way we set meta, we can set headers?

[backlineint]

What capability do you want to achieve? (i.e. I'd like my pages to be cached by the browser)

At Pantheon we're looking to preserve the CMS publishing flows (through WordPress and Drupal) that our customers expect while pairing those CMSes with Next.js (and other front-end frameworks). So at the highest level, our use case is that we would like to be able to invalidate dynamic Next.js routes from the CDN based on cache tag values included in a custom Surrogate-Key response header.

When using either Drupal or WordPress as a backend, our customers can enable the Pantheon Advanced Page Cache module/plugin to include this cache tag data on responses, including the data APIs provided by either CMS. When content is updated in the CMS, the Advanced Page Cache plugin will issue a purge request to our CDN which will revalidate any route dependent on the provided cache keys - both for the CMS providing that data, and the Next.js route consuming it.

The following documentation provides some more detail on how we’ve implemented this in our Drupal and WordPress Next.js starter kits using the pages router:

• Drupal and Next.js
• WordPress and Next.js

While we’ve focused on WordPress and Drupal due to our existing user base, we see this approach as something that should be able to apply to any content source.

This doesn’t prevent us from also supporting framework specific solutions to this problem like On-Demand Revalidation, but generally we prefer to put more reliance on the CDN than inside the application. Being able to offer a consistent cache-tag based invalidation strategy across the entire platform also opens up some powerful possibilities for our users. We’d like them to have this option with Next.js. This is possible today with the pages router, but not yet practical from our perspective today using the app router.

What header or headers are necessary to coordinate this behavior?

Cache-Control, Pantheon-Skey

What makes middleware and static headers insufficient

Our prototypical customers are

• Publishing content multiple times a day/hour
• Composing their websites through a number of plugins/modules/components

Frequently publishing means that it is impractical to set cache tags statically, or in a way that requires a front-end code deployment. The cache tags on the homepage in any given minute might change in the next minute when another piece of content is published.

Soon after the app router became stable we looked at implementing this in our Next.js starter kits for WordPress and Drupal. We encountered similar problems to others in this thread.

Middleware runs too early for many of our use cases. Certain data fetching (for instance, does a given page need to fetch the data for a sidebar of recently published articles in a taxonomy term?) will only be knowable after rendering starts.

If we were to use middleware, it would be necessary to move all data fetching out of components and into the middleware file. There can also only be a single top level middleware file, which means that all data fetching would have to happen in a single middleware file, or we’d have to invent some convention to be able to import modules from elsewhere in the application into the middleware. Either way, we don’t see any of these approaches as something we can broadly recommend to customers and expect them to reliably implement.

I/O that happens during Middleware needs to finish before rendering can start, and then may need to be repeated while rendering.

We encountered this as well. At the time we decided to set this research aside we still needed to make a second redundant request outside of the middleware. It might be possible to solve this via caching or something similar, but we didn’t get that far.

Additional comments

We’re seeing more users using the app router, likely as a side effect of it being presented as the default in the Next.js cli and in documentation. While some of these cases can be solved by the pages router, redirecting them that way to solve these problems seems impractical if app router usage continues to grow. Especially with likely high-visibility features like partial prerendering on the horizon.

Appreciate all the discussion here — happy to provide any additional information that could help.

[jordanmaslyn]

I would second this use case. Being able to dynamically build up cache tag headers based on sourced data (whether that data is sourced at build-time or on-demand) is pretty critical to the adoption of this architecture.

We have found a similar limitation even in the pages router with getStaticProps pages, where there is seemingly no hook to be able to dynamically configure the response header for a static page (despite all of that information being available at the time of generation).

[ghankerson]

I'm giving up on app router for now. I've tried to make it work but I can't figure it out. I thought incremental static regeneration would get me there but I am finding I get different etags per Kubernetes pod so this makes using a CDN very difficult. This is disappointing because lighthouse scores using Next 13 are much improved. At the end of the day though I am seeing too much server load largely due to the inability to use a CDN effectively. Maybe this all gets ironed out soon and I can return to the app router.

[homburg]

Hi @ghankerson

Did you try using a shared cache for your ISR renders? https://nextjs.org/docs/app/building-your-application/deploying#configuring-caching I'd guess that helps with the different etags per pod

[ghankerson]

This is new so not yet! But actually somehow I am now getting the same etags across pods without doing anything to try to make that happen.

[amannn]

I have a related use case that I've opened a separate discussion for: #58303. I'll rephrase it to match the format of this discussion.

What capability do you want to achieve?

I'd like to use an appropriate cache-control response header, but my app uses certain request headers that when read, opt the page into full dynamic rendering (see #58303 for examples). Overwriting the cache-control header would be one option, but maybe a safer option would be to be able to mark certain headers as not affecting the response, enabling ISR for these cases.

Another use case is caching of pages with search params (e.g. /songs?sort=name,asc). Currently usage of search params in Server Components opts into full dynamic rendering too. Using search params in client components is the suggested alternative, but this prevents me from using search params for data fetching (and generally requiring more components then necessary in the client-side module graph).

Something like an opt-in const dynamic = 'force-isr'; would help here.

What header or headers are necessary to coordinate this behavior?

The cache-control response header.

What makes Middleware and or static headers insufficient

cache-control can't be set on responses as Next.js overrides this.

[danigrandem]

Im usgin the middleware to add the Cache-control tag, more or less it does the job, although I would like to be able to add a ttl depending on the page. But now I'm facing another issue... I'm caching the 404 pages triggered by notFound() method in the components. Is there any way to detect if the page is a 404 in the middleware to avoid the cache?

[Livog]

In my project using Next.js and a Headless CMS, combined with Cloudflare, the primary goal is to optimize content updates through an efficient purging strategy. To achieve this, I'm planning to use cache tag headers, such as 'global-${block.id}' for global blocks and 'page-{$page.id}' for pages, based on the CMS's response. These tags are crucial not just for caching but more importantly for purging. They enable selective clearing of the cache, allowing me to specifically target and purge only the content that has been updated. This approach is vital for maintaining content up-to-date with related pages or entities within the CMS, ensuring that any updates are reflected promptly without needing to purge the entire cache. This approach, if I could set headers directly through Next.js App Router, would provide the simplest solution while also allowing me to leverage tiered caching in Cloudflare.

[Luluno01]

What capability do you want to achieve? (i.e. I'd like my pages to be cached by the browser)

I would like to precisely control the caching behavior of Vercel network and/or the browser by telling it when a page is finalized and becomes immutable.

In my case, I have a "task" object fetched from the database (not via the fetch API). It has 3 states, created, running and finished. When it is in created or running states, I would love it to not be cached because it might change its state at any time. But when it is in finished state, it is finalized, and I would love to cache the entire page for as long time as possible.

What header or headers are necessary to coordinate this behavior?

Cache-Control.

What makes Middleware and or static headers insufficient

Fetching requested "task" objects inside the middleware to determine if it is finalized is impossible and does not sound like a good engineering practice. 1) The database SDK I am using does not run on Edge Runtime. 2) Even if it is possible, it would introduce unnecessary latency due to fetching the same "task" objects twice.

[ghankerson]

Just wanted to post a note here that you can get http headers on Next's app router set like this

 curl -I https://www.thecurrent.org/feature/2023/12/26/coffee-break-from-jingle-bells-to-cowbells               prod
HTTP/2 200
content-type: text/html; charset=utf-8
content-length: 128554
date: Tue, 26 Dec 2023 15:15:50 GMT
server: Apache
x-apm: AWS
x-nextjs-cache: STALE
x-powered-by: Next.js
cache-control: s-maxage=120, stale-while-revalidate
etag: "igdtzvbbki2r5a"
x-content-type-options: nosniff
vary: RSC,Next-Router-State-Tree,Next-Router-Prefetch,Accept-Encoding
x-cache: Hit from cloudfront
age: 24

To do this you just have to add this to your page.tsx/page.jsx file:

export const revalidate = 120;
export const dynamic = 'force-static';

The only issue now is I get different etags sometimes per AWS EC2 instance.

The problem for me was the nomenclature in the Next documentation. What I think of is http caching or maybe page level caching is not called this in the documentation. The documentation talks about 4 kinds of caching but never http caching https://nextjs.org/docs/app/building-your-application/caching if I am not mistaken.

[ryami333]

This is definitely not incorrect, but implicitly the target audience of this discussion thread is (or includes) users who explicitly don't want their Cache-Control (or other headers) to be derived from their Route Segment Config, for various reasons.

[dhmacs]

What capability do you want to achieve?

I'd like to use a CDN. For example I have a product page, and I want it to be served by the CDN (using a stale while revalidate approach). The page is forced to be dynamic because it access the variant search param.

What header or headers are necessary to coordinate this behaviour?

Cache-Control (e.g. Cache-Control: public, s-maxage=60, max-age=60, stale-while-revalidate=3600)

What makes Middleware and or static headers insufficient

The fact that Next.js overrides Cache-Control. It also seems like stuffing middleware with conditions on how to set headers in various urls would be a bad DX (and costs more because now you're introducing edge functions into the cost equation)

[ghankerson]

Did you try adding these?

export const revalidate = 60;
export const dynamic = 'force-static';

[dhmacs]

I've read your suggestion and I thought it was interesting, but probably not suitable for our use case. The reason is that we're also setting the cache-control header conditionally based on a search param (this is done so that the team can bypass the cdn cache — maybe draft mode could be used instead? 🤔 ). We're also reading headers (this is being used to pass the domain of the API server, and it's used by the API server devs to test new APIs).

Just as a thought experiment, let's suppose that I can do without headers and the bypass search param, what would be the consequences of static rendering here? I suppose that product variants urls would not be server rendered?

[Saturate]

We also run into the need to set the Cache-Control header. We are using both NextAuth and Cloudflare. In the login flow the path api/auth/csrf is called, but due to it being behind cloudflare it's being cached (https://developers.cloudflare.com/cache/concepts/default-cache-behavior/) as there's no Cache-Control header, breaking the login flow.

[Luluno01]

I think in your case you should be able to disable caching of api/auth/csrf endpoint on Cloudflare side by setting a page/cache rule or something. Alternatively, just append a unique query string to the URL, e.g., api/auth/csrf?_t=1706267794992&_rnd=5ff39c26, so that it is guaranteed to bypass the cache.

[mattvb91]

appending a query string does not solve the issue at all. Now youve got potentially sensitive information in varying circumstances lying in a publicly accessible cache if one was to scrape through it...

[Luluno01]

Yes you are correct when it comes to more general scenarios. We should definitely disable CDN caching on pages that contain sensitive data to prevent leaking the cached page to unauthorized parties. But in this particular case, I don't see the danger of leaking cached CSRF token. Please correct me if I missed anything. Thanks!

[jamesarosen]

What capability do you want to achieve?

I'd like to perform server-side authentication or identification using a mechanism that may set cookies, e.g. because it has refreshed an access token and wants to pass the new version down.

@auth0/nextjs-auth0's getSession has this note:

Note: You can't write to the cookie in a React Server Component, so updates to the session like setting the expiry of the rolling session won't be persisted. For this, we recommend interacting with the session in the middleware.

What header or headers are necessary to coordinate this behavior?

Set-Cookie

What makes Middleware and or static headers insufficient

Middleware is a poor fit for two reasons:

1. I have to resolve the session in the page.tsx anyway to extract properties (like user_id). Having to also resolve it in middleware will impose an undue performance burden (since middleware run in a different process and can't share objects with pages). At best, I could resolve the session in the middleware, then attach signed headers to the request. Even that will require extra cryptographic processing on the request, adding at minimum a few ms.
2. only some routes require authentication. Middleware would be an OK fit if I could define multiple middleware so that I could target the requireAuthentication middleware to exactly those routes, but there's still a high-coupling / low-cohesion issue.

Static headers are insufficient because this header must be unique per user and changes over the life of their session.

[tyaan]

Hi I'm very late here, but I am having this exact same issue now. I'm pretty new to next.js and app router and figured there would be a standard way to do this, but I have spent the last 2 days trying to find a way and am yet to find one.

I just want my server component to do a simple validation check with JWT token cookies, and redirect to login page is validation fails. When refresh is required, it needs to make a request to my back end with the refresh token cookie, receive the new access token in response and then attach that new access token cookie to the response to the browser along with the page content, or redirect to login page if the refresh failed. But... there's no way to set response headers in a server component? I can't find a way to get that new access token cookie back to the browser.

It looks like in page router you could edit response headers in getServerSideProps, but there's no equivalent in app router. I've seen a few people recommending middleware, but the next.js docs state very clearly that it's not a good fit for session management, the whole refresh token request to the backend is just too slow to happen in middleware.

Does anyone have a solution for this? I feel like I must be missing something, it seems unlikely that it's just impossible to do JWT refresh using app router, I feel like this is quite a common thing?

@jamesarosen what did you end up doing for your project?

[jamesarosen]

the whole refresh token request to the backend is just too slow to happen in middleware

I'm not sure why this would be the case.

Consider this diagram from Auth0's What Are Refresh Tokens and How to Use Them Securely docs:

In the diagram above, SPA = Single-Page Application; AS = Authorization Server; RS = Resource Server; AT = Access Token; RT = Refresh Token. Image copyright Auth0

The SPA sends the refresh token to the Authorization Server to exchange it for an Access Token. The could happen in NestJS middleware -- though I'd recommend avoiding that flow on public resources like .css files.

what did you end up doing for your project

I moved the application to Hono and Vite. NextJS doesn't offer the extensibility I want in a a web application framework.

[tyaan]

Oh ok thanks. Maybe I just misunderstood the next docs. They say -

"Middleware is not a good fit for:

Slow data fetching
Session management"

I assumed this meant that a request to my backend api to receive a new access token would be too slow.

[jamesarosen]

I've been working in Nest for five years, but I'm not an expert. Here's my guess as to what they're saying:

Middleware is not a good fit for Slow data fetching

That's because middleware needs to complete quickly. It has a very limited timeout compared to serverless and long-running server runtimes.

Middleware is not a good fit for: Session management

It's less clear to me why they say this. One point is that middleware run on all requests (unless you configure them not to) and you don't want to do session management on asset requests like .css files. The other is that the middleware and the route handler upstream of it don't run in the same runtime. The only way they can communicate is via HTTP headers. So you can't create a session object in middleware, use it in a route, and then write it to a cookie in the middleware. This, by the way, is precisely what I mean when I say "NesJS doesn't offer the extensibility I want in a a web application framework." Web application frameworks should make it easy to extend with shared behavior like session management. If you're running purely on the app router, you might be able to put some shared logic in a root layout, but it's very limited by the inability to manage HTTP headers.

[tyaan]

Yeah ok thanks that all makes sense, you've just described all the things I tried and couldn't find a way to make it work properly (some combination of middleware and route handlers, or shared logic in root layout).

I've got it functioning in middleware now, but I'm still worried the requests to the backend will be too slow in production. It's also just worrying that the docs say "Middleware is not a good fit for: Session management", but don't really fully explain why.

I've started this as a separate discussion if anyone sees this and wants to weigh in. #79614

[jamesarosen]

What capability do you want to achieve?

I'd like to render flash messages that have been stored in a cookie (in another route.jsx file) in my layout.tsx. Then I'd like to clear that cookie (via set-cookie with an expires-at in the past) so they don't reappear on the next page transition.

This is all to support non-JS clients.

What header or headers are necessary to coordinate this behavior?

Set-Cookie

What makes Middleware and or static headers insufficient

Middleware is a poor fit because I only want to delete the cookie after having rendered the layout. It's also possible that other things in my system render HTML -- for example, a GET in a route.tsx that forwards to some other service. Thus, I can't simply unset the cookie if I'm rendering any HTML. I would have to maintain an explicit list of all the pages that use that layout.

Static headers may be a good fit for this if they have append semantics, but they are a poor fit if they have set semantics.

[Pruxis]

What capability do you want to achieve?

I'd like to secure embeddable content for a multi-tenant application.

What header or headers are necessary to coordinate this behavior?

X-Frame-Options

What makes Middleware and or static headers insufficient

Static headers are insufficient as our goal is to provide this functionality for each potential tenant on our SaaS.
Middleware it's possible to achieve this by performing an additional fetch on each request of those specific pages, this adds unnecessary latency as the required information is already being fetched to render the page.

[lapduongbkit]

Hi @Pruxis

I’ve encountered a similar situation, and my solution involves using cookies to store the necessary Content Security Policy data. By doing so, the middleware can directly access this information without making additional requests. Although there are additional redirects to initialize the cookies, once the cookie is set, it remains valid until changes occur.

Have you tried any other workaround for this issue that you can share?

[errnesto]

What capability do you want to achieve?

We have a route /resource/[id] where for some resources we do an expensive ip authentication step.
We only know which resource needs authentication after fetching some information about it.
And we only want to authenticate resources that need this step.

After we did authenticate the users ip we want to store the authToken in a cookie. So we don't have to authenticate again.

What header or headers are necessary to coordinate this behavior?

Set-Cookie

What makes Middleware and or static headers insufficient

We would need to fetch the resource information in the middleware for all resources under this path.
Authenticating all resources would be expensive and the extra fetch is a uncached performance hit.
Also getting out all the parts of the route path in the middleware again, means we almoast would write our own router just for the middleware.

[errnesto]

A workaround would be to trigger a api route that sets this cookie. This could be triggered after page load via js. Or a redirect (that is triggered when the cookie is missing) to an api route that sets the cookie and then redirects back. But both solutions are not ideal. I also don't like to set an auth token via client side cookies…

[c0d3rm0n]

I have a problem that is a bit similar (#64346). I have to set a cookie in raw format and cookies().set({...my_cookie}) will automatically set the encode option to encodeURIcomponent, and this causes my project to fail as I need to use 3rd party libs that define / use those cookies.
The only way I found to set them with encode option was to flow next.js example and set the cookie using a serializer in an api route, and this way isn't very nice...
I agree with ernesto as sending auth cookies to client and set them by API isn't the safest way to handle this.

By the way... Is there any way to set encode option in cookies from next/headers?

[slimshreydy]

I'm aiming to use the Server-Timing header-based API, which is the recommended to debug high TTFB applications (https://web.dev/articles/optimize-ttfb#understanding_high_ttfb_with_server-timing). This requires me to be able to measure the time taken to perform certain DB calls during the RSC render, and then supply Server-Timing headers with the elapsed times. This integrates with the Network view on most browser dev consoles, making it one of the easiest ways to debug TTFB.

I understand this use case is likely impossible given the RSC streaming, so I suppose I could also log timings to a central logging application and then set up a pipeline to extract timings on those logs, but that feels a bit overkill.

[eschaefer]

Our use-case is to set an X-Content-Age header for an article page, depending on the article's age rating. This comes back with an API response. The place I would expect to be able to set this:

import { headers } from 'next/headers';

async function ArticlePage({ params }) {
  const res = await fetch(`/some-api/articles/${params.id}`);
  const article = await res.json();

  const headersList = headers();
  headersList.set('X-Content-Age', article.minAge); // currently not possible

 return ...
}

export default ArticlePage; 

This is pretty unmanageable at the middleware level

[hieupham2010]

I have the same issue. Do you have any solution?

[manavm1990]

Not really a thing for me @eschaefer , but just some suggestions to take or leave.

Would you want to use a Route Handler to set that ?

async function getArticle(id: string) {
  const res = await fetch(`https://your-api.com/articles/${id}`);
  return res.json();
}

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const article = await getArticle(params.id);

  return NextResponse.json(
    { article },
    {
      headers: {
        'X-Content-Age': article.ageRating.toString(),
      },
    }
  );
}

And from the page, call that Route Handler ☝🏾 :

async function getArticle(id: string) {
  // Have the route handler fetch the article and set the header ☝🏾 
  const res = await fetch(`http://localhost:3000/api/articles/${id}`, { cache: 'no-store' });
  
if (!res.ok) throw new Error('Failed to fetch article');
  return res.json();
}

export default async function ArticlePage({ params }: { params: { id: string } }) {
  const { article } = await getArticle(params.id);
  const headersList = headers();
  const contentAge = headersList.get('X-Content-Age'); // It's there from the Route Handler...

[hieupham2010]

It doesn't work @manavm1990.

async function getArticle(id: string) {
 // the response header 'X-Content-Age' is here!
  const res = await fetch(`http://localhost:3000/api/articles/${id}`, { cache: 'no-store' });
 
if (!res.ok) throw new Error('Failed to fetch article');
  return res.json();
}

It can't access from headersList.get('X-Content-Age') in ArticlePage. I don't know but, in my case, I want the response header of ArticlePage that contains the 'X-Content-Age' not just the response header of getArticle API.

[eschaefer]

@manavm1990 yeah unfortunately that won't work. Headers from a GET request don't automatically make it to to the page response. Of course the header is there on the GET response, but that's no different that calling any other GET api endpoint. The page response headers do not get set there.

[maslowivan]

Will bump this topic

What capability are you aiming to achieve? (For example, "I want my web pages to be cached by the browser.")

1. We have a category /mens-jackets with product X. When we update this product's price, we need to drop:
   • /mens-jackets and every other category containing this product
   • The /product URL itself
   • We have 36 stores, so for example: /de/product, /ca-fr/product, /eu/product, etc. — meaning the product URL × 36 + category URLs × 36.
   • Additionally, every product page can have related products or recommendations linking to other product pages. We need to find all those related products and multiply their URLs by 36 to drop the cache for them as well.
   • Now imagine each category having paginated views (?page=xxx) and feature-flagged versions (?exp1=a and so on).
   • So we may have thousands URLs to drop here but CDNs usually have the limits.
   • This can be solved with the Cache-Tag header.
2. The CDN can have its own cache timing rules. For example, we may not want the browser to cache a page, but we do want it cached at the CDN level (where we can easily purge it if needed). Examples: Fastly’s Surrogate-Control or Cloudflare’s CDN-Cache-Control.
3. We need some static assets/images to be manually included in Early Hints to speed up site rendering. The Link header is useful here.
4. We need a custom header for the CDN to signal that we can stop downloading the rest of the response once this header is received.
   Example: X-Product-Status: archived in our case.

Which header or headers are necessary to coordinate this behavior?

• Cache-Tag
• Surrogate-Key
• CDN-Cache-Control
• Surrogate-Control
• Link
• Custom (e.g. X-Product-Status) used to mark a page as "archived" (HTTP code 410 Gone)

Why are middleware and static headers insufficient?

• Determining the cache tag would require fetching data from the API twice — once in middleware and once in the page.
• It’s useful to control CDN-Cache-Control dynamically via API responses, for example depending on whether a product is in stock.
• The Link header may depend on the page type — product page or category page. Both may share the same [slug]/page.tsx file, with an API rewrite deciding whether it’s a category or product.

Thanks @gnoff