From 91e7f697d8087d6d1d0e086785406ab8a8238bdb Mon Sep 17 00:00:00 2001 From: Ahmed Abdelbaset Date: Mon, 25 Sep 2023 18:08:59 +0300 Subject: [PATCH 001/341] Update tutorial error message to use ConsoleBlock --- src/content/learn/tutorial-tic-tac-toe.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/learn/tutorial-tic-tac-toe.md b/src/content/learn/tutorial-tic-tac-toe.md index 7c5adb11..eca388a8 100644 --- a/src/content/learn/tutorial-tic-tac-toe.md +++ b/src/content/learn/tutorial-tic-tac-toe.md @@ -2073,7 +2073,13 @@ export default function Game() { } ``` -You can see what your code should look like below. Note that you should see an error in the developer tools console that says: ``Warning: Each child in an array or iterator should have a unique "key" prop. Check the render method of `Game`.`` You'll fix this error in the next section. +You can see what your code should look like below. Note that you should see an error in the developer tools console that says: + + +Warning: Each child in an array or iterator should have a unique "key" prop. Check the render method of `Game`. + + +You'll fix this error in the next section. From 4df3e7cf189d7fe649d1994e3c05f7f3b3c7df15 Mon Sep 17 00:00:00 2001 From: Luna Date: Mon, 25 Sep 2023 19:53:26 -0700 Subject: [PATCH 002/341] Remove pitfall and update Next link (#6318) * Remove pitfall and update Next link * Fix other beta link --------- Co-authored-by: Luna Wei --- src/content/learn/start-a-new-react-project.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/src/content/learn/start-a-new-react-project.md b/src/content/learn/start-a-new-react-project.md index 280a1378..d0933bcc 100644 --- a/src/content/learn/start-a-new-react-project.md +++ b/src/content/learn/start-a-new-react-project.md @@ -89,14 +89,9 @@ These features are getting closer to being production-ready every day, and we've ### Next.js (App Router) {/*nextjs-app-router*/} -**[Next.js's App Router](https://beta.nextjs.org/docs/getting-started) is a redesign of the Next.js APIs aiming to fulfill the React team’s full-stack architecture vision.** It lets you fetch data in asynchronous components that run on the server or even during the build. +**[Next.js's App Router](https://nextjs.org/docs) is a redesign of the Next.js APIs aiming to fulfill the React team’s full-stack architecture vision.** It lets you fetch data in asynchronous components that run on the server or even during the build. -Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/deployment) to any Node.js or serverless hosting, or to your own server. Next.js also supports [static export](https://beta.nextjs.org/docs/configuring/static-export) which doesn't require a server. - - -Next.js's App Router is **currently in beta and is not yet recommended for production** (as of Mar 2023). To experiment with it in an existing Next.js project, [follow this incremental migration guide](https://beta.nextjs.org/docs/upgrade-guide#migrating-from-pages-to-app). - - +Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/deployment) to any Node.js or serverless hosting, or to your own server. Next.js also supports [static export](https://nextjs.org/docs/app/building-your-application/deploying/static-exports) which doesn't require a server. From 62b9b4519bcf24e5c2c87cf51b1ce8f8105bdcc5 Mon Sep 17 00:00:00 2001 From: JustLolo <103621114+JustLolo@users.noreply.github.com> Date: Mon, 25 Sep 2023 22:34:02 -0500 Subject: [PATCH 003/341] Main (#5963) From 2dbd19531f5031e81a67eba532203c9abedc054a Mon Sep 17 00:00:00 2001 From: jajima <119467077+jajimajp@users.noreply.github.com> Date: Tue, 26 Sep 2023 12:56:16 +0900 Subject: [PATCH 004/341] Fix an incorrect person's name (#6066) --- src/content/learn/rendering-lists.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/learn/rendering-lists.md b/src/content/learn/rendering-lists.md index 45b60240..13ac932f 100644 --- a/src/content/learn/rendering-lists.md +++ b/src/content/learn/rendering-lists.md @@ -1086,7 +1086,7 @@ Here, `` is a syntax shortcut saying "pass #### List with a separator {/*list-with-a-separator*/} -This example renders a famous haiku by Katsushika Hokusai, with each line wrapped in a `

` tag. Your job is to insert an `

` separator between each paragraph. Your resulting structure should look like this: +This example renders a famous haiku by Tachibana Hokushi, with each line wrapped in a `

` tag. Your job is to insert an `

