Skip to content
Closed
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 37 additions & 42 deletions src/content/reference/rsc/server-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ Server Functions allow Client Components to call async functions executed on the

<Note>

#### How do I build support for Server Functions? {/*how-do-i-build-support-for-server-functions*/}
#### How do I build support for Server Functions? {/* how-do-i-build-support-for-server-functions */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

While Server Functions in React 19 are stable and will not break between minor versions, the underlying APIs used to implement Server Functions in a React Server Components bundler or framework do not follow semver and may break between minors in React 19.x.
While Server Functions in React 19 are stable and will not break between minor versions, the underlying APIs used to implement Server Functions in a React Server Components bundler or framework do not follow semver and may break between minors in React 19.x.
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

To support Server Functions as a bundler or framework, we recommend pinning to a specific React version, or using the Canary release. We will continue working with bundlers and frameworks to stabilize the APIs used to implement Server Functions in the future.

Expand All @@ -32,77 +32,75 @@ When a Server Function is defined with the [`"use server"`](/reference/rsc/use-s

Server Functions can be created in Server Components and passed as props to Client Components, or they can be imported and used in Client Components.

## Usage {/*usage*/}
## Usage {/* usage */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

### Creating a Server Function from a Server Component {/*creating-a-server-function-from-a-server-component*/}
### Creating a Server Function from a Server Component {/* creating-a-server-function-from-a-server-component */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

Server Components can define Server Functions with the `"use server"` directive:

```js [[2, 7, "'use server'"], [1, 5, "createNoteAction"], [1, 12, "createNoteAction"]]
// Server Component
import Button from './Button';

function EmptyNote () {
function EmptyNote() {
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
async function createNoteAction() {
// Server Function
'use server';

Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
await db.notes.create();
}

return <Button onClick={createNoteAction}/>;
return <Button onClick={createNoteAction} />;
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
}
```

When React renders the `EmptyNote` Server Component, it will create a reference to the `createNoteAction` function, and pass that reference to the `Button` Client Component. When the button is clicked, React will send a request to the server to execute the `createNoteAction` function with the reference provided:

```js {5}
"use client";
'use client';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

export default function Button({onClick}) {
console.log(onClick);
export default function Button({onClick}) {
console.log(onClick);
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
// {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'}
return <button onClick={() => onClick()}>Create Empty Note</button>
return <button onClick={() => onClick()}>Create Empty Note</button>;
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
}
```

For more, see the docs for [`"use server"`](/reference/rsc/use-server).


### Importing Server Functions from Client Components {/*importing-server-functions-from-client-components*/}
### Importing Server Functions from Client Components {/* importing-server-functions-from-client-components */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

Client Components can import Server Functions from files that use the `"use server"` directive:

```js [[1, 3, "createNote"]]
"use server";
'use server';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

export async function createNote() {
await db.notes.create();
}
Comment thread
rickhanlonii marked this conversation as resolved.

```

When the bundler builds the `EmptyNote` Client Component, it will create a reference to the `createNote` function in the bundle. When the `button` is clicked, React will send a request to the server to execute the `createNote` function using the reference provided:

```js [[1, 2, "createNote"], [1, 5, "createNote"], [1, 7, "createNote"]]
"use client";
'use client';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
import {createNote} from './actions';

function EmptyNote() {
console.log(createNote);
// {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNote'}
<button onClick={() => createNote()} />
<button onClick={() => createNote()} />;
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
}
```

For more, see the docs for [`"use server"`](/reference/rsc/use-server).

### Server Functions with Actions {/*server-functions-with-actions*/}
### Server Functions with Actions {/* server-functions-with-actions */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

Server Functions can be called from Actions on the client:

```js [[1, 3, "updateName"]]
"use server";
'use server';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

export async function updateName(name) {
if (!name) {
Expand All @@ -113,7 +111,7 @@ export async function updateName(name) {
```

```js [[1, 3, "updateName"], [1, 13, "updateName"], [2, 11, "submitAction"], [2, 23, "submitAction"]]
"use client";
'use client';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

import {updateName} from './actions';

Expand All @@ -131,31 +129,30 @@ function UpdateName() {
} else {
setName('');
}
})
}
});
};
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

Comment thread
rickhanlonii marked this conversation as resolved.
return (
<form action={submitAction}>
<input type="text" name="name" disabled={isPending}/>
<input type="text" name="name" disabled={isPending} />
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
{error && <span>Failed: {error}</span>}
</form>
)
);
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
}
```

This allows you to access the `isPending` state of the Server Function by wrapping it in an Action on the client.

For more, see the docs for [Calling a Server Function outside of `<form>`](/reference/rsc/use-server#calling-a-server-function-outside-of-form)

### Server Functions with Form Actions {/*using-server-functions-with-form-actions*/}
### Server Functions with Form Actions {/* using-server-functions-with-form-actions */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

Server Functions work with the new Form features in React 19.

You can pass a Server Function to a Form to automatically submit the form to the server:

Comment thread
rickhanlonii marked this conversation as resolved.

```js [[1, 3, "updateName"], [1, 7, "updateName"]]
"use client";
'use client';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

import {updateName} from './actions';

Expand All @@ -164,29 +161,31 @@ function UpdateName() {
<form action={updateName}>
<input type="text" name="name" />
</form>
)
);
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
}
```

When the Form submission succeeds, React will automatically reset the form. You can add `useActionState` to access the pending state, last response, or to support progressive enhancement.

For more, see the docs for [Server Functions in Forms](/reference/rsc/use-server#server-functions-in-forms).

### Server Functions with `useActionState` {/*server-functions-with-use-action-state*/}
### Server Functions with `useActionState` {/* server-functions-with-use-action-state */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

You can call Server Functions with `useActionState` for the common case where you just need access to the action pending state and last returned response:

```js [[1, 3, "updateName"], [1, 6, "updateName"], [2, 6, "submitAction"], [2, 9, "submitAction"]]
"use client";
'use client';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

import {updateName} from './actions';

function UpdateName() {
const [state, submitAction, isPending] = useActionState(updateName, {error: null});
const [state, submitAction, isPending] = useActionState(updateName, {
error: null,
});
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

return (
<form action={submitAction}>
<input type="text" name="name" disabled={isPending}/>
<input type="text" name="name" disabled={isPending} />
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
{state.error && <span>Failed: {state.error}</span>}
</form>
);
Expand All @@ -195,28 +194,24 @@ function UpdateName() {

When using `useActionState` with Server Functions, React will also automatically replay form submissions entered before hydration finishes. This means users can interact with your app even before the app has hydrated.

For more, see the docs for [`useActionState`](/reference/react-dom/hooks/useFormState).
For more, see the docs for [`useActionState`](/reference/react/useActionState).

### Progressive enhancement with `useActionState` {/*progressive-enhancement-with-useactionstate*/}
### Progressive enhancement with `useActionState` {/* progressive-enhancement-with-useactionstate */}
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

Server Functions also support progressive enhancement with the third argument of `useActionState`.

```js [[1, 3, "updateName"], [1, 6, "updateName"], [2, 6, "/name/update"], [3, 6, "submitAction"], [3, 9, "submitAction"]]
"use client";
'use client';
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated

import {updateName} from './actions';

function UpdateName() {
const [, submitAction] = useActionState(updateName, null, `/name/update`);

return (
<form action={submitAction}>
...
</form>
);
return <form action={submitAction}>...</form>;
Comment thread
rickhanlonii marked this conversation as resolved.
Outdated
}
```

When the <CodeStep step={2}>permalink</CodeStep> is provided to `useActionState`, React will redirect to the provided URL if the form is submitted before the JavaScript bundle loads.

For more, see the docs for [`useActionState`](/reference/react-dom/hooks/useFormState).
For more, see the docs for [`useActionState`](/reference/react/useActionState).
Loading