From c68c36f73be978949e5eb1589e230fb9bd0d6f50 Mon Sep 17 00:00:00 2001 From: dan Date: Mon, 12 Dec 2022 17:57:10 +0000 Subject: [PATCH] [Beta] Profiler API (#5355) --- beta/src/content/apis/react/Fragment.md | 8 +- beta/src/content/apis/react/Profiler.md | 126 +++++++++++++++++++++- beta/src/content/apis/react/StrictMode.md | 2 +- beta/src/content/apis/react/Suspense.md | 8 +- beta/src/sidebarAPIs.json | 3 +- 5 files changed, 132 insertions(+), 15 deletions(-) diff --git a/beta/src/content/apis/react/Fragment.md b/beta/src/content/apis/react/Fragment.md index 4ccfe75ab..07bc7410a 100644 --- a/beta/src/content/apis/react/Fragment.md +++ b/beta/src/content/apis/react/Fragment.md @@ -1,10 +1,10 @@ --- -title: Fragment (<>...) +title: (<>...) --- -The `Fragment` component, which is often used via the `<>...` syntax, lets you render multiple elements in place of one, without wrapping them in any other container element. +``, often used via `<>...` syntax, lets you group elements without a wrapper node. ```js <> @@ -195,11 +195,11 @@ function PostBody({ body }) { ## Reference {/*reference*/} -### `Fragment` {/*fragment*/} +### `` {/*fragment*/} Wrap elements in `` to group them together in situations where you need a single element. Grouping elements in `Fragment` has no effect on the resulting DOM; it is the same as if the elements were not grouped. The empty JSX tag `<>` is shorthand for `` in most cases. -#### Props {/*fragment-props*/} +#### Props {/*props*/} - **optional** `key`: Fragments declared with the explicit `` syntax may have [keys.](https://beta.reactjs.org/learn/rendering-lists#keeping-list-items-in-order-with-key) diff --git a/beta/src/content/apis/react/Profiler.md b/beta/src/content/apis/react/Profiler.md index efb7712c7..fc7cdde5a 100644 --- a/beta/src/content/apis/react/Profiler.md +++ b/beta/src/content/apis/react/Profiler.md @@ -1,11 +1,129 @@ --- -title: Profiler +title: --- - + -This section is incomplete, please see the old docs for [Profiler.](https://reactjs.org/docs/profiler.html) +`` lets you measure rendering performance of a React tree programmatically. - +```js + + + +``` + + + +--- + +## Usage {/*usage*/} + +### Measuring rendering performance programmatically {/*measuring-rendering-performance-programmatically*/} + +Wrap the `` component around a React tree to measure its rendering performance. + +```js {2,4} + + + + + + +``` + +It requires two props: an `id` (string) and an `onRender` callback (function) which React calls any time a component within the tree "commits" an update. + + + +Profiling adds some additional overhead, so **it is disabled in the production build by default.** To opt into production profiling, you need to enable a [special production build with profiling enabled.](https://fb.me/react-profiling) + + + + + +`` lets you gather measurements programmatically. If you're looking for an interactive profiler, try the Profiler tab in [React Developer Tools](/learn/react-developer-tools). It exposes similar functionality as a browser extension. + + + +--- + +### Measuring different parts of the application {/*measuring-different-parts-of-the-application*/} + +You can use multiple `` components to measure different parts of your application: + +```js {5,7} + + + + + + + + +``` + +You can also nest `` components: + +```js {5,7,9,12} + + + + + + + + + + + + + +``` + +Although `` is a lightweight component, it should be used only when necessary. Each use adds some CPU and memory overhead to an application. + +--- + +## Reference {/*reference*/} + +### `` {/*profiler*/} + +Wrap a component tree in a `` to measure its rendering performance. + +```js + + + +``` + +#### Props {/*props*/} + +* `id`: A string identifying the part of the UI you are measuring. +* `onRender`: An [`onRender` callback](#onrender-callback) that React calls it every time components within the profiled tree update. It receives information about what was rendered and how much time it took. + +#### Caveats {/*caveats*/} + +* Profiling adds some additional overhead, so **it is disabled in the production build by default.** To opt into production profiling, you need to enable a [special production build with profiling enabled.](https://fb.me/react-profiling) + +--- + +### `onRender` callback {/*onrender-callback*/} + +React will call your `onRender` callback with information about what was rendered. + +```js +function onRender(id, phase, actualDuration, baseDuration, startTime, commitTime) { + // Aggregate or log render timings... +} +``` + +#### Parameters {/*onrender-parameters*/} + +* `id`: The string `id` prop of the `` tree that has just committed. This lets you identify which part of the tree was committed if you are using multiple profilers. +* `phase`: Either `"mount"` or `"update"`. This lets you know whether the tree has just been mounted for the first time or re-rendered due to a change in props, state, or hooks. +* `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`](/apis/react/memo) and [`useMemo`](/apis/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. diff --git a/beta/src/content/apis/react/StrictMode.md b/beta/src/content/apis/react/StrictMode.md index e58050873..168c054aa 100644 --- a/beta/src/content/apis/react/StrictMode.md +++ b/beta/src/content/apis/react/StrictMode.md @@ -1,5 +1,5 @@ --- -title: StrictMode +title: --- diff --git a/beta/src/content/apis/react/Suspense.md b/beta/src/content/apis/react/Suspense.md index 6425cb80f..dc690d7e5 100644 --- a/beta/src/content/apis/react/Suspense.md +++ b/beta/src/content/apis/react/Suspense.md @@ -1,10 +1,10 @@ --- -title: Suspense +title: --- -`Suspense` is a React component that displays a fallback until its children have finished loading. +`` lets you displays a fallback until its children have finished loading. ```js @@ -2523,9 +2523,9 @@ The server HTML will include the loading indicator. It will be replaced by the ` ## Reference {/*reference*/} -### `Suspense` {/*suspense*/} +### `` {/*suspense*/} -#### Props {/*suspense-props*/} +#### Props {/*props*/} * `children`: The actual UI you intend to render. If `children` suspends while rendering, the Suspense boundary will switch to rendering `fallback`. * `fallback`: An alternate UI to render in place of the actual UI if it has not finished loading. Any valid React node is accepted, though in practice, a fallback is a lightweight placeholder view, such as a loading spinner or skeleton. Suspense will automatically switch to `fallback` when `children` suspends, and back to `children` when the data is ready. If `fallback` suspends while rendering, it will activate the closest parent Suspense boundary. diff --git a/beta/src/sidebarAPIs.json b/beta/src/sidebarAPIs.json index cf248b533..61a63bfc0 100644 --- a/beta/src/sidebarAPIs.json +++ b/beta/src/sidebarAPIs.json @@ -85,8 +85,7 @@ }, { "title": "", - "path": "/apis/react/Profiler", - "wip": true + "path": "/apis/react/Profiler" }, { "title": "",