Skip to content

Clarify Server Function caveats #7201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Clarify Server Function caveats #7201

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 3 additions & 2 deletions src/content/reference/rsc/use-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,9 @@ Instead of individually marking functions with `'use server'`, you can add the d
* To import a Server Functions from [client code](/reference/rsc/use-client), the directive must be used on a module level.
* Because the underlying network calls are always asynchronous, `'use server'` can only be used on async functions.
* Always treat arguments to Server Functions as untrusted input and authorize any mutations. See [security considerations](#security).
* Server Functions should be called in a [Transition](/reference/react/useTransition). Server Functions passed to [`<form action>`](/reference/react-dom/components/form#props) or [`formAction`](/reference/react-dom/components/input#props) will automatically be called in a transition.
* Server Functions are designed for mutations that update server-side state; they are not recommended for data fetching. Accordingly, frameworks implementing Server Functions typically process one action at a time and do not have a way to cache the return value.
* Server Functions are typically used in Actions to update server-side state; if you need to fetch data from the server, consider using a [Server Component](/reference/rsc/server-components).
* By convention, Server Functions used in Actions such as inside a [Transition](/reference/react/useTransition), passed to [`<form action>`](/reference/react-dom/components/form#props), or passed to [`formAction`](/reference/react-dom/components/input#props) are called Server Actions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm some Transitions are navigations right? And not Actions.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I want this to say "in Actions" and link directly to that section of Transitions, but that doesn't exist yet. I didn't intend for this to imply all Transitions are Actions, any idea how to clarify?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about like:

By convention, Server Functions that perform a mutation of some kind (i.e., that do not merely fetch data) and are called in a context that integrates with React's handling of async operations (such as inside …) are called Server Actions.

That's wordy and maybe can be refactored but I think this is correct? For Actions in general I think it means:

  • State updates are transition priority [server actions couldn't possibly trigger sync updates, of course]
  • Ties into isPending, optimistic, and error handling
  • Might have side effects (other than calling setState) so must be called in a context where React will call them exactly once / can't be interrupted or rebased

Note that the first two are true of navigation-style transitions too.

* Frameworks implementing Server Functions may order requests and may not have a way to cache the return value. Please see your framework's documentation for the framework specific behavior.

### Security considerations {/*security*/}

Expand Down
Loading