diff --git a/src/content/reference/react/index.md b/src/content/reference/react/index.md index 43394acf..ef644924 100644 --- a/src/content/reference/react/index.md +++ b/src/content/reference/react/index.md @@ -3,7 +3,6 @@ title: React Reference Overview --- - This section provides detailed reference documentation for working with React. For an introduction to React, please visit the [Learn](/learn) section. diff --git a/src/content/reference/react/use-client.md b/src/content/reference/react/use-client.md index 98c45d3d..3e633bb6 100644 --- a/src/content/reference/react/use-client.md +++ b/src/content/reference/react/use-client.md @@ -58,7 +58,7 @@ As dependencies of `RichTextEditor`, `formatDate` and `Button` will also be eval In a React app, components are often split into separate files, or [modules](/learn/importing-and-exporting-components#exporting-and-importing-a-component). -For apps that use React Server Components, the app is server-rendered by default. `'use client'` introduces a server-client boundary in the [module dependency tree](/learn/understanding-your-ui-as-a-tree#the-module-dependency-tree), effectively creating a subtree of Client modules. +For apps that use React Server Components, the app is server-rendered by default. `'use client'` introduces a server-client boundary in the [module dependency tree](/learn/understanding-your-ui-as-a-tree#the-module-dependency-tree), effectively creating a subtree of client modules. To better illustrate this, consider the following React Server Components app. @@ -145,7 +145,7 @@ export default [ -In the module dependency tree of this example app, the `'use client'` directive in `InspirationGenerator.js` marks that module and all of its transitive dependencies as Client modules. The subtree starting at `InspirationGenerator.js` is now marked as Client modules. +In the module dependency tree of this example app, the `'use client'` directive in `InspirationGenerator.js` marks that module and all of its transitive dependencies as client modules. The subtree starting at `InspirationGenerator.js` is now marked as client modules. `'use client'` segments the module dependency tree of the React Server Components app, marking `InspirationGenerator.js` and all of its dependencies as client-rendered. @@ -237,7 +237,7 @@ With `'use client'`, you can determine when components are Client Components. As For simplicity, we talk about Server Components, but the same principles apply to all code in your app that is server run. #### Advantages of Server Components {/*advantages*/} -* Server Components can reduce the amount of code sent and run by the client. Only Client modules are bundled and evaluated by the client. +* Server Components can reduce the amount of code sent and run by the client. Only client modules are bundled and evaluated by the client. * Server Components benefit from running on the server. They can access the local filesystem and may experience low latency for data fetches and network requests. #### Limitations of Server Components {/*limitations*/} @@ -269,7 +269,7 @@ Serializable props include: * [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) * [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) * 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 -* Functions that are [Server Actions](/reference/react/use-server) +* Functions that are [server actions](/reference/react/use-server) * Client or Server Component elements (JSX) * [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) @@ -307,7 +307,7 @@ export default function Counter({initialValue = 0}) { -As `Counter` requires both the `useState` Hook and event handlers to increment or decrement the value, this component must be a Client Component and will require a `'use client'` directive at the top. +As `Counter` requires both the `useState` hook and event handlers to increment or decrement the value, this component must be a Client Component and will require a `'use client'` directive at the top. In contrast, a component that renders UI without interaction will not need to be a Client Component. @@ -377,3 +377,4 @@ These libraries may rely on component Hooks or client APIs. Third-party componen 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. [TODO]: <> (Troubleshooting - need use-cases) + diff --git a/src/content/reference/react/use-server.md b/src/content/reference/react/use-server.md index 938efa90..ed4a7440 100644 --- a/src/content/reference/react/use-server.md +++ b/src/content/reference/react/use-server.md @@ -25,7 +25,7 @@ canary: true ### `'use server'` {/*use-server*/} -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_. +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_. ```js {2} async function addToCart(data) { @@ -34,28 +34,28 @@ async function addToCart(data) { } ``` -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. +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. -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. +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. #### Caveats {/*caveats*/} * `'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. -* `'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). -* To import a Server Action from [client code](/reference/react/use-client), the directive must be used on a module level. +* `'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). +* To import a server action from [client code](/reference/react/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 Actions as untrusted input and authorize any mutations. See [security considerations](#security). -* Server Actions should be called in a [transition](/reference/react/useTransition). Server Actions passed to [`
`](/reference/react-dom/components/form#props) or [`formAction`](/reference/react-dom/components/input#props) will automatically be called in a transition. -* 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. +* Always treat arguments to server actions as untrusted input and authorize any mutations. See [security considerations](#security). +* Server actions should be called in a [transition](/reference/react/useTransition). Server actions passed to [``](/reference/react-dom/components/form#props) or [`formAction`](/reference/react-dom/components/input#props) will automatically be called in a transition. +* 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. ### Security considerations {/*security*/} -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. +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. -In any Server Action, make sure to validate that the logged-in user is allowed to perform that action. +In any server action, make sure to validate that the logged-in user is allowed to perform that action. -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. +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. See [experimental_taintUniqueValue](/reference/react/experimental_taintUniqueValue) and [experimental_taintObjectReference](/reference/react/experimental_taintObjectReference). @@ -63,9 +63,9 @@ See [experimental_taintUniqueValue](/reference/react/experimental_taintUniqueVal ### Serializable arguments and return values {/*serializable-parameters-and-return-values*/} -As client code calls the Server Action over the network, any arguments passed will need to be serializable. +As client code calls the server action over the network, any arguments passed will need to be serializable. -Here are supported types for Server Action arguments: +Here are supported types for server action arguments: * Primitives * [string](https://developer.mozilla.org/en-US/docs/Glossary/String) @@ -84,12 +84,12 @@ Here are supported types for Server Action arguments: * [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) * [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instances * 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 -* Functions that are Server Actions +* Functions that are server actions * [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) Notably, these are not supported: * React elements, or [JSX](https://react.dev/learn/writing-markup-with-jsx) -* Functions, including component functions or any other function that is not a Server Action +* Functions, including component functions or any other function that is not a server action * [Classes](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Classes_in_JavaScript) * 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) * Symbols not registered globally, ex. `Symbol('my new symbol')` @@ -100,9 +100,9 @@ Supported serializable return values are the same as [serializable props](/refer ## Usage {/*usage*/} -### Server Actions in forms {/*server-actions-in-forms*/} +### Server actions in forms {/*server-actions-in-forms*/} -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). +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). Here is a form that allows a user to request a username. @@ -123,15 +123,16 @@ export default App() { } ``` -In this example `requestUsername` is a Server Action passed to a ``. 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 [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) as the first argument to the Server Action. +In this example `requestUsername` is a server action passed to a ``. 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 [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) as the first argument to the server action. -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. +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. #### Handling return values in forms {/*handling-return-values*/} 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. -To update the UI based on the result of a Server Action while supporting progressive enhancement, use [`useFormState`](/reference/react-dom/hooks/useFormState). + +To update the UI based on the result of a server action while supporting progressive enhancement, use [`useFormState`](/reference/react-dom/hooks/useFormState). ```js // requestUsername.js @@ -171,11 +172,11 @@ function UsernameForm() { Note that like most Hooks, `useFormState` can only be called in [client code](/reference/react/use-client). -### Calling a Server Action outside of `` {/*calling-a-server-action-outside-of-form*/} +### Calling a server action outside of `` {/*calling-a-server-action-outside-of-form*/} -Server Actions are exposed server endpoints and can be called anywhere in client code. +Server actions are exposed server endpoints and can be called anywhere in client code. -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. +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. ```js {9-12} import incrementLike from './actions'; @@ -212,4 +213,5 @@ export default async incrementLike() { } ``` -To read a Server Action return value, you'll need to `await` the promise returned. +To read a server action return value, you'll need to `await` the promise returned. +