Next.js 13.5: Server Actions & Router Cache

What I learned about Server Actions and Router Cache in Next 13.5 and a reminder of the importance of source code access to augment even the best documentation.

Our application is using React Server Components and the App Router and Server Actions features of Next 13.5. Its on the cutting edge. 🗡️ When stuff doesn’t just work, I figure it’s on me to go beyond Reading the Fine Manual to really understanding the processes, inputs, and output of the software I’m building.

Reading the documentation about content caching in Next is a joy. Like all Next documentation, the writing is clear, concise, and filled with information “Good to Know” that guides readers down a best-practice path. However, like most documentation for code, it doesn’t answer every question a curious developer may imagine - nor does it need to, nor should it want to - and there may be issues in some use cases that are not yet addressed by the documentation. Access to the source code enables developers to move at their own pace, avoiding the risk of blocking adoption.

This felt like a defeat of the purpose of client-side code calling a light-weight Server Action to quickly add one item to a potentially large list and avoid another request for the whole page.

This post fits more squarely in the “curious developer” category, though the questions it addresses were raised in my mind as I used caching in anger. I would have been quite frustrated with Next if I had not been able to look at the source code to understand what I was experiencing. What I learned is interesting, but I need to provide some context.

How this started…

We have a Items server component that loads list items from the database and passes them to a ItemList client component. The ItemList renders on the server when the page loads so we see the list items HTML immediately and it maintains the collection on the client with useState to track client-side changes to the collection. The component uses Server Actions to add, update, and delete individual items in the database.

“List One” starts with three items rendered on the server. Clicking a button triggers a Server Action to create a new item in the database and return the new item data to the client, which then adds it to the collection of the ItemList. Reviewing browser network requests, Charles Proxy request tracing, and Next server logs, we see everything is going according to plan. The collection state change causes the component to re-render on the client. 😎

Server rendered ItemList of page /lists/1

Client re-rendered ItemList with new item added to collection state

Requesting page “List Two” at path /lists/2 presents the server rendered items from the other list.

Server rendered ItemList of page /lists/2

When switching back to the “List One” page, “Item A” is no longer present. 😳 Why wasn’t the new collection state retained and the new item still visible in “List One?”

Where’s the new item?

A hard refresh of /lists/1 brought the new item back into view.

This felt like a defeat of the purpose of client-side code to call a light-weight Server Action to quickly add one item to a potentially large list and avoid another request for the whole page.

Perhaps you already know what happened to the new item, and perhaps you also know the exact change necessary to achieve the goal, but did you know that as of Next 13.5, the fix has a surprising side-effect?

Router Cache

I don’t intend to reiterate the excellent Next caching documentation, but I’ll point out an aspect of the Router Cache that is relevant to my experience.

The Router Cache temporarily stores the React Server Component Payload in the browser for the duration of a user session

Revisiting page “List One” displayed the items that were originally provided to the ItemList, rendered by the server into the HTML document as <ul><li>…, which turns out to be the payload retained by the Router Cache for future client-side renderings of the components at /lists/1.

It wasn’t immediately clear how a page, React Server Component Payload, the ItemList client component, and the Router Cache were all related, but the documentation made it clear that a cache needed to be cleared.

Cache Revalidation

Next cache management APIs are elegant and conform to web terminology. revalidatePath correlates to the HTTP response Cache-Control header directive must-revalidate and the first line of an HTTP request message, which contains the request method and resource path (i.e. GET /path). The additional API revalidateTag makes it easy to revalidate one or many paths associated with a particular tag.

must-revalidate is a directive to caches, whether they reside in the user’s browser, the corporate proxy, or any number of other devices between the server and the content consumer, indicating to them that the resource they’re caching must not be delivered or presented once it becomes stale; those caches must revalidate the content.

The documentation led me to believe the Server Action code needed to be changed from this:

export async function addItem(listId: number) {
  return createNewItem({ listId, title: 'Item A' })
}

To this:

export async function addItem(listId: number) {
  const item = await createNewItem({ listId, title: 'Item A' })
  revalidatePath(`/items/${item.listId}`)
  return item
}

It worked. Moving between lists did not lose changes that were made to the items. This was the fix I needed, but it led to changes in how the client interacted with server, and I wanted to understand.

Curiosity Made a Blog Post

Being an executive doesn’t afford a lot of time for analysis, but we’re wearing the developer hat. 🤠 Curiosity, questions, and experimentation are allowed!

• What values were in the Cache-Control header of the original page response that had the SSR content of the list?

• How could the response for the Server Action - a function that only added an item to the database and returned that item in the response, which I verified after coding and testing the page - have any impact on the original response content that was stored by the Router Cache?

• Was the complete collection being re-fetched in another request for the page after the Server Action returned? That’s load on the server we’re trying to avoid, and the client is doing more work.

• Does this mean we don’t really need to leverage useState in the ItemList client component, if a new server request is issued to re-render the page?

