Skip to content

Commit 42ca996

Browse files
authored
Captailize Server Action (#6417)
Summary of changes: "Server Action", like "Effect", is a React-specific notion that would be benefited from captailization to be distinguished from its genertic meaning. It seems like [Next doc](https://nextjs.org/docs/app/api-reference/functions/server-actions) has also adopted such connventions and we should probably do the same. Co-authored-by: xuan.huang <[email protected]>
1 parent 8727204 commit 42ca996

File tree

4 files changed

+32
-32
lines changed

4 files changed

+32
-32
lines changed

src/content/reference/react-dom/components/form.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -93,11 +93,11 @@ export default function Search() {
9393

9494
### Handle form submission with a Server Action {/*handle-form-submission-with-a-server-action*/}
9595

96-
Render a `<form>` with an input and submit button. Pass a server action (a function marked with [`'use server'`](/reference/react/use-server)) to the `action` prop of form to run the function when the form is submitted.
96+
Render a `<form>` with an input and submit button. Pass a Server Action (a function marked with [`'use server'`](/reference/react/use-server)) to the `action` prop of form to run the function when the form is submitted.
9797

98-
Passing a server action to `<form action>` allow users to submit forms without JavaScript enabled or before the code has loaded. This is beneficial to users who have a slow connection, device, or have JavaScript disabled and is similar to the way forms work when a URL is passed to the `action` prop.
98+
Passing a Server Action to `<form action>` allow users to submit forms without JavaScript enabled or before the code has loaded. This is beneficial to users who have a slow connection, device, or have JavaScript disabled and is similar to the way forms work when a URL is passed to the `action` prop.
9999

100-
You can use hidden form fields to provide data to the `<form>`'s action. The server action will be called with the hidden form field data as an instance of [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
100+
You can use hidden form fields to provide data to the `<form>`'s action. The Server Action will be called with the hidden form field data as an instance of [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
101101

102102
```jsx
103103
import { updateCart } from './lib.js';

src/content/reference/react-dom/hooks/useFormState.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ function StatefulForm({}) {
5151

5252
The form state is the value returned by the action when the form was last submitted. If the form has not yet been submitted, it is the initial state that you pass.
5353

54-
If used with a server action, `useFormState` allows the server's response from submitting the form to be shown even before hydration has completed.
54+
If used with a Server Action, `useFormState` allows the server's response from submitting the form to be shown even before hydration has completed.
5555

5656
[See more examples below.](#usage)
5757

@@ -117,7 +117,7 @@ function action(currentState, formData) {
117117

118118
#### Display form errors {/*display-form-errors*/}
119119

120-
To display messages such as an error message or toast that's returned by a server action, wrap the action in a call to `useFormState`.
120+
To display messages such as an error message or toast that's returned by a Server Action, wrap the action in a call to `useFormState`.
121121

122122
<Sandpack>
123123

@@ -190,7 +190,7 @@ form button {
190190

191191
#### Display structured information after submitting a form {/*display-structured-information-after-submitting-a-form*/}
192192

193-
The return value from a server action can be any serializable value. For example, it could be an object that includes a boolean indicating whether the action was successful, an error message, or updated information.
193+
The return value from a Server Action can be any serializable value. For example, it could be an object that includes a boolean indicating whether the action was successful, an error message, or updated information.
194194

195195
<Sandpack>
196196

src/content/reference/react/use-client.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -269,7 +269,7 @@ Serializable props include:
269269
* [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) and [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
270270
* [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
271271
* Plain [objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object): those created with [object initializers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer), with serializable properties
272-
* Functions that are [server actions](/reference/react/use-server)
272+
* Functions that are [Server Actions](/reference/react/use-server)
273273
* Client or Server Component elements (JSX)
274274
* [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
275275

@@ -376,4 +376,4 @@ These libraries may rely on component Hooks or client APIs. Third-party componen
376376

377377
If these libraries have been updated to be compatible with React Server Components, then they will already include `'use client'` markers of their own, allowing you to use them directly from your Server Components. If a library hasn't been updated, or if a component needs props like event handlers that can only be specified on the client, you may need to add your own Client Component file in between the third-party Client Component and your Server Component where you'd like to use it.
378378

379-
[TODO]: <> (Troubleshooting - need use-cases)
379+
[TODO]: <> (Troubleshooting - need use-cases)

src/content/reference/react/use-server.md

+24-24
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ canary: true
2525

2626
### `'use server'` {/*use-server*/}
2727

28-
Add `'use server'` at the top of an async function body to mark the function as callable by the client. We call these functions _server actions_.
28+
Add `'use server'` at the top of an async function body to mark the function as callable by the client. We call these functions _Server Actions_.
2929

3030
```js {2}
3131
async function addToCart(data) {
@@ -34,38 +34,38 @@ async function addToCart(data) {
3434
}
3535
```
3636

37-
When calling a server action on the client, it will make a network request to the server that includes a serialized copy of any arguments passed. If the server action returns a value, that value will be serialized and returned to the client.
37+
When calling a Server Action on the client, it will make a network request to the server that includes a serialized copy of any arguments passed. If the Server Action returns a value, that value will be serialized and returned to the client.
3838

39-
Instead of individually marking functions with `'use server'`, you can add the directive to the top of a file to mark all exports within that file as server actions that can be used anywhere, including imported in client code.
39+
Instead of individually marking functions with `'use server'`, you can add the directive to the top of a file to mark all exports within that file as Server Actions that can be used anywhere, including imported in client code.
4040

4141
#### Caveats {/*caveats*/}
4242
* `'use server'` must be at the very beginning of their function or module; above any other code including imports (comments above directives are OK). They must be written with single or double quotes, not backticks.
43-
* `'use server'` can only be used in server-side files. The resulting server actions can be passed to Client Components through props. See supported [types for serialization](#serializable-parameters-and-return-values).
44-
* To import a server action from [client code](/reference/react/use-client), the directive must be used on a module level.
43+
* `'use server'` can only be used in server-side files. The resulting Server Actions can be passed to Client Components through props. See supported [types for serialization](#serializable-parameters-and-return-values).
44+
* To import a Server Action from [client code](/reference/react/use-client), the directive must be used on a module level.
4545
* Because the underlying network calls are always asynchronous, `'use server'` can only be used on async functions.
46-
* Always treat arguments to server actions as untrusted input and authorize any mutations. See [security considerations](#security).
47-
* Server actions should be called in a [transition](/reference/react/useTransition). Server actions 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.
48-
* Server actions are designed for mutations that update server-side state; they are not recommended for data fetching. Accordingly, frameworks implementing server actions typically process one action at a time and do not have a way to cache the return value.
46+
* Always treat arguments to Server Actions as untrusted input and authorize any mutations. See [security considerations](#security).
47+
* Server Actions should be called in a [transition](/reference/react/useTransition). Server Actions 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.
48+
* Server Actions are designed for mutations that update server-side state; they are not recommended for data fetching. Accordingly, frameworks implementing Server Actions typically process one action at a time and do not have a way to cache the return value.
4949

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

52-
Arguments to server actions are fully client-controlled. For security, always treat them as untrusted input, and make sure to validate and escape arguments as appropriate.
52+
Arguments to Server Actions are fully client-controlled. For security, always treat them as untrusted input, and make sure to validate and escape arguments as appropriate.
5353

54-
In any server action, make sure to validate that the logged-in user is allowed to perform that action.
54+
In any Server Action, make sure to validate that the logged-in user is allowed to perform that action.
5555

5656
<Wip>
5757

58-
To prevent sending sensitive data from a server action, there are experimental taint APIs to prevent unique values and objects from being passed to client code.
58+
To prevent sending sensitive data from a Server Action, there are experimental taint APIs to prevent unique values and objects from being passed to client code.
5959

6060
See [experimental_taintUniqueValue](/reference/react/experimental_taintUniqueValue) and [experimental_taintObjectReference](/reference/react/experimental_taintObjectReference).
6161

6262
</Wip>
6363

6464
### Serializable arguments and return values {/*serializable-parameters-and-return-values*/}
6565

66-
As client code calls the server action over the network, any arguments passed will need to be serializable.
66+
As client code calls the Server Action over the network, any arguments passed will need to be serializable.
6767

68-
Here are supported types for server action arguments:
68+
Here are supported types for Server Action arguments:
6969

7070
* Primitives
7171
* [string](https://developer.mozilla.org/en-US/docs/Glossary/String)
@@ -84,12 +84,12 @@ Here are supported types for server action arguments:
8484
* [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
8585
* [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instances
8686
* Plain [objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object): those created with [object initializers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer), with serializable properties
87-
* Functions that are server actions
87+
* Functions that are Server Actions
8888
* [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
8989

9090
Notably, these are not supported:
9191
* React elements, or [JSX](https://react.dev/learn/writing-markup-with-jsx)
92-
* Functions, including component functions or any other function that is not a server action
92+
* Functions, including component functions or any other function that is not a Server Action
9393
* [Classes](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Classes_in_JavaScript)
9494
* Objects that are instances of any class (other than the built-ins mentioned) or objects with [a null prototype](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects)
9595
* Symbols not registered globally, ex. `Symbol('my new symbol')`
@@ -100,9 +100,9 @@ Supported serializable return values are the same as [serializable props](/refer
100100

101101
## Usage {/*usage*/}
102102

103-
### Server actions in forms {/*server-actions-in-forms*/}
103+
### Server Actions in forms {/*server-actions-in-forms*/}
104104

105-
The most common use case of server actions will be calling server functions that mutate data. On the browser, the [HTML form element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) is the traditional approach for a user to submit a mutation. With React Server Components, React introduces first-class support for server actions in [forms](/reference/react-dom/components/form).
105+
The most common use case of Server Actions will be calling server functions that mutate data. On the browser, the [HTML form element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) is the traditional approach for a user to submit a mutation. With React Server Components, React introduces first-class support for Server Actions in [forms](/reference/react-dom/components/form).
106106

107107
Here is a form that allows a user to request a username.
108108

@@ -123,15 +123,15 @@ export default App() {
123123
}
124124
```
125125

126-
In this example `requestUsername` is a server action passed to a `<form>`. When a user submits this form, there is a network request to the server function `requestUsername`. When calling a server action in a form, React will supply the form's <CodeStep step={1}>[FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData)</CodeStep> as the first argument to the server action.
126+
In this example `requestUsername` is a Server Action passed to a `<form>`. When a user submits this form, there is a network request to the server function `requestUsername`. When calling a Server Action in a form, React will supply the form's <CodeStep step={1}>[FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData)</CodeStep> as the first argument to the Server Action.
127127

128-
By passing a server action to the form `action`, React can [progressively enhance](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement) the form. This means that forms can be submitted before the JavaScript bundle is loaded.
128+
By passing a Server Action to the form `action`, React can [progressively enhance](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement) the form. This means that forms can be submitted before the JavaScript bundle is loaded.
129129

130130
#### Handling return values in forms {/*handling-return-values*/}
131131

132132
In the username request form, there might be the chance that a username is not available. `requestUsername` should tell us if it fails or not.
133133

134-
To update the UI based on the result of a server action while supporting progressive enhancement, use [`useFormState`](/reference/react-dom/hooks/useFormState).
134+
To update the UI based on the result of a Server Action while supporting progressive enhancement, use [`useFormState`](/reference/react-dom/hooks/useFormState).
135135

136136
```js
137137
// requestUsername.js
@@ -171,11 +171,11 @@ function UsernameForm() {
171171

172172
Note that like most Hooks, `useFormState` can only be called in <CodeStep step={1}>[client code](/reference/react/use-client)</CodeStep>.
173173

174-
### Calling a server action outside of `<form>` {/*calling-a-server-action-outside-of-form*/}
174+
### Calling a Server Action outside of `<form>` {/*calling-a-server-action-outside-of-form*/}
175175

176-
Server actions are exposed server endpoints and can be called anywhere in client code.
176+
Server Actions are exposed server endpoints and can be called anywhere in client code.
177177

178-
When using a server action outside of a [form](/reference/react-dom/components/form), call the server action in a [transition](/reference/react/useTransition), which allows you to display a loading indicator, show [optimistic state updates](/reference/react/useOptimistic), and handle unexpected errors. Forms will automatically wrap server actions in transitions.
178+
When using a Server Action outside of a [form](/reference/react-dom/components/form), call the Server Action in a [transition](/reference/react/useTransition), which allows you to display a loading indicator, show [optimistic state updates](/reference/react/useOptimistic), and handle unexpected errors. Forms will automatically wrap Server Actions in transitions.
179179

180180
```js {9-12}
181181
import incrementLike from './actions';
@@ -212,4 +212,4 @@ export default async incrementLike() {
212212
}
213213
```
214214

215-
To read a server action return value, you'll need to `await` the promise returned.
215+
To read a Server Action return value, you'll need to `await` the promise returned.

0 commit comments

Comments
 (0)