perf: remove form state network requests

[jacobsfletch]

Exploration for #13753.

TL;DR:

It's possible to mostly, and in some cases, completely, remove the network layer from form state. However, this work isn't going to land in v4, mostly due to DX concerns, but could potentially land in a future major release. This PR will act research into the technical requirements of making this change.

Background

Since Payload v3, every single document event fires a unique HTTP request for "form state", which includes RSCs in its text/x-component response type—a primary responsibility of this endpoint. This is because server components, by definition, require a server to render.

This means that if you define a server component anywhere in your Payload config, we must go back to the server to render it, on demand, unless it was part of the initial page load. For example, when a field's admin.condition evaluates to true, a custom server component may need to render in as a result.

Within the edit view, this means we go to the server to process every change, because that change potentially require rendering server components, regardless of whether it truly does.

Solution

So the question becomes: do we need to do go to the server for every user action? Why can't we determine at build-time exactly which actions require rendering, and only go the server for events that specifically require it?

That's exactly what this PR explores.

Imagine a world where we make a server roundtrip only when a server component needs rendering. We only need to go to the server if the user's action requires a fresh server component to render, eliminating all unnecessary requests.

In this world, default Payload components, as well as custom client components, can be rendered on the spot, immediately. Even projects that heavily use server components at the field level, we only need to go to the server if the user's action requires a fresh server component to render.

Aside from the network and bandwidth savings, UX improvements of fulfilling user actions instantaneously is a huge win. For example, newly added array rows would no longer lazy load.

Technical Constraints

Easier said than done, however, as this approach has implications to custom client components, and more. This is largely due to the server/client boundary in RSC frameworks like Next.js, which restrict us from passing any non-serializable JSON across that boundary, including React components, functions, etc.

Getting around this constraint is not necessarily the problem, as we have existing patterns that achieve a similar goal through the "import map". For background, in v3 we established a fully Node-safe Payload config by stripping React components out of the config itself, and instead referencing them via file paths. When we need to render a component, we reference it via import map.

For example:

import type { Text Field } from 'payload'

const MyField: TextField = {
  type: 'text',
  admin: {
    components: {
      Field: './PathToMyComponent.tsx' // This shipped in Payload v3
    }
  }
}

So in theory, we could extend this approach and create a "client import map" that could be sent through the boundary. By doing this, we would have full access to the custom client components on the client, and can render them without going to the server.

Where this breaks down is this: other properties required of form state would need the same "file path" treatment in order to run on the client.

For example, fields are often behind conditional logic, require validations, or default values. To avoid going to the server to run these functions, they would need to exist on the "client import map", and consequently, be defined as file paths...not great.

For example:

import type { Text Field } from 'payload'

const MyField: TextField = {
  type: 'text',
  admin: {
    components: {
      condition: './PathToMyCondition.tsx',
    }
  }
}

This is obviously inferior to writing basic functions inline. We don't want to require file paths for all admin properties.

In the future, it's possible we could do this programmatically, however, this is a bundling problem more than anything. For example, we cannot simply lift these functions out into an external file. Things outside of the function's closure, like imports, local variables, etc., cannot easily be carried over. This is where the 'use client' directive shines.

Other implications

Here's a generally comprehensive list of all properties affected by this change:

• validate would lose its event arg, and would only run server-side validations on submit
• admin.validate would be a new property used to run client-side validations on change, defined as a file path
• admin.condition would now run client-side, defined as a file path
• defaultValue would force the field into server rendering even without custom components, as it requires a req arg and must run async

Looking ahead, we should also consider a future "realtime API" that might have implications to this work. For example, it alone would invoke a high volume of requests, one for each event, effectively reversing some of the gains of this PR.

This also ties into another broader point to me made, which is that form state network requests are not a big deal. For example, each request contains a relatively small payload, typically not exceeding a few KB of transfer.

Demo

Before:

Screen.Recording.2026-05-01.at.3.23.14.PM.mp4

After:

Screen.Recording.2026-05-01.at.3.14.25.PM.mp4