Client-triggered mutations
Expose a server-side mutation such as adding an item to a cart while keeping database access on the server.
React 19+ · Directive
use server
'use server' marks an async server-side function as callable from client-side code. Client calls become network requests, with serializable arguments and results handled by the framework.
How it works
'use server' marks an async server-side function as callable from client-side code. A framework turns it into a server reference; calling that reference sends serializable arguments over the network and returns a serialized result.
Syntax
'use server'Parameters
| Name | Type | Description |
|---|---|---|
function arguments | Serializable values | Arguments passed to the async Server Function; they must use types supported by React serialization. |
Returns
A serialized function result delivered to the client; the function itself must return a Promise because it is async.
Key points
- It exposes a server-side function through a client-callable server reference.
- React's current documentation calls these callable server-side functions Server Functions.
- A client invocation performs a network request rather than executing the function locally.
- Return values cross back to the client through serialization.
- A file-level directive applies to every exported function in that module.
- Arguments must be serializable because they cross the client-server boundary.
- Wrap ordinary client-triggered calls in a Transition; form actions receive this handling automatically.
Common mistakes
- The directive belongs only in server-side files; it does not designate a Server Component.
- Only async functions can use the directive because invoking them requires an asynchronous network request.
- Validate and authorize every request before performing a mutation.
- Place the directive first, before imports or other executable code; comments may precede it.
Example: Module-level Server Function
// actions.ts
'use server';
export async function addToCart(productId: string, quantity: number) {
// Validate and authorize before mutating data.
return {productId, quantity};
}
// CartButton.tsx
'use client';
import {addToCart} from './actions';
export function CartButton() {
return <button onClick={() => addToCart('p-1', 1)}>Add</button>;
}The module directive makes the exported async function callable from client code through the framework's server-function mechanism.
When to use it
Shared server-function modules
Place the directive at module scope so several exported async functions can be imported by Client Components.
Form submissions
Use a function as a form action or formAction so React invokes it in a Transition.
Interview questions
QWhat does 'use server' do?
It marks an async server-side function as callable by client code. The framework creates a reference, and invoking that reference sends a request to the server and returns the serialized result.
Follow-up: Can a synchronous function use it? No. The documentation says the directive can only be used on async functions because the underlying call is a network operation.
QWhat is the difference between function-level and module-level usage?
A module-level directive marks every export in that file as a Server Function, allowing those exports to be imported by client code. A function-level directive marks only that function.
Follow-up: Why is module scope needed for client imports? The documentation requires the directive at module level when Server Functions are imported from client code.
QWhat constraints apply when calling a Server Function?
Arguments cross a network boundary, so they must use React's supported serializable types. Server Functions should also be treated as public entry points: validate untrusted arguments and authorize mutations.
Follow-up: How should UI code invoke one? Prefer a Transition; functions supplied to a form's action or formAction are automatically invoked in a Transition.
Related
Server Functionsuse clientServer ComponentsTransitionsform actionformAction