React Reference ยท Top-Level React APIs
The "use server" directive
Reference for the "use server" directive: mark async functions as Server Functions that the client can call, with rules for arguments, security and forms.
"use server" is a directive, a string at the top of a function body or a file, that tells a Server Components framework: "this async function runs on the server, but client code may call it". Calling it from the browser sends a request; the arguments are serialized, the function runs on the server, and the return value is sent back.
These functions are called Server Functions (often still called server actions when used with forms or transitions). The directive does nothing without a bundler and framework that implement it, such as a Server Components capable framework; in plain client-only React it is just an unused string.
// app/actions.js 'use server'; export async function saveName(formData) { const name = formData.get('name'); // runs on the server: database access, secrets, file system... }
Try it
The live editor has no server, so these examples show the shape of the idea with ordinary client code. The directive line itself is harmless there.
Syntax
There are two placements:
// 1. Inside one async function (in a Server Component file) async function save(formData) { 'use server'; /* ... */ } // 2. At the top of a file: every export becomes a Server Function 'use server'; export async function save(formData) { /* ... */ } export async function remove(id) { /* ... */ }
| Rule | Detail |
|---|---|
Must be async |
Calls cross the network, so they always return a promise. |
| Placement | First statement of the function body or of the module, before imports. |
| Quotes | Directives are string literals; single or double quotes both work. Backticks do not. |
| Arguments | Must be serializable by React: primitives, plain objects, arrays, Date, Map, Set, FormData, promises, and Server Function references. Functions, class instances and symbols are not accepted. |
| Return value | Also serialized. Return plain data, not rich objects. |
A file with the top-level directive may only export async functions.
Usage notes
- Every Server Function is a public HTTP endpoint. Treat arguments as untrusted input: validate them and check the user's permission inside the function, every time. Hiding the button is not authorization.
- Server Functions can be passed to
<form action={...}>or<button formAction={...}>, so a form can work before JavaScript loads in frameworks that support it. - They can also be called from event handlers or effects inside a transition, so pending state and error boundaries work as with any async action.
- Do not confuse it with
"use client":"use server"marks functions callable from the client, not server-only components. A Server Component needs no directive at all. - Closures inside inline Server Functions capture values by serializing them; keep captured data small and non-secret.
- Calls from one client component run in order, one at a time by default, so do not use them for streaming reads. Use them for mutations.
- If the framework is missing, the directive is silently ignored and the function runs in the browser; test with the real framework.