` separator between each paragraph. Your resulting structure should look like this: ```js
From 01c31630f9522c0d023e897168a48c5b0a394931 Mon Sep 17 00:00:00 2001 From: Matan Borenkraout Date: Tue, 26 Sep 2023 07:10:41 +0300 Subject: [PATCH 005/341] fix: wrong parameter name defined in explanation (#6158) --- src/content/reference/react/Profiler.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react/Profiler.md b/src/content/reference/react/Profiler.md index 8e149634..502ab0d4 100644 --- a/src/content/reference/react/Profiler.md +++ b/src/content/reference/react/Profiler.md @@ -58,7 +58,7 @@ function onRender(id, phase, actualDuration, baseDuration, startTime, commitTime * `actualDuration`: The number of milliseconds spent rendering the `` and its descendants for the current update. This indicates how well the subtree makes use of memoization (e.g. [`memo`](/reference/react/memo) and [`useMemo`](/reference/react/useMemo)). Ideally this value should decrease significantly after the initial mount as many of the descendants will only need to re-render if their specific props change. * `baseDuration`: The number of milliseconds estimating how much time it would take to re-render the entire `` subtree without any optimizations. It is calculated by summing up the most recent render durations of each component in the tree. This value estimates a worst-case cost of rendering (e.g. the initial mount or a tree with no memoization). Compare `actualDuration` against it to see if memoization is working. * `startTime`: A numeric timestamp for when React began rendering the current update. -* `endTime`: A numeric timestamp for when React committed the current update. This value is shared between all profilers in a commit, enabling them to be grouped if desirable. +* `commitTime`: A numeric timestamp for when React committed the current update. This value is shared between all profilers in a commit, enabling them to be grouped if desirable. --- From 8afb1ef5fcfaa1017542fb2b223de3edfdb82462 Mon Sep 17 00:00:00 2001 From: Krzysztof Piaskowy Date: Tue, 26 Sep 2023 20:00:24 +0200 Subject: [PATCH 006/341] Add info about App.js 2024 conference (#6192) Co-authored-by: Luna --- src/content/community/conferences.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/community/conferences.md b/src/content/community/conferences.md index 6e1780a7..1c164a09 100644 --- a/src/content/community/conferences.md +++ b/src/content/community/conferences.md @@ -55,7 +55,6 @@ October 27th 2023. In-person in Verona, Italy and online (hybrid event) [Website](https://2023.reactjsday.it/) - [Twitter](https://twitter.com/reactjsday) - [Facebook](https://www.facebook.com/GrUSP/) - [YouTube](https://www.youtube.com/c/grusp) - ### React Summit US 2023 {/*react-summit-us-2023*/} November 13 & 15, 2023. In-person in New York, US + remote first interactivity (hybrid event) @@ -66,6 +65,11 @@ December 8 & 12, 2023. In-person in Berlin, Germany + remote first interactivity [Website](https://reactday.berlin) - [Twitter](https://twitter.com/reactdayberlin) - [Facebook](https://www.facebook.com/reactdayberlin/) - [Videos](https://portal.gitnation.org/events/react-day-berlin-2023) +### App.js Conf 2024 {/*appjs-conf-2024*/} +May 22 - 24, 2024. In-person in Kraków, Poland + remote + +[Website](https://appjs.co) - [Twitter](https://twitter.com/appjsconf) + ### Render(ATL) 2024 🍑 {/*renderatl-2024-*/} June 12 - June 14, 2024. Atlanta, GA, USA From 850327d056ee2ea84d48262f103de6293d7d4809 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 27 Sep 2023 21:55:16 -0500 Subject: [PATCH 007/341] Update "Start a new React project" for stable Next.js App Router (#6020) --- src/content/learn/start-a-new-react-project.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/learn/start-a-new-react-project.md b/src/content/learn/start-a-new-react-project.md index d0933bcc..9c395d3f 100644 --- a/src/content/learn/start-a-new-react-project.md +++ b/src/content/learn/start-a-new-react-project.md @@ -21,12 +21,12 @@ If you want to build a new app or a new website fully with React, we recommend p **[Next.js](https://nextjs.org/) is a full-stack React framework.** It's versatile and lets you create React apps of any size--from a mostly static blog to a complex dynamic application. To create a new Next.js project, run in your terminal: -npx create-next-app +npx create-next-app@latest If you're new to Next.js, check out the [Next.js tutorial.](https://nextjs.org/learn/foundations/about-nextjs) -Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/deployment) to any Node.js or serverless hosting, or to your own server. [Fully static Next.js apps](https://nextjs.org/docs/advanced-features/static-html-export) can be deployed to any static hosting. +Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/app/building-your-application/deploying) to any Node.js or serverless hosting, or to your own server. Next.js also supports a [static export](https://nextjs.org/docs/pages/building-your-application/deploying/static-exports) which doesn't require a server. ### Remix {/*remix*/} @@ -91,7 +91,7 @@ These features are getting closer to being production-ready every day, and we've **[Next.js's App Router](https://nextjs.org/docs) is a redesign of the Next.js APIs aiming to fulfill the React team’s full-stack architecture vision.** It lets you fetch data in asynchronous components that run on the server or even during the build. -Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/deployment) to any Node.js or serverless hosting, or to your own server. Next.js also supports [static export](https://nextjs.org/docs/app/building-your-application/deploying/static-exports) which doesn't require a server. +Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/app/building-your-application/deploying) to any Node.js or serverless hosting, or to your own server. Next.js also supports [static export](https://nextjs.org/docs/app/building-your-application/deploying/static-exports) which doesn't require a server. From d4c214ad105548168b175a4e448e7411562d2f34 Mon Sep 17 00:00:00 2001 From: Sourabh singh <96938361+SouSingh@users.noreply.github.com> Date: Thu, 28 Sep 2023 17:23:39 +0530 Subject: [PATCH 008/341] Update Page not found to React18 URL (#6320) * Update react-labs-what-we-have-been-working-on-june-2022.md * Update react-labs-what-we-have-been-working-on-june-2022.md --- .../06/15/react-labs-what-we-have-been-working-on-june-2022.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.md b/src/content/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.md index 0d9e8e26..938b75c4 100644 --- a/src/content/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.md +++ b/src/content/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.md @@ -8,7 +8,7 @@ June 15, 2022 by [Andrew Clark](https://twitter.com/acdlite), [Dan Abramov](http -[React 18](https://reactjs.org/blog/2022/03/29/react-v18) was years in the making, and with it brought valuable lessons for the React team. Its release was the result of many years of research and exploring many paths. Some of those paths were successful; many more were dead-ends that led to new insights. One lesson we’ve learned is that it’s frustrating for the community to wait for new features without having insight into these paths that we’re exploring. +[React 18](https://react.dev/blog/2022/03/29/react-v18) was years in the making, and with it brought valuable lessons for the React team. Its release was the result of many years of research and exploring many paths. Some of those paths were successful; many more were dead-ends that led to new insights. One lesson we’ve learned is that it’s frustrating for the community to wait for new features without having insight into these paths that we’re exploring. From 1dfc88fe46b2ca169083377f0f716d8e7951af81 Mon Sep 17 00:00:00 2001 From: Alain Kaiser Date: Sun, 1 Oct 2023 11:25:16 +0200 Subject: [PATCH 009/341] fix: typo in useMemo example (#6330) --- src/content/reference/react/useMemo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react/useMemo.md b/src/content/reference/react/useMemo.md index 543c1112..c96c1a94 100644 --- a/src/content/reference/react/useMemo.md +++ b/src/content/reference/react/useMemo.md @@ -647,7 +647,7 @@ In this example, the `List` component is **artificially slowed down** so that yo Switching the tabs feels slow because it forces the slowed down `List` to re-render. That's expected because the `tab` has changed, and so you need to reflect the user's new choice on the screen. -Next, try toggling the theme. **Thanks to `useMemo` together with [`memo`](/reference/react/memo), it’s fast despite the artificial slowdown!** The `List` skipped re-rendering because the `visibleItems` array has not changed since the last render. The `visibleItems` array has not changed because both `todos` and `tab` (which you pass as dependencies to `useMemo`) haven't changed since the last render. +Next, try toggling the theme. **Thanks to `useMemo` together with [`memo`](/reference/react/memo), it’s fast despite the artificial slowdown!** The `List` skipped re-rendering because the `visibleTodos` array has not changed since the last render. The `visibleTodos` array has not changed because both `todos` and `tab` (which you pass as dependencies to `useMemo`) haven't changed since the last render. From 68f417a600c7d7b8c4131e39f8a843a856ae3909 Mon Sep 17 00:00:00 2001 From: Sebastian Silbermann Date: Sun, 1 Oct 2023 12:16:27 +0200 Subject: [PATCH 010/341] Explain how `null` ends up in `ref.current` for React-managed refs (#5836) * Update referencing-values-with-refs.md * Update src/content/learn/referencing-values-with-refs.md --- src/content/learn/referencing-values-with-refs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/learn/referencing-values-with-refs.md b/src/content/learn/referencing-values-with-refs.md index da5d864a..4faf1878 100644 --- a/src/content/learn/referencing-values-with-refs.md +++ b/src/content/learn/referencing-values-with-refs.md @@ -284,7 +284,7 @@ You also don't need to worry about [avoiding mutation](/learn/updating-objects-i ## Refs and the DOM {/*refs-and-the-dom*/} -You can point a ref to any value. However, the most common use case for a ref is to access a DOM element. For example, this is handy if you want to focus an input programmatically. When you pass a ref to a `ref` attribute in JSX, like `
`, React will put the corresponding DOM element into `myRef.current`. You can read more about this in [Manipulating the DOM with Refs.](/learn/manipulating-the-dom-with-refs) +You can point a ref to any value. However, the most common use case for a ref is to access a DOM element. For example, this is handy if you want to focus an input programmatically. When you pass a ref to a `ref` attribute in JSX, like `
`, React will put the corresponding DOM element into `myRef.current`. Once the element is removed from the DOM, React will update `myRef.current` to be `null`. You can read more about this in [Manipulating the DOM with Refs.](/learn/manipulating-the-dom-with-refs) From c45fa10a95e3ec757d2997c18f5053daa0b4cc39 Mon Sep 17 00:00:00 2001 From: Ruben Amendoeira Date: Thu, 5 Oct 2023 07:37:52 +0200 Subject: [PATCH 011/341] Fix "primatives" typo in cache.md (#6335) --- src/content/reference/react/cache.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react/cache.md b/src/content/reference/react/cache.md index 72fa4bd3..7f9afdb9 100644 --- a/src/content/reference/react/cache.md +++ b/src/content/reference/react/cache.md @@ -414,7 +414,7 @@ See prior mentioned pitfalls If none of the above apply, it may be a problem with how React checks if something exists in cache. -If your arguments are not [primatives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) (ex. objects, functions, arrays), ensure you're passing the same object reference. +If your arguments are not [primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) (ex. objects, functions, arrays), ensure you're passing the same object reference. When calling a memoized function, React will look up the input arguments to see if a result is already cached. React will use shallow equality of the arguments to determine if there is a cache hit. From 3cd1723658f0628aa3c68badd3e32dde96fe404c Mon Sep 17 00:00:00 2001 From: Sophie Alpert Date: Thu, 5 Oct 2023 22:55:01 -0700 Subject: [PATCH 012/341] Mention `use` as a Suspense-enabled data source (#6340) Maybe it's debatable whether we want to link to canary APIs in other pages but I feel like here it's more useful than not. --- .../reference/react-dom/server/renderToPipeableStream.md | 1 + .../reference/react-dom/server/renderToReadableStream.md | 1 + src/content/reference/react/Suspense.md | 1 + src/content/reference/react/useDeferredValue.md | 3 ++- 4 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/reference/react-dom/server/renderToPipeableStream.md b/src/content/reference/react-dom/server/renderToPipeableStream.md index 6a9021e0..26422f18 100644 --- a/src/content/reference/react-dom/server/renderToPipeableStream.md +++ b/src/content/reference/react-dom/server/renderToPipeableStream.md @@ -288,6 +288,7 @@ Streaming does not need to wait for React itself to load in the browser, or for - Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials) - Lazy-loading component code with [`lazy`](/reference/react/lazy) +- Reading the value of a Promise with [`use`](/reference/react/use) Suspense **does not** detect when data is fetched inside an Effect or event handler. diff --git a/src/content/reference/react-dom/server/renderToReadableStream.md b/src/content/reference/react-dom/server/renderToReadableStream.md index 8ef42aa7..f4ed54ce 100644 --- a/src/content/reference/react-dom/server/renderToReadableStream.md +++ b/src/content/reference/react-dom/server/renderToReadableStream.md @@ -287,6 +287,7 @@ Streaming does not need to wait for React itself to load in the browser, or for - Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials) - Lazy-loading component code with [`lazy`](/reference/react/lazy) +- Reading the value of a Promise with [`use`](/reference/react/use) Suspense **does not** detect when data is fetched inside an Effect or event handler. diff --git a/src/content/reference/react/Suspense.md b/src/content/reference/react/Suspense.md index dd931205..d9400378 100644 --- a/src/content/reference/react/Suspense.md +++ b/src/content/reference/react/Suspense.md @@ -254,6 +254,7 @@ async function getAlbums() { - Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials) - Lazy-loading component code with [`lazy`](/reference/react/lazy) +- Reading the value of a Promise with [`use`](/reference/react/use) Suspense **does not** detect when data is fetched inside an Effect or event handler. diff --git a/src/content/reference/react/useDeferredValue.md b/src/content/reference/react/useDeferredValue.md index f2505454..74fdab8a 100644 --- a/src/content/reference/react/useDeferredValue.md +++ b/src/content/reference/react/useDeferredValue.md @@ -82,10 +82,11 @@ During updates, the deferred value will "lag behin -This example assumes you use one of Suspense-enabled data sources: +This example assumes you use a Suspense-enabled data source: - Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials) - Lazy-loading component code with [`lazy`](/reference/react/lazy) +- Reading the value of a Promise with [`use`](/reference/react/use) [Learn more about Suspense and its limitations.](/reference/react/Suspense) From 9aa84b19222838f38863ce4bd8f516dbfe193bbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Markb=C3=A5ge?= Date: Fri, 6 Oct 2023 17:39:04 -0400 Subject: [PATCH 013/341] Add Experimental Taint API Docs (#6337) Co-authored-by: Matt Carroll --- .../experimental_taintObjectReference.md | 153 ++++++++++++++ .../react/experimental_taintUniqueValue.md | 198 ++++++++++++++++++ src/sidebarReference.json | 8 + 3 files changed, 359 insertions(+) create mode 100644 src/content/reference/react/experimental_taintObjectReference.md create mode 100644 src/content/reference/react/experimental_taintUniqueValue.md diff --git a/src/content/reference/react/experimental_taintObjectReference.md b/src/content/reference/react/experimental_taintObjectReference.md new file mode 100644 index 00000000..ce91c3d0 --- /dev/null +++ b/src/content/reference/react/experimental_taintObjectReference.md @@ -0,0 +1,153 @@ +--- +title: experimental_taintObjectReference +--- + + + +**This API is experimental and is not available in a stable version of React yet.** + +You can try it by upgrading React packages to the most recent experimental version: + +- `react@experimental` +- `react-dom@experimental` +- `eslint-plugin-react-hooks@experimental` + +Experimental versions of React may contain bugs. Don't use them in production. + +This API is only available inside React Server Components. + + + + + + +`taintObjectReference` lets you prevent a specific object instance from being passed to a Client Component like a `user` object. + +```js +experimental_taintObjectReference(message, object); +``` + +To prevent passing a key, hash or token, see [`taintUniqueValue`](/reference/react/experimental_taintUniqueValue). + + + + + +--- + +## Reference {/*reference*/} + +### `taintObjectReference(message, object)` {/*taintobjectreference*/} + +Call `taintObjectReference` with an object to register it with React as something that should not be allowed to be passed to the Client as is: + +```js +import {experimental_taintObjectReference} from 'react'; + +experimental_taintObjectReference( + 'Do not pass ALL environment variables to the client.', + process.env +); +``` + +[See more examples below.](#usage) + +#### Parameters {/*parameters*/} + +* `message`: The message you want to display if the object gets passed to a Client Component. This message will be displayed as a part of the Error that will be thrown if the object gets passed to a Client Component. + +* `object`: The object to be tainted. Functions and class instances can be passed to `taintObjectReference` as `object`. Functions and classes are already blocked from being passed to Client Components but the React's default error message will be replaced by what you defined in `message`. When a specific instance of a Typed Array is passed to `taintObjectReference` as `object`, any other copies of the Typed Array will not be tainted. + +#### Returns {/*returns*/} + +`experimental_taintObjectReference` returns `undefined`. + +#### Caveats {/*caveats*/} + +- Recreating or cloning a tainted object creates a new untained object which main contain sensetive data. For example, if you have a tainted `user` object, `const userInfo = {name: user.name, ssn: user.ssn}` or `{...user}` will create new objects which are not tainted. `taintObjectReference` only protects against simple mistakes when the object is passed through to a Client Component unchanged. + + + +**Do not rely on just tainting for security.** Tainting an object doesn't prevent leaking of every possible derived value. For example, the clone of a tainted object will create a new untained object. Using data from a tainted object (e.g. `{secret: taintedObj.secret}`) will create a new value or object that is not tainted. Tainting is a layer of protection, a secure app will have multiple layers of protection, well designed APIs, and isolation patterns. + + + +--- + +## Usage {/*usage*/} + +### Prevent user data from unintentionally reaching the client {/*prevent-user-data-from-unintentionally-reaching-the-client*/} + +A Client Component should never accept objects that carry sensitive data. Ideally, the data fetching functions should not expose data that the current user should not have access to. Sometimes mistakes happen during refactoring. To protect against this mistakes happening down the line we can "taint" the user object in our data API. + +```js +import {experimental_taintObjectReference} from 'react'; + +export async function getUser(id) { + const user = await db`SELECT * FROM users WHERE id = ${id}`; + experimental_taintObjectReference( + 'Do not pass the entire user object to the client. ' + + 'Instead, pick off the specific properties you need for this use case.', + user, + ); + return user; +} +``` + +Now whenever anyone tries to pass this object to a Client Component, an error will be thrown with the passed in error message instead. + + + +#### Protecting against leaks in data fetching {/*protecting-against-leaks-in-data-fetching*/} + +If you're running a Server Components environment that has access to sensitive data, you have to be careful not to pass objects straight through: + +```js +// api.js +export async function getUser(id) { + const user = await db`SELECT * FROM users WHERE id = ${id}`; + return user; +} +``` + +```js +import { getUser } from 'api.js'; +import { InfoCard } from 'components.js'; + +export async function Profile(props) { + const user = await getUser(props.userId); + // DO NOT DO THIS + return ; +} +``` + +```js +// components.js +"use client"; + +export async function InfoCard({ user }) { + return
{user.name}
; +} +``` + +Ideally, the `getUser` should not expose data that the current user should not have access to. To prevent passing the `user` object to a Client Component down the line we can "taint" the user object: + + +```js +// api.js +import {experimental_taintObjectReference} from 'react'; + +export async function getUser(id) { + const user = await db`SELECT * FROM users WHERE id = ${id}`; + experimental_taintObjectReference( + 'Do not pass the entire user object to the client. ' + + 'Instead, pick off the specific properties you need for this use case.', + user, + ); + return user; +} +``` + +Now if anyone tries to pass the `user` object to a Client Component, an error will be thrown with the passed in error message. + + diff --git a/src/content/reference/react/experimental_taintUniqueValue.md b/src/content/reference/react/experimental_taintUniqueValue.md new file mode 100644 index 00000000..eab73df5 --- /dev/null +++ b/src/content/reference/react/experimental_taintUniqueValue.md @@ -0,0 +1,198 @@ +--- +title: experimental_taintUniqueValue +--- + + + +**This API is experimental and is not available in a stable version of React yet.** + +You can try it by upgrading React packages to the most recent experimental version: + +- `react@experimental` +- `react-dom@experimental` +- `eslint-plugin-react-hooks@experimental` + +Experimental versions of React may contain bugs. Don't use them in production. + +This API is only available inside [React Server Components](/reference/react/use-client). + + + + + + +`taintUniqueValue` lets you prevent unique values from being passed to Client Components like passwords, keys, or tokens. + +```js +taintUniqueValue(errMessage, lifetime, value) +``` + +To prevent passing an object containing sensitive data, see [`taintObjectReference`](/reference/react/experimental_taintObjectReference). + + + + + +--- + +## Reference {/*reference*/} + +### `taintUniqueValue(message, lifetime, value)` {/*taintuniquevalue*/} + +Call `taintUniqueValue` with a password, token, key or hash to register it with React as something that should not be allowed to be passed to the Client as is: + +```js +import {experimental_taintUniqueValue} from 'react'; + +experimental_taintUniqueValue( + 'Do not pass secret keys to the client.', + process, + process.env.SECRET_KEY +); +``` + +[See more examples below.](#usage) + +#### Parameters {/*parameters*/} + +* `message`: The message you want to display if `value` is passed to a Client Component. This message will be displayed as a part of the Error that will be thrown if `value` is passed to a Client Component. + +* `lifetime`: Any object that indicates how long `value` should be tainted. `value` will be blocked from being sent to any Client Component while this object still exists. For example, passing `globalThis` blocks the value for the lifetime of an app. `lifetime` is typically an object whose properties contains `value`. + +* `value`: A string, bigint or TypedArray. `value` must be a unique sequence of characters or bytes with high entropy such as a cryptographic token, private key, hash, or a long password. `value` will be blocked from being sent to any Client Component. + +#### Returns {/*returns*/} + +`experimental_taintUniqueValue` returns `undefined`. + +#### Caveats {/*caveats*/} + +- Deriving new values from tainted values can compromise tainting protection. New values created by uppercasing tainted values, concatenating tainted string values into a larger string, converting tainted values to base64, substringing tainted values, and other similar transformations are not tainted unless you explicity call `taintUniqueValue` on these newly created values. + +--- + +## Usage {/*usage*/} + +### Prevent a token from being passed to Client Components {/*prevent-a-token-from-being-passed-to-client-components*/} + +To ensure that sensitive information such as passwords, session tokens, or other unique values do not inadvertently get passed to Client Components, the `taintUniqueValue` function provides a layer of protection. When a value is tainted, any attempt to pass it to a Client Component will result in an error. + +The `lifetime` argument defines the duration for which the value remains tainted. For values that should remain tainted indefinitely, objects like [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) or `process` can serve as the `lifetime` argument. These objects have a lifespan that spans the entire duration of your app's execution. + +```js +import {experimental_taintUniqueValue} from 'react'; + +experimental_taintUniqueValue( + 'Do not pass a user password to the client.', + globalThis, + process.env.SECRET_KEY +); +``` + +If the tainted value's lifespan is tied to a object, the `lifetime` should be the object that encapsulates the value. This ensures the tainted value remains protected for the lifetime of the encapsulating object. + +```js +import {experimental_taintUniqueValue} from 'react'; + +export async function getUser(id) { + const user = await db`SELECT * FROM users WHERE id = ${id}`; + experimental_taintUniqueValue( + 'Do not pass a user session token to the client.', + user, + user.session.token + ); + return user; +} +``` + +In this example, the `user` object serves as the `lifetime` argument. If this object gets stored in a global cache or is accessible by another request, the session token remains tainted. + + + +**Do not rely solely on tainting for security.** Tainting a value doesn't block every possible derived value. For example, creating a new value by upper casing a tainted string will not taint the new value. + + +```js +import {experimental_taintUniqueValue} from 'react'; + +const password = 'correct horse battery staple'; + +experimental_taintUniqueValue( + 'Do not pass the password to the client.', + globalThis, + password +); + +const uppercasePassword = password.toUpperCase() // `uppercasePassword` is not tainted +``` + +In this example, the constant `password` is tainted. Then `password` is used to create a new value `uppercasePassword` by calling the `toUpperCase` method on `password`. The newly created `uppercasePassword` is not tainted. + +Other similar ways of deriving new values from tainted values like concatenating it into a larger string, converting it to base64, or returning a substring create untained values. + +Tainting only protects against simple mistakes like explictly passing secret values to the client. Mistakes in calling the `taintUniqueValue` like using a global store outside of React, without the corresponding lifetime object, can cause the tainted value to become untainted. Tainting is a layer of protection, a secure app will have multiple layers of protection, well designed APIs, and isolation patterns. + + + + + +#### Using `server-only` and `taintUniqueValue` to prevent leaking secrets {/*using-server-only-and-taintuniquevalue-to-prevent-leaking-secrets*/} + +If you're running a Server Components environment that has access to private keys or passwords such as database passwords, you have to be careful not to pass that to a Client Component. + +```js +export async function Dashboard(props) { + // DO NOT DO THIS + return ; +} +``` + +```js +"use client"; + +import {useEffect} from '...' + +export async function Overview({ password }) { + useEffect(() => { + const headers = { Authorization: password }; + fetch(url, { headers }).then(...); + }, [password]); + ... +} +``` + +This example would leak the secret API token to the client. If this API token can be used to access data this particular user shouldn't have access to, it could lead to a data breach. + +[comment]: <> (TODO: Link to `server-only` docs once they are written) + +Ideally, secrets like this are abstracted into a single helper file that can only be imported by trusted data utilities on the server. The helper can even be tagged with [`server-only`](https://www.npmjs.com/package/server-only) to ensure that this file isn't imported on the client. + +```js +import "server-only"; + +export function fetchAPI(url) { + const headers = { Authorization: process.env.API_PASSWORD }; + return fetch(url, { headers }); +} +``` + +Sometimes mistakes happen during refactoring and not all of your colleagues might know about this. +To protect against this mistakes happening down the line we can "taint" the actual password: + +```js +import "server-only"; +import {experimental_taintUniqueValue} from 'react'; + +experimental_taintUniqueValue( + 'Do not pass the API token password to the client. ' + + 'Instead do all fetches on the server.' + process, + process.env.API_PASSWORD +); +``` + +Now whenever anyone tries to pass this password to a Client Component, or send the password to a Client Component with a Server Action, a error will be thrown with message you defined when you called `taintUniqueValue`. + + + +--- diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 62725693..d1de3062 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -127,6 +127,14 @@ { "title": "startTransition", "path": "/reference/react/startTransition" + }, + { + "title": "experimental_taintObjectReference", + "path": "/reference/react/experimental_taintObjectReference" + }, + { + "title": "experimental_taintUniqueValue", + "path": "/reference/react/experimental_taintUniqueValue" } ] }, From fdad54db4c16633ef3b0a896047037d3585e8aab Mon Sep 17 00:00:00 2001 From: Sophie Alpert Date: Mon, 9 Oct 2023 11:06:26 -0700 Subject: [PATCH 014/341] Explain limitations of useSyncExternalStore with concurrency (#6339) * Explain limitations of useSyncExternalStore with concurrency Doesn't seem like we have this noted anywhere. * Pull out example to code block --- .../reference/react/useSyncExternalStore.md | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/src/content/reference/react/useSyncExternalStore.md b/src/content/reference/react/useSyncExternalStore.md index 4169e231..955b751f 100644 --- a/src/content/reference/react/useSyncExternalStore.md +++ b/src/content/reference/react/useSyncExternalStore.md @@ -57,6 +57,26 @@ The current snapshot of the store which you can use in your rendering logic. * If a different `subscribe` function is passed during a re-render, React will re-subscribe to the store using the newly passed `subscribe` function. You can prevent this by declaring `subscribe` outside the component. +* If the store is mutated during a [non-blocking transition update](/reference/react/useTransition), React will fall back to performing that update as blocking. Specifically, React will call `getSnapshot` a second time just before applying changes to the DOM. If it returns a different value than when it was called originally, React will restart the transition update from scratch, this time applying it as a blocking update, to ensure that every component on screen is reflecting the same version of the store. + +* It's not recommended to _suspend_ a render based on a store value returned by `useSyncExternalStore`. The reason is that mutations to the external store cannot be [marked as non-blocking transition updates](/reference/react/useTransition), so they will trigger the nearest [`Suspense` fallback](/reference/react/Suspense), replacing already-rendered content on screen with a loading spinner, which typically makes a poor UX. + + For example, the following are discouraged: + + ```js + const LazyProductDetailPage = lazy(() => import('./ProductDetailPage.js')); + + function ShoppingApp() { + const selectedProductId = useSyncExternalStore(...); + + // ❌ Calling `use` with a Promise dependent on `selectedProductId` + const data = use(fetchItem(selectedProductId)) + + // ❌ Conditionally rendering a lazy component based on `selectedProductId` + return selectedProductId != null ? : ; + } + ``` + --- ## Usage {/*usage*/} @@ -425,4 +445,4 @@ function ChatIndicator({ userId }) { // ... } -``` \ No newline at end of file +``` From 88af66dbd1243594ad983e8463f9785c6e0a1450 Mon Sep 17 00:00:00 2001 From: Sophie Alpert Date: Mon, 9 Oct 2023 11:23:04 -0700 Subject: [PATCH 015/341] Fix comma splice --- .../reference/react/experimental_taintObjectReference.md | 2 +- src/content/reference/react/experimental_taintUniqueValue.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/reference/react/experimental_taintObjectReference.md b/src/content/reference/react/experimental_taintObjectReference.md index ce91c3d0..e3fd35a4 100644 --- a/src/content/reference/react/experimental_taintObjectReference.md +++ b/src/content/reference/react/experimental_taintObjectReference.md @@ -68,7 +68,7 @@ experimental_taintObjectReference( -**Do not rely on just tainting for security.** Tainting an object doesn't prevent leaking of every possible derived value. For example, the clone of a tainted object will create a new untained object. Using data from a tainted object (e.g. `{secret: taintedObj.secret}`) will create a new value or object that is not tainted. Tainting is a layer of protection, a secure app will have multiple layers of protection, well designed APIs, and isolation patterns. +**Do not rely on just tainting for security.** Tainting an object doesn't prevent leaking of every possible derived value. For example, the clone of a tainted object will create a new untained object. Using data from a tainted object (e.g. `{secret: taintedObj.secret}`) will create a new value or object that is not tainted. Tainting is a layer of protection; a secure app will have multiple layers of protection, well designed APIs, and isolation patterns. diff --git a/src/content/reference/react/experimental_taintUniqueValue.md b/src/content/reference/react/experimental_taintUniqueValue.md index eab73df5..a67eebf7 100644 --- a/src/content/reference/react/experimental_taintUniqueValue.md +++ b/src/content/reference/react/experimental_taintUniqueValue.md @@ -130,7 +130,7 @@ In this example, the constant `password` is tainted. Then `password` is used to Other similar ways of deriving new values from tainted values like concatenating it into a larger string, converting it to base64, or returning a substring create untained values. -Tainting only protects against simple mistakes like explictly passing secret values to the client. Mistakes in calling the `taintUniqueValue` like using a global store outside of React, without the corresponding lifetime object, can cause the tainted value to become untainted. Tainting is a layer of protection, a secure app will have multiple layers of protection, well designed APIs, and isolation patterns. +Tainting only protects against simple mistakes like explictly passing secret values to the client. Mistakes in calling the `taintUniqueValue` like using a global store outside of React, without the corresponding lifetime object, can cause the tainted value to become untainted. Tainting is a layer of protection; a secure app will have multiple layers of protection, well designed APIs, and isolation patterns. From f2c45ea17f60285316055e3dfe339f473f8ca85b Mon Sep 17 00:00:00 2001 From: Sophie Alpert Date: Mon, 9 Oct 2023 11:57:24 -0700 Subject: [PATCH 016/341] Add labs icon to experimental APIs (#6346) --- src/sidebarReference.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/sidebarReference.json b/src/sidebarReference.json index d1de3062..f9049956 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -130,11 +130,13 @@ }, { "title": "experimental_taintObjectReference", - "path": "/reference/react/experimental_taintObjectReference" + "path": "/reference/react/experimental_taintObjectReference", + "canary": true }, { "title": "experimental_taintUniqueValue", - "path": "/reference/react/experimental_taintUniqueValue" + "path": "/reference/react/experimental_taintUniqueValue", + "canary": true } ] }, From 43f4702f7897fa824833435107b68b7d7acf5203 Mon Sep 17 00:00:00 2001 From: Matt Carroll <7158882+mattcarrollcode@users.noreply.github.com> Date: Tue, 10 Oct 2023 18:19:58 -0700 Subject: [PATCH 017/341] Fix typo in typescript.md (#6347) --- src/content/learn/typescript.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/learn/typescript.md b/src/content/learn/typescript.md index 56fa5be5..727974b1 100644 --- a/src/content/learn/typescript.md +++ b/src/content/learn/typescript.md @@ -284,7 +284,7 @@ export default App = AppTSX; -This technique works when you have an default value which makes sense - but there are occasionally cases when you do not, and in those cases `null` can feel reasonable as a default value. However, to allow the type-system to understand your code, you need to explicitly set `ContextShape | null` on the `createContext`. +This technique works when you have a default value which makes sense - but there are occasionally cases when you do not, and in those cases `null` can feel reasonable as a default value. However, to allow the type-system to understand your code, you need to explicitly set `ContextShape | null` on the `createContext`. This causes the issue that you need to eliminate the `| null` in the type for context consumers. Our recommendation is to have the hook do a runtime check for it's existence and throw an error when not present: @@ -460,4 +460,4 @@ We recommend the following resources: - [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/) is a community-maintained cheatsheet for using TypeScript with React, covering a lot of useful edge cases and providing more breadth than this document. - - [TypeScript Community Discord](https://discord.com/invite/typescript) is a great place to ask questions and get help with TypeScript and React issues. \ No newline at end of file + - [TypeScript Community Discord](https://discord.com/invite/typescript) is a great place to ask questions and get help with TypeScript and React issues. From 900a6693ef20cbcb59430fa45b7cc079735d0522 Mon Sep 17 00:00:00 2001 From: Rogin Farrer Date: Tue, 10 Oct 2023 18:50:12 -0700 Subject: [PATCH 018/341] Upgrade react-collapsed (#5893) * Upgrade react-collapsed * 4.0.4 --------- Co-authored-by: Rogin Farrer --- package.json | 2 +- .../Layout/Sidebar/SidebarRouteTree.tsx | 2 +- yarn.lock | 21 ++++--------------- 3 files changed, 6 insertions(+), 19 deletions(-) diff --git a/package.json b/package.json index 5ff6adba..472ef79c 100644 --- a/package.json +++ b/package.json @@ -36,7 +36,7 @@ "next-remote-watch": "^1.0.0", "parse-numeric-range": "^1.2.0", "react": "^0.0.0-experimental-16d053d59-20230506", - "react-collapsed": "npm:@gaearon/react-collapsed@3.1.0-forked.1", + "react-collapsed": "4.0.4", "react-dom": "^0.0.0-experimental-16d053d59-20230506", "remark-frontmatter": "^4.0.1", "remark-gfm": "^3.0.1" diff --git a/src/components/Layout/Sidebar/SidebarRouteTree.tsx b/src/components/Layout/Sidebar/SidebarRouteTree.tsx index 9a0dd23f..a9fa575b 100644 --- a/src/components/Layout/Sidebar/SidebarRouteTree.tsx +++ b/src/components/Layout/Sidebar/SidebarRouteTree.tsx @@ -7,7 +7,7 @@ import {useRef, useLayoutEffect, Fragment} from 'react'; import cn from 'classnames'; import {useRouter} from 'next/router'; import {SidebarLink} from './SidebarLink'; -import useCollapse from 'react-collapsed'; +import {useCollapse} from 'react-collapsed'; import usePendingRoute from 'hooks/usePendingRoute'; import type {RouteItem} from 'components/Layout/getRouteMeta'; diff --git a/yarn.lock b/yarn.lock index 5819fa4f..8a3183cd 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4797,11 +4797,6 @@ path-type@^4.0.0: resolved "https://registry.yarnpkg.com/path-type/-/path-type-4.0.0.tgz#84ed01c0a7ba380afe09d90a8c180dcd9d03043b" integrity sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw== -performance-now@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/performance-now/-/performance-now-2.1.0.tgz#6309f4e0e5fa913ec1c69307ae364b4b377c9e7b" - integrity sha1-Ywn04OX6kT7BxpMHrjZLSzd8nns= - periscopic@^3.0.0: version "3.0.4" resolved "https://registry.yarnpkg.com/periscopic/-/periscopic-3.0.4.tgz#b3fbed0d1bc844976b977173ca2cd4a0ef4fa8d1" @@ -5284,13 +5279,6 @@ queue-microtask@^1.2.2: resolved "https://registry.yarnpkg.com/queue-microtask/-/queue-microtask-1.2.3.tgz#4929228bbc724dfac43e0efb058caf7b6cfb6243" integrity sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A== -raf@^3.4.1: - version "3.4.1" - resolved "https://registry.yarnpkg.com/raf/-/raf-3.4.1.tgz#0742e99a4a6552f445d73e3ee0328af0ff1ede39" - integrity sha512-Sq4CW4QhwOHE8ucn6J34MqtZCeWFP2aQSmrlroYgqAV1PjStIhJXxYuTgUIfkEk7zTLjmIjLmU5q+fbD1NnOJA== - dependencies: - performance-now "^2.1.0" - range-parser@~1.2.1: version "1.2.1" resolved "https://registry.yarnpkg.com/range-parser/-/range-parser-1.2.1.tgz#3cf37023d199e1c24d1a55b84800c2f3e6468031" @@ -5306,12 +5294,11 @@ raw-body@2.5.1: iconv-lite "0.4.24" unpipe "1.0.0" -"react-collapsed@npm:@gaearon/react-collapsed@3.1.0-forked.1": - version "3.1.0-forked.1" - resolved "https://registry.yarnpkg.com/@gaearon/react-collapsed/-/react-collapsed-3.1.0-forked.1.tgz#b287b81fc2af2971d7d7b523dc40b6cf116822ac" - integrity sha512-QkW55Upl4eeOtnDMOxasafDtDwaF+DpYKvHq8KZoNz9P477iUH8Ik1YFYuqtI7UA8mHm1/z66LD678dZCXwEEg== +react-collapsed@4.0.4: + version "4.0.4" + resolved "https://registry.yarnpkg.com/react-collapsed/-/react-collapsed-4.0.4.tgz#4c6bce3a15286d43e95b6730ad70ec387a54caa9" + integrity sha512-8avvmnQxDYTgGZYVP9+3Z7doomxVEBoCkukpTmUHEIrAYvELZ5jNNfYCt/hCpHB6GmQbzZoDmnDupjsnQVgcCQ== dependencies: - raf "^3.4.1" tiny-warning "^1.0.3" react-devtools-inline@4.4.0: From e85b71de88a20cda9588f51f01d4a70e5cbe1cb4 Mon Sep 17 00:00:00 2001 From: Soichiro Miki Date: Fri, 13 Oct 2023 20:21:15 +0900 Subject: [PATCH 019/341] Add 'ja' to deployedTranslations (#6351) --- src/components/Seo.tsx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/components/Seo.tsx b/src/components/Seo.tsx index d0dcaab7..79f19f87 100644 --- a/src/components/Seo.tsx +++ b/src/components/Seo.tsx @@ -22,6 +22,7 @@ const deployedTranslations = [ 'zh-hans', 'es', 'fr', + 'ja', // We'll add more languages when they have enough content. // Please DO NOT edit this list without a discussion in the reactjs/react.dev repo. // It must be the same between all translations. From 31b7881905460b755345b41110892f5c5af80679 Mon Sep 17 00:00:00 2001 From: Kathryn Middleton Date: Mon, 16 Oct 2023 15:03:02 -0400 Subject: [PATCH 020/341] Add GA4 tag to react.dev (#6350) --- src/pages/_document.tsx | 9 +++++++++ src/siteConfig.js | 1 + 2 files changed, 10 insertions(+) diff --git a/src/pages/_document.tsx b/src/pages/_document.tsx index 392fdf88..d8fb0c62 100644 --- a/src/pages/_document.tsx +++ b/src/pages/_document.tsx @@ -9,6 +9,15 @@ const MyDocument = () => { return ( + +``` + + + + + +--- + +## Reference {/*reference*/} + +### ` + + ); +} + +export default function Page() { + return ( + +

My Website

+ +

Welcome

+ + ); +} +``` + + \ No newline at end of file diff --git a/src/content/reference/react-dom/components/style.md b/src/content/reference/react-dom/components/style.md new file mode 100644 index 00000000..f5cf231a --- /dev/null +++ b/src/content/reference/react-dom/components/style.md @@ -0,0 +1,106 @@ +--- +style: " +``` + + + + + +--- + +## Reference {/*reference*/} + +### ` +``` + +[See more examples below.](#usage) + +#### Props {/*props*/} + +` + + … + + + ); +} + +export default function App() { + return ( + + + + ); +} +``` + + diff --git a/src/content/reference/react-dom/components/title.md b/src/content/reference/react-dom/components/title.md new file mode 100644 index 00000000..9d6ed18c --- /dev/null +++ b/src/content/reference/react-dom/components/title.md @@ -0,0 +1,98 @@ +--- +title: "" +canary: true +--- + +<Canary> + +React's extensions to `<title>` are currently only available in React's canary and experimental channels. In stable releases of React `<title>` 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). + +</Canary> + + +<Intro> + +The [built-in browser `<title>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) lets you specify the title of the document. + +```js +<title>My Blog +``` + + + + + +--- + +## Reference {/*reference*/} + +### `` {/*title*/} + +To specify the title of the document, render the [built-in browser `<title>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title). You can render `<title>` from any component and React will always place the corresponding DOM element in the document head. + +```js +<title>My Blog +``` + +[See more examples below.](#usage) + +#### Props {/*props*/} + +`` supports all [common element props.](/reference/react-dom/components/common#props) + +* `children`: `<title>` accepts only text as a child. This text will become the title of the document. You can also pass your own components as long as they only render text. + +#### Special rendering behavior {/*special-rendering-behavior*/} + +React will always place the DOM element corresponding to the `<title>` component within the document’s `<head>`, regardless of where in the React tree it is rendered. The `<head>` is the only valid place for `<title>` to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render its `<title>` itself. + +There are two exception to this: +* If `<title>` is within an `<svg>` component, then there is no special behavior, because in this context it doesn’t represent the document’s title but rather is an [accessibility annotation for that SVG graphic](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title). +* If the `<title>` has an [`itemProp`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop) prop, there is no special behavior, because in this case it doesn’t represent the document’s title but rather metadata about a specific part of the page. + +<Pitfall> + +Only render a single `<title>` at a time. If more than one component renders a `<title>` tag at the same time, React will place all of those titles in the document head. When this happens, the behavior of browsers and search engines is undefined. + +</Pitfall> + +--- + +## Usage {/*usage*/} + +### Set the document title {/*set-the-document-title*/} + +Render the `<title>` component from any component with text as its children. React will put a `<title>` DOM node in the document `<head>`. + +<SandpackWithHTMLOutput> + +```js App.js active +import ShowRenderedHTML from './ShowRenderedHTML.js'; + +export default function ContactUsPage() { + return ( + <ShowRenderedHTML> + <title>My Site: Contact Us +

Contact Us

+

Email us at support@example.com

+ + ); +} +``` + + + +### Use variables in the title {/*use-variables-in-the-title*/} + +The children of the `` component must be a single string of text. (Or a single number or a single object with a `toString` method.) It might not be obvious, but using JSX curly braces like this: + +```js +<title>Results page {pageNumber} // 🔴 Problem: This is not a single string +``` + +... actually causes the `` component to get a two-element array as its children (the string `"Results page"` and the value of `pageNumber`). This will cause an error. Instead, use string interpolation to pass `<title>` a single string: + +```js +<title>{`Results page ${pageNumber}`} +``` + diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 315ea3e0..08e0132a 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -218,6 +218,31 @@ { "title": "