diff --git a/src/content/reference/react-dom/components/form.md b/src/content/reference/react-dom/components/form.md index fc59a8edeae..39b7ac960e4 100644 --- a/src/content/reference/react-dom/components/form.md +++ b/src/content/reference/react-dom/components/form.md @@ -83,13 +83,13 @@ export default function Search() { -### Handle form submission with a Server Action {/*handle-form-submission-with-a-server-action*/} +### Handle form submission with a Server Function {/*handle-form-submission-with-a-server-function*/} -Render a `
` with an input and submit button. Pass a Server Action (a function marked with [`'use server'`](/reference/rsc/use-server)) to the `action` prop of form to run the function when the form is submitted. +Render a `` with an input and submit button. Pass a Server Function (a function marked with [`'use server'`](/reference/rsc/use-server)) to the `action` prop of form to run the function when the form is submitted. -Passing a Server Action to `` 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. +Passing a Server Function to `` 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. -You can use hidden form fields to provide data to the ``'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). +You can use hidden form fields to provide data to the ``'s action. The Server Function will be called with the hidden form field data as an instance of [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData). ```jsx import { updateCart } from './lib.js'; @@ -129,7 +129,7 @@ function AddToCart({productId}) { } ``` -When `` is rendered by a [Server Component](/reference/rsc/use-client), and a [Server Action](/reference/rsc/use-server) is passed to the ``'s `action` prop, the form is [progressively enhanced](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). +When `` is rendered by a [Server Component](/reference/rsc/use-client), and a [Server Function](/reference/rsc/server-function) is passed to the ``'s `action` prop, the form is [progressively enhanced](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). ### Display a pending state during form submission {/*display-a-pending-state-during-form-submission*/} To display a pending state when a form is being submitted, you can call the `useFormStatus` Hook in a component rendered in a `` and read the `pending` property returned. @@ -315,10 +315,10 @@ export default function Search() { Displaying a form submission error message before the JavaScript bundle loads for progressive enhancement requires that: 1. `` be rendered by a [Server Component](/reference/rsc/use-client) -1. the function passed to the ``'s `action` prop be a [Server Action](/reference/rsc/use-server) +1. the function passed to the ``'s `action` prop be a [Server Function](/reference/rsc/server-functions) 1. the `useActionState` Hook be used to display the error message -`useActionState` takes two parameters: a [Server Action](/reference/rsc/use-server) and an initial state. `useActionState` returns two values, a state variable and an action. The action returned by `useActionState` should be passed to the `action` prop of the form. The state variable returned by `useActionState` can be used to displayed an error message. The value returned by the [Server Action](/reference/rsc/use-server) passed to `useActionState` will be used to update the state variable. +`useActionState` takes two parameters: a [Server Function](/reference/rsc/server-functions) and an initial state. `useActionState` returns two values, a state variable and an action. The action returned by `useActionState` should be passed to the `action` prop of the form. The state variable returned by `useActionState` can be used to display an error message. The value returned by the Server Function passed to `useActionState` will be used to update the state variable. diff --git a/src/content/reference/react/experimental_taintUniqueValue.md b/src/content/reference/react/experimental_taintUniqueValue.md index 09d277eb35d..de9a9beda16 100644 --- a/src/content/reference/react/experimental_taintUniqueValue.md +++ b/src/content/reference/react/experimental_taintUniqueValue.md @@ -192,7 +192,7 @@ experimental_taintUniqueValue( ); ``` -Now whenever anyone tries to pass this password to a Client Component, or send the password to a Client Component with a Server Action, an error will be thrown with message you defined when you called `taintUniqueValue`. +Now whenever anyone tries to pass this password to a Client Component, or send the password to a Client Component with a Server Function, an error will be thrown with message you defined when you called `taintUniqueValue`. diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 1b84b2b629c..bab5b8a0e07 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -48,8 +48,8 @@ The `use` API returns the value that was read from the resource like the resolve #### Caveats {/*caveats*/} * The `use` API must be called inside a Component or a Hook. -* When fetching data in a [Server Component](/reference/rsc/use-server), prefer `async` and `await` over `use`. `async` and `await` pick up rendering from the point where `await` was invoked, whereas `use` re-renders the component after the data is resolved. -* Prefer creating Promises in [Server Components](/reference/rsc/use-server) and passing them to [Client Components](/reference/rsc/use-client) over creating Promises in Client Components. Promises created in Client Components are recreated on every render. Promises passed from a Server Component to a Client Component are stable across re-renders. [See this example](#streaming-data-from-server-to-client). +* When fetching data in a [Server Component](/reference/rsc/server-components), prefer `async` and `await` over `use`. `async` and `await` pick up rendering from the point where `await` was invoked, whereas `use` re-renders the component after the data is resolved. +* Prefer creating Promises in [Server Components](/reference/rsc/server-components) and passing them to [Client Components](/reference/rsc/use-client) over creating Promises in Client Components. Promises created in Client Components are recreated on every render. Promises passed from a Server Component to a Client Component are stable across re-renders. [See this example](#streaming-data-from-server-to-client). --- diff --git a/src/content/reference/react/useActionState.md b/src/content/reference/react/useActionState.md index 2d4c7958761..b90c4b0b951 100644 --- a/src/content/reference/react/useActionState.md +++ b/src/content/reference/react/useActionState.md @@ -51,7 +51,7 @@ function StatefulForm({}) { 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. -If used with a Server Action, `useActionState` allows the server's response from submitting the form to be shown even before hydration has completed. +If used with a Server Function, `useActionState` allows the server's response from submitting the form to be shown even before hydration has completed. [See more examples below.](#usage) @@ -59,7 +59,7 @@ If used with a Server Action, `useActionState` allows the server's response from * `fn`: The function to be called when the form is submitted or button pressed. When the function is called, it will receive the previous state of the form (initially the `initialState` that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that a form action normally receives. * `initialState`: The value you want the state to be initially. It can be any serializable value. This argument is ignored after the action is first invoked. -* **optional** `permalink`: A string containing the unique page URL that this form modifies. For use on pages with dynamic content (eg: feeds) in conjunction with progressive enhancement: if `fn` is a [server action](/reference/rsc/use-server) and the form is submitted before the JavaScript bundle loads, the browser will navigate to the specified permalink URL, rather than the current page's URL. Ensure that the same form component is rendered on the destination page (including the same action `fn` and `permalink`) so that React knows how to pass the state through. Once the form has been hydrated, this parameter has no effect. +* **optional** `permalink`: A string containing the unique page URL that this form modifies. For use on pages with dynamic content (eg: feeds) in conjunction with progressive enhancement: if `fn` is a [server function](/reference/rsc/server-functions) and the form is submitted before the JavaScript bundle loads, the browser will navigate to the specified permalink URL, rather than the current page's URL. Ensure that the same form component is rendered on the destination page (including the same action `fn` and `permalink`) so that React knows how to pass the state through. Once the form has been hydrated, this parameter has no effect. {/* TODO T164397693: link to serializable values docs once it exists */} @@ -118,7 +118,7 @@ function action(currentState, formData) { #### Display form errors {/*display-form-errors*/} -To display messages such as an error message or toast that's returned by a Server Action, wrap the action in a call to `useActionState`. +To display messages such as an error message or toast that's returned by a Server Function, wrap the action in a call to `useActionState`. @@ -190,7 +190,7 @@ form button { #### Display structured information after submitting a form {/*display-structured-information-after-submitting-a-form*/} -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. +The return value from a Server Function 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. diff --git a/src/content/reference/rsc/server-actions.md b/src/content/reference/rsc/server-actions.md deleted file mode 100644 index 4d866f367f9..00000000000 --- a/src/content/reference/rsc/server-actions.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Server Actions ---- - - - -Sever Actions are for use in [React Server Components](/learn/start-a-new-react-project#bleeding-edge-react-frameworks). - - - - - -Server Actions allow Client Components to call async functions executed on the server. - - - - - - - -#### How do I build support for Server Actions? {/*how-do-i-build-support-for-server-actions*/} - -While Server Actions in React 19 are stable and will not break between major versions, the underlying APIs used to implement Server Actions in a React Server Components bundler or framework do not follow semver and may break between minors in React 19.x. - -To support Server Actions 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 Actions in the future. - - - -When a Server Action is defined with the `"use server"` directive, your framework will automatically create a reference to the server function, and pass that reference to the Client Component. When that function is called on the client, React will send a request to the server to execute the function, and return the result. - -Server Actions can be created in Server Components and passed as props to Client Components, or they can be imported and used in Client Components. - -### Creating a Server Action from a Server Component {/*creating-a-server-action-from-a-server-component*/} - -Server Components can define Server Actions with the `"use server"` directive: - -```js [[2, 7, "'use server'"], [1, 5, "createNoteAction"], [1, 12, "createNoteAction"]] -// Server Component -import Button from './Button'; - -function EmptyNote () { - async function createNoteAction() { - // Server Action - 'use server'; - - await db.notes.create(); - } - - return -} -``` - -For more, see the docs for [`"use server"`](/reference/rsc/use-server). - - -### Importing Server Actions from Client Components {/*importing-server-actions-from-client-components*/} - -Client Components can import Server Actions from files that use the `"use server"` directive: - -```js [[1, 3, "createNoteAction"]] -"use server"; - -export async function createNoteAction() { - await db.notes.create(); -} - -``` - -When the bundler builds the `EmptyNote` Client Component, it will create a reference to the `createNoteAction` function in the bundle. When the `button` is clicked, React will send a request to the server to execute the `createNoteAction` function using the reference provided: - -```js [[1, 2, "createNoteAction"], [1, 5, "createNoteAction"], [1, 7, "createNoteAction"]] -"use client"; -import {createNoteAction} from './actions'; - -function EmptyNote() { - console.log(createNoteAction); - // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'} - +} +``` + +For more, see the docs for [`"use server"`](/reference/rsc/use-server). + + +### Importing Server Functions from Client Components {/*importing-server-functions-from-client-components*/} + +Client Components can import Server Functions from files that use the `"use server"` directive: + +```js [[1, 3, "createNote"]] +"use server"; + +export async function createNote() { + await db.notes.create(); +} + +``` + +When the bundler builds the `EmptyNote` Client Component, it will create a reference to the `createNoteAction` function in the bundle. When the `button` is clicked, React will send a request to the server to execute the `createNoteAction` function using the reference provided: + +```js [[1, 2, "createNote"], [1, 5, "createNote"], [1, 7, "createNote"]] +"use client"; +import {createNote} from './actions'; + +function EmptyNote() { + console.log(createNote); + // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'} +