diff --git a/src/content/blog/2023/03/16/introducing-react-dev.md b/src/content/blog/2023/03/16/introducing-react-dev.md index d27673d90..d2e11fded 100644 --- a/src/content/blog/2023/03/16/introducing-react-dev.md +++ b/src/content/blog/2023/03/16/introducing-react-dev.md @@ -428,7 +428,7 @@ export default function PackingList() { Note that you must write `importance > 0 && ...` rather than `importance && ...` so that if the `importance` is `0`, `0` isn't rendered as the result! -In this solution, two separate conditions are used to insert a space between then name and the importance label. Alternatively, you could use a fragment with a leading space: `importance > 0 && <> ...` or add a space immediately inside the ``: `importance > 0 && ...`. +In this solution, two separate conditions are used to insert a space between then name and the importance label. Alternatively, you could use a Fragment with a leading space: `importance > 0 && <> ...` or add a space immediately inside the ``: `importance > 0 && ...`. @@ -643,4 +643,3 @@ On the development front, thanks to [Jared Palmer](https://twitter.com/jaredpalm Huge thanks to the folks who volunteered their time to participate in the alpha and beta testing program. Your enthusiasm and invaluable feedback helped us shape these docs. A special shout out to our beta tester, [Debbie O'Brien](https://twitter.com/debs_obrien), who gave a talk about her experience using the React docs at React Conf 2021. Finally, thanks to the React community for being the inspiration behind this effort. You are the reason we do this, and we hope that the new docs will help you use React to build any user interface that you want. - diff --git a/src/content/community/versioning-policy.md b/src/content/community/versioning-policy.md index 68d5b8eb1..eb38f8c29 100644 --- a/src/content/community/versioning-policy.md +++ b/src/content/community/versioning-policy.md @@ -46,7 +46,7 @@ In general, we *don't* bump the major version number for changes to: * **Development warnings.** Since these don't affect production behavior, we may add new warnings or modify existing warnings in between major versions. In fact, this is what allows us to reliably warn about upcoming breaking changes. * **APIs starting with `unstable_`.** These are provided as experimental features whose APIs we are not yet confident in. By releasing these with an `unstable_` prefix, we can iterate faster and get to a stable API sooner. -* **Alpha and canary versions of React.** We provide alpha versions of React as a way to test new features early, but we need the flexibility to make changes based on what we learn in the alpha period. If you use these versions, note that APIs may change before the stable release. +* **Alpha and Canary versions of React.** We provide alpha versions of React as a way to test new features early, but we need the flexibility to make changes based on what we learn in the alpha period. If you use these versions, note that APIs may change before the stable release. * **Undocumented APIs and internal data structures.** If you access internal property names like `__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED` or `__reactInternalInstance$uk43rzhitjg`, there is no warranty. You are on your own. This policy is designed to be pragmatic: certainly, we don't want to cause headaches for you. If we bumped the major version for all of these changes, we would end up releasing more major versions and ultimately causing more versioning pain for the community. It would also mean that we can't make progress in improving React as fast as we'd like. diff --git a/src/content/learn/conditional-rendering.md b/src/content/learn/conditional-rendering.md index cfd52320a..895d610d3 100644 --- a/src/content/learn/conditional-rendering.md +++ b/src/content/learn/conditional-rendering.md @@ -626,7 +626,7 @@ export default function PackingList() { Note that you must write `importance > 0 && ...` rather than `importance && ...` so that if the `importance` is `0`, `0` isn't rendered as the result! -In this solution, two separate conditions are used to insert a space between the name and the importance label. Alternatively, you could use a fragment with a leading space: `importance > 0 && <> ...` or add a space immediately inside the ``: `importance > 0 && ...`. +In this solution, two separate conditions are used to insert a space between the name and the importance label. Alternatively, you could use a Fragment with a leading space: `importance > 0 && <> ...` or add a space immediately inside the ``: `importance > 0 && ...`. diff --git a/src/content/learn/rendering-lists.md b/src/content/learn/rendering-lists.md index 13ac932fb..5b07afd93 100644 --- a/src/content/learn/rendering-lists.md +++ b/src/content/learn/rendering-lists.md @@ -1145,7 +1145,7 @@ hr { -You'll either need to convert `map` to a manual loop, or use a fragment. +You'll either need to convert `map` to a manual loop, or use a Fragment. @@ -1208,7 +1208,7 @@ hr { Using the original line index as a `key` doesn't work anymore because each separator and paragraph are now in the same array. However, you can give each of them a distinct key using a suffix, e.g. `key={i + '-text'}`. -Alternatively, you could render a collection of fragments which contain `
` and `

...

`. However, the `<>...` shorthand syntax doesn't support passing keys, so you'd have to write `` explicitly: +Alternatively, you could render a collection of Fragments which contain `
` and `

...

`. However, the `<>...` shorthand syntax doesn't support passing keys, so you'd have to write `` explicitly: @@ -1254,7 +1254,7 @@ hr { -Remember, fragments (often written as `<> `) let you group JSX nodes without adding extra `
`s! +Remember, Fragments (often written as `<> `) let you group JSX nodes without adding extra `
`s! diff --git a/src/content/learn/tutorial-tic-tac-toe.md b/src/content/learn/tutorial-tic-tac-toe.md index eca388a88..b40a90572 100644 --- a/src/content/learn/tutorial-tic-tac-toe.md +++ b/src/content/learn/tutorial-tic-tac-toe.md @@ -362,11 +362,11 @@ You'll get this error: -/src/App.js: Adjacent JSX elements must be wrapped in an enclosing tag. Did you want a JSX fragment `<>...`? +/src/App.js: Adjacent JSX elements must be wrapped in an enclosing tag. Did you want a JSX Fragment `<>...`? -React components need to return a single JSX element and not multiple adjacent JSX elements like two buttons. To fix this you can use *fragments* (`<>` and ``) to wrap multiple adjacent JSX elements like this: +React components need to return a single JSX element and not multiple adjacent JSX elements like two buttons. To fix this you can use *Fragments* (`<>` and ``) to wrap multiple adjacent JSX elements like this: ```js {3-6} export default function Square() { diff --git a/src/content/reference/react-dom/components/form.md b/src/content/reference/react-dom/components/form.md index 0097b3c89..25d1ba4e9 100644 --- a/src/content/reference/react-dom/components/form.md +++ b/src/content/reference/react-dom/components/form.md @@ -93,14 +93,12 @@ export default function Search() { ### Handle form submission with a Server Action {/*handle-form-submission-with-a-server-action*/} - Render a `
` 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. 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. 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). - ```jsx import { updateCart } from './lib.js'; @@ -275,9 +273,7 @@ export async function deliverMessage(message) { - [//]: # 'Uncomment the next line, and delete this line after the `useOptimistic` reference documentatino page is published' - [//]: # 'To learn more about the `useOptimistic` Hook see the [reference documentation](/reference/react/hooks/useOptimistic).' ### Handling form submission errors {/*handling-form-submission-errors*/} diff --git a/src/content/reference/react-dom/components/input.md b/src/content/reference/react-dom/components/input.md index 7328fddc9..03c0669cc 100644 --- a/src/content/reference/react-dom/components/input.md +++ b/src/content/reference/react-dom/components/input.md @@ -34,7 +34,8 @@ To display an input, render the [built-in browser ``](https://developer.m -React's extensions to the `formAction` prop are currently only available in React's canary and experimental channels. In stable releases of React `formAction` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). +React's extensions to the `formAction` prop are currently only available in React's Canary and experimental channels. In stable releases of React `formAction` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + [`formAction`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#formaction): A string or function. Overrides the parent `` for `type="submit"` and `type="image"`. When a URL is passed to `action` the form will behave like a standard HTML form. When a function is passed to `formAction` the function will handle the form submission. See [``](/reference/react-dom/components/form#props). diff --git a/src/content/reference/react-dom/hooks/useFormState.md b/src/content/reference/react-dom/hooks/useFormState.md index 1a0e9fbdb..fc17ac1fd 100644 --- a/src/content/reference/react-dom/hooks/useFormState.md +++ b/src/content/reference/react-dom/hooks/useFormState.md @@ -5,7 +5,7 @@ canary: true -The `useFormState` Hook is currently only available in React's canary and experimental channels. Learn more about [release channels here](/community/versioning-policy#all-release-channels). In addition, you need to use a framework that supports [React Server Components](/reference/react/use-client) to get the full benefit of `useFormState`. +The `useFormState` Hook is currently only available in React's Canary and experimental channels. Learn more about [release channels here](/community/versioning-policy#all-release-channels). In addition, you need to use a framework that supports [React Server Components](/reference/react/use-client) to get the full benefit of `useFormState`. @@ -51,10 +51,8 @@ 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, `useFormState` allows the server's response from submitting the form to be shown even before hydration has completed. - [See more examples below.](#usage) #### Parameters {/*parameters*/} @@ -119,10 +117,8 @@ 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 `useFormState`. - ```js App.js @@ -194,10 +190,8 @@ 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. - ```js App.js diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md index abaa9b6f2..67a06022b 100644 --- a/src/content/reference/react-dom/hooks/useFormStatus.md +++ b/src/content/reference/react-dom/hooks/useFormStatus.md @@ -5,7 +5,7 @@ canary: true -The `useFormStatus` Hook is currently only available in React's canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). +The `useFormStatus` Hook is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). diff --git a/src/content/reference/react/index.md b/src/content/reference/react/index.md index 313a8ef6d..43394acf6 100644 --- a/src/content/reference/react/index.md +++ b/src/content/reference/react/index.md @@ -4,7 +4,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. @@ -33,4 +32,3 @@ React-dom contains features that are only supported for web applications (which ## Legacy APIs {/*legacy-apis*/} * [Legacy APIs](/reference/react/legacy) - Exported from the `react` package, but not recommended for use in newly written code. - diff --git a/src/content/reference/react/use-client.md b/src/content/reference/react/use-client.md index 55b3aa3fa..98c45d3d0 100644 --- a/src/content/reference/react/use-client.md +++ b/src/content/reference/react/use-client.md @@ -51,7 +51,6 @@ As dependencies of `RichTextEditor`, `formatDate` and `Button` will also be eval * When a `'use client'` module is imported from another client-rendered module, the directive has no effect. * When a component module contains a `'use client'` directive, any usage of that component is guaranteed to be a Client Component. However, a component can still be evaluated on the client even if it does not have a `'use client'` directive. * A component usage is considered a Client Component if it is defined in module with `'use client'` directive or when it is a transitive dependency of a module that contains a `'use client'` directive. Otherwise, it is a Server Component. - * Code that is marked for client evaluation is not limited to components. All code that is a part of the Client module sub-tree is sent to and run by the client. * When a server evaluated module imports values from a `'use client'` module, the values must either be a React component or [supported serializable prop values](#passing-props-from-server-to-client-components) to be passed to a Client Component. Any other use case will throw an exception. @@ -59,10 +58,8 @@ 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. - To better illustrate this, consider the following React Server Components app. @@ -148,10 +145,8 @@ 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. - `'use client'` segments the module dependency tree of the React Server Components app, marking `InspirationGenerator.js` and all of its dependencies as client-rendered. @@ -242,9 +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 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*/} @@ -276,9 +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) - * Client or Server Component elements (JSX) * [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) @@ -316,10 +307,8 @@ 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. - In contrast, a component that renders UI without interaction will not need to be a Client Component. ```js @@ -387,6 +376,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 69282ebb1..03508cee5 100644 --- a/src/content/reference/react/use-server.md +++ b/src/content/reference/react/use-server.md @@ -25,10 +25,8 @@ 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_. - ```js {2} async function addToCart(data) { 'use server'; @@ -36,7 +34,6 @@ 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. 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. @@ -60,19 +57,16 @@ In any Server Action, make sure to validate that the logged-in user is allowed t 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). ### 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. Here are supported types for Server Action arguments: - * Primitives * [string](https://developer.mozilla.org/en-US/docs/Glossary/String) * [number](https://developer.mozilla.org/en-US/docs/Glossary/Number) @@ -90,16 +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 - * [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 - * [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')` @@ -110,12 +100,10 @@ Supported serializable return values are the same as [serializable props](/refer ## Usage {/*usage*/} - ### 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). - Here is a form that allows a user to request a username. ```js [[1, 3, "formData"]] @@ -135,20 +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. 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). - ```js // requestUsername.js 'use server'; @@ -194,7 +178,6 @@ Server Actions are exposed server endpoints and can be called anywhere in client 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'; import { useState, useTransition } from 'react'; @@ -230,6 +213,4 @@ export default async incrementLike() { } ``` - To read a Server Action return value, you'll need to `await` the promise returned. - diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index b726e67db..bb2fb6d5d 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -5,7 +5,7 @@ canary: true -The `use` Hook is currently only available in React's canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). +The `use` Hook is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). diff --git a/src/content/reference/react/useOptimistic.md b/src/content/reference/react/useOptimistic.md index 47593a0ae..2095a4198 100644 --- a/src/content/reference/react/useOptimistic.md +++ b/src/content/reference/react/useOptimistic.md @@ -5,7 +5,7 @@ canary: true -The `useOptimistic` Hook is currently only available in React's canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). +The `useOptimistic` Hook is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). @@ -27,7 +27,7 @@ The `useOptimistic` Hook is currently only available in React's canary and exper ### `useOptimistic(state, updateFn)` {/*use*/} -`useOptimistic` is a React hook that lets you show a different state while an async action is underway. It accepts some state as an argument and returns a copy of that state that can be different during the duration of an async action such as a network request. You provide a function that takes the current state and the input to the action, and returns the optimistic state to be used while the action is pending. +`useOptimistic` is a React Hook that lets you show a different state while an async action is underway. It accepts some state as an argument and returns a copy of that state that can be different during the duration of an async action such as a network request. You provide a function that takes the current state and the input to the action, and returns the optimistic state to be used while the action is pending. This state is called the "optimistic" state because it is usually used to immediately present the user with the result of performing an action, even though the action actually takes time to complete.