How it works
The client-side reference holds the action id. On a call, Next's callServer sends the encoded arguments with the id and the router state. The request I captured in Chrome (trimmed):
POST /rt
next-action: 0029b9e2e50ad98e248b2b8f8ee440c8327979b156
next-router-state-tree: %5B%22%22%2C%7B%22children%22%3A%5B%22rt%22…
accept: text/x-component
content-type: text/plain;charset=UTF-8
origin: http://localhost:3000
body: []
The server looks the id up in its server reference manifest, checks Origin against Host, decodes the body and runs the function. While it runs, revalidatePath, updateTag, refresh and cookie writes record that the route must be re-rendered. After it returns, Next renders the route for the state tree the client sent and writes everything into one response. For the path action (trimmed):
HTTP/1.1 200 OK
x-action-revalidated: 1
Content-Type: text/x-component
0:{"a":"$@1","q":"","i":false,"t":{"t":{"s":"","h":80,"d":{"r":["$","$2","c",…
1:"ret:path"
9:["$","main",null,{"children":[["$","p",null,{"id":"out","children":["v=",14," t=",1794204012984]}],…
Row 0 is the envelope: a points at row 1, the return value; t is the new tree, whose page segment resolves to row 9 with the new v. The same action without an invalidating call answered:
0:{"a":"$@1","q":"","i":false,"b":"E69shmJKgqAFGnl71Tc-l"}
1:"ret:none"
b matched .next/BUILD_ID. The header said what kind of update happened: 1 after revalidatePath, updateTag, one-argument revalidateTag or a cookie write; 2 after refresh(); absent after revalidateTag(tag, 'max') or nothing.
On the client, the router applies the tree as a navigation seeded with data it already has: nothing is fetched for the current route. Because client state lives in the React tree, a re-rendered page keeps its useState values (per the docs, not run here).
Edge cases
- Router cache. After
revalidatePath, updateTag and a cookie write, both browsers re-requested the prefetch of a <Link> to /other (GET /other?_rsc=…). After refresh() they didn't. The revalidatePath docs say an action's call refreshes every previously visited page on its next visit, and call that temporary.
- Cache Components on. With
cacheComponents: true, data from a use cache function tagged v, and the timestamp in a <Suspense> hole, every action gave the same headers and the same visible result as with it off.
- Errors. A thrown error comes back as an error row (
1:E{"digest":"…"}) in the same stream; see the errors question.
Real-world scenario
A "rename project" form calls an action that writes to the database and calls revalidateTag('projects', 'max'). The user saves and still sees the old name until they reload. The max profile is stale-while-revalidate: correct for a CMS webhook, wrong for the person who just made the change. updateTag('projects') expires the tag, the action's response includes the re-rendered page, and the new name appears with the save.
Trade-offs
Folding the refresh into the action's response removes a round trip and the window where the UI shows the mutation's result but stale page data. The cost is coupling: the action's response size depends on the route it was called from (a heavy page sends a heavy response), every invalidation clears the router's prefetched pages, and actions queue behind each other. Reads that don't mutate belong in Server Components or a route handler, not in an action.