• Why did a change to “List One” lead to a new request to the server for “List Two” when moving between those pages (and changing “List Two” now caused another request for “List One” content)?

To save you and I both some time, I’ll lay out what’s happening to answer these questions and leave it to you to decide how deep you’d like to go into those questions.

What I Learned

Starting from the beginning, before I added revalidatePath:

• The page is dynamically rendered because it uses the headers() function to load the JWT session token. Everyone will receive different content, and the content is highly likely to change between requests. There will be no server-side caching, and proxies should never cache the content. The response headers will always include Cache-Control: no-store, must-revalidate, where no-store directs all caches not to store the response.

• Next Router Cache always caches the content of React Server Components. In our app, the List server component loads the item collection and passes it to the ItemList, which is initially rendered on the server and delivered as HTML when we hard-refresh “List One.” The ItemList is re-rendered on the client when we call the setCollection function provided by useState (adding a new item returned from the Server Action), and re-rendered again when we switch between “List One” and “List Two.” This render uses the collection originally provided by the List server component that was stored in the Router Cache; it looks like we lost our item.

• The Server Action does its job by adding an item to the database and returns a single object in the response JSON. This is what I expected and longed for, keeping the action lightweight and fast. It also includes Cache-Control: no-store, must-revalidate in the response header.

• The Server Action response includes another curious header, x-action-revalidated: [[],0,0]. 🤔

After adding revalidatePath, the UI continued to show the new item when moving between the “List One” and “List Two” pages, and no additional request was made after the Server Action response, which is the desired outcome. I needed to understand!

Here’s what I observed:

• The Server Action started returning the complete collection of items in the JSON response (in fact, the response bodies are Content-Type: text/x-component, a serialization format I believe is Apache Arrow Flight).

• The Server Action response x-action-revalidated header changed to the value [[],1,0]. 😯

• In fact, the response contained the item collection value that is generated in the List server component and passed to the ItemList client component, serialized! Wow. Doesn’t this mean that when the Server Action was changed to add a single line, revalidatePath, the framework re-rendered the List component on the server and took the values of properties passed to the ItemList and returned them in the response?

• Searching the Next codebase for that header I found the addRevalidationHeader() server function. Here is where I was surprised to find an undocumented, unexpected side-effect; stay tuned. I also found the Server Action client code that handles the action response and particularly, that header.

• That led me to the client code applyFlightData() where fillCacheWithNewSubTreeData() is called, doing the work of updating the Router Cache content for the component with the complete collection returned from Server Action, avoiding a need for another request. 🤯

This feels rather magical, and I want to kiss it. 😘

Surprise

There was one catch, the surprise I continue to mention, and the reason I’m thankful for source code access when my curiosity exceeds my desire to write more code.

After adding revalidatePath, I noticed that after adding an item to “List One,” then moving to “List Two” would cause a new request for the content of “List Two.” That’s not ideal because nothing changed in “List Two” and wasted work was performed.

The source code reveals that revalidatePath, when used in a Server Action, completely invalidates the Router Cache, erasing every bit of content so far fetched, requiring the client to re-fetch all Server Component content. 😳

In fact, there were two requests for “List Two” content, going something like this:

1. GET /lists/2?_rsc=1ugcv, with a response header content-type text/x-component, and body 0:["development",[["children","list",["list",{"children":["__PAGE__",{}]}],null,null]]].

2. GET /lists/2?_rsc=6dg7j, with a response header content-type text/x-component, and a body containing the complete item collection for “List Two” (also in the Flight format).

Moving to “List One,” there is another single request:

1. GET /lists/1?_rsc=36pmj, with a response header content-type text/x-component, and body 0:["development",[["children","list",["list",{"children":["__PAGE__",{}]}],null,null]]].

I eventually realized that these three requests were due to the fact that three server components’ content were erased from the Router Cache:

1. The Page component of “List Two”

2. The List component of “List Two”

3. The Page component of “List One”

There was no need to request the List component content for “List One” because it was returned in the Server Action response with the header x-action-revalidated [[],1,0].

Notice that our RootLayout component, which is rendered on the server, is not requested again. Layouts are not pages. They’re specially designed to maintain state across pages. revalidatePath is all about React Server Component content in the Router Cache.

Summary

I learned a lot about React Server Components, Server Actions, and the Router Cache. The documentation for these things is really good, but as I used them and observed their behavior together on a real project, questions were raised the documentation just didn’t answer for me. Only by experimentation and reading the code (okay, I also set some DOM mutation and network request breakpoints) was I able to develop a deep understanding of what the framework was doing for me and figure out why more requests were coming to the server than I expected.

I now understand that there is a current limitation in Next 13.5 that will cause clients to make new requests for everything generated by server components if we use revalidatePath in a Server Action. Perhaps we should should leverage useRouter and router.refresh() in the ItemList after mutating the list or items in it so we can avoid blasting the whole Router Cache. 🤨