React Reference ยท Concepts and Pitfalls
Server Functions
How React Server Functions work: async functions marked 'use server' that the client calls like local code, with serialization, security and form integration.
A Server Function is an async function that lives on the server but can be called from client code as if it were local. When a module or function is marked with the 'use server' directive, the bundler replaces its body in the client bundle with a small reference. Calling that reference sends the arguments to the server over HTTP, runs the real function there, and returns the result (or the error) to the caller.
When a Server Function is passed to a form's action or to a transition, React calls it an Action (a "Server Action" in older wording). Server Functions need framework or bundler support, so the code here is read-only; the live examples use a stand-in that behaves the same way from the component's point of view.
// actions.js 'use server'; export async function addComment(prevState, formData) { const text = String(formData.get('text') ?? '').trim(); if (!text) return { error: 'Write something first.' }; await db.comments.insert({ text }); return { error: null }; }
Try it
What happens on a call
- The client builds a request containing an identifier for the function and its serialized arguments.
- The server finds the function, deserializes the arguments and runs it.
- The return value is serialized and sent back. If the function returns UI, React can merge it into the page, and frameworks usually refresh the affected server-rendered data.
- If the function throws, the call rejects on the client. In an Action, the error surfaces to the nearest error boundary unless you catch it or return an error value.
Arguments and results use React's serialization format, which is richer than JSON (it handles Date, Map, Set, FormData, BigInt and promises) but still cannot carry functions, class instances or DOM nodes. Server Functions are always asynchronous on the client, even if the server function itself has no await.
Using them in forms
Passing a Server Function to <form action={fn}> gives you form submission without writing fetch. The function receives a FormData object. With frameworks that support it, the form works before JavaScript has loaded (progressive enhancement), because the browser can submit it as a normal POST. Combine it with useActionState for validation messages, useFormStatus for pending state, and useOptimistic for instant feedback.
Usage notes
- Every Server Function is a public endpoint. Anyone can call it with any arguments, even if your UI never renders the button. Validate input, check authentication and authorization inside the function, and never trust values that came from the client.
- Mark by directive.
'use server'at the top of a file marks all its exports; inside an async function body it marks that one function. It is not the opposite of'use client', and it does not turn a component into a Server Component (see'use server'). - Only async functions can be exported from a
'use server'file. - Calls run one after another by default in many frameworks, so do not use them for rapid parallel reads. Fetch data in Server Components instead and use Server Functions for mutations.
- Return small, serializable results, such as an error object or the new record, instead of throwing for expected validation failures.
- Closures: a function defined inline inside a Server Component can capture variables; frameworks serialize and protect them, but treat anything captured as visible to the client.
- Security headers and CSRF protection are provided by the framework. If you build your own integration, add them yourself.