Invoking from Forms and Handlers

## The call site A Server Action is an ordinary async function that only ever executes on the server, but that the browser is permitted to *call*. Next arranges for that function to be reachable from the client (how that endpoint comes into existence is a separate topic). What matters here is the consequence: at the call site you write no client-side transport code at all. There is no `fetch`, no URL string, no `Content-Type`, no `JSON.parse`, no error-status handling. You hand the function itself to the form. ```tsx // app/notes/page.tsx (a Server Component) export default function Page() { async function saveNote(formData: FormData) { 'use server' await db.note.create({ data: { body: String(formData.get('body')) } }) } return ( <form action={saveNote}> <textarea name="body" /> <button type="submit">Save</button> </form> ) } ``` ## Step by step **1. The submit is intercepted.** Once the page has hydrated, React handles the submit event rather than letting the browser perform its default form POST-and-navigate. You do not write `onSubmit` and you do not call `preventDefault()`. **2. FormData is built.** React serializes the form's *named* controls into a `FormData` instance. Only controls with a `name` are included, an unchecked checkbox contributes nothing at all, and every value is either a string or a `File` — there are no numbers and no booleans on the wire. **3. A POST goes to the current URL.** The request targets the route the user is already on, not some `/api/...` path, and it carries an identifier for the action to invoke plus the encoded arguments. Open the network tab during a submit and you see a POST to the page's own URL with an opaque body — that surprises people expecting a REST call. **4. The server runs the function.** It runs in the server runtime with whatever privileges that process has: secrets, database handles, internal services. The body of the function is never shipped to the browser, which is exactly why data access can sit inline in it. **5. The response is an RSC payload.** Not JSON, not a redirect, not a full HTML document. It is the React Server Components wire format, streamed back, and it can carry two things: the action's return value (which must be serializable across that boundary) and re-rendered server UI for the current route. **6. The router applies it in place.** React reconciles the incoming tree against the mounted one. The URL is unchanged, there is no navigation and no scroll reset, and any client component that is not unmounted keeps its state — a scroll position in a sidebar, an open dropdown, a `useState` value elsewhere on the page. ## Why a payload rather than JSON In the App Router the unit of update is a *server-rendered tree*, not a record. A REST endpoint hands you a row and leaves you to work out which parts of the UI now need to change; a Server Action response can carry the recomputed UI directly, which is why a mutation can update the screen without any client state management at all. One caveat worth stating plainly: the mutation running successfully does not by itself guarantee the *new* data appears. Whether the freshly rendered tree reflects your write depends on the relevant caches being invalidated — a separate concern with its own API, and the usual explanation for "it saved but the list still shows the old row". ## What still needs wiring The transport is free; the UX is not. The action's return value is available to you, but you have to route it into state to render a message; a pending indicator needs a hook to read the in-flight status; a reset or a focus move after success is yours to write. Those hooks are React's form and action primitives — the framework part being described here is only how the call travels and what comes back. ## Where teams get this wrong - Writing an `onSubmit` handler *and* an `action`, then wondering why the flow runs twice or not at all. - Returning something non-serializable from the action — a class instance, a function, a database cursor — and getting a serialization error rather than a value. - Assuming the code in the action is somehow "shared" and worrying about it leaking; it is not in the client bundle. - Assuming a full page reload happened, and re-fetching or re-initializing client state defensively after every submit.