From 375e46b8dff6951beb977d630ddcaeab787868a1 Mon Sep 17 00:00:00 2001 From: Brian Vaughn Date: Sat, 27 Jul 2019 15:59:10 -0700 Subject: [PATCH 1/4] First pass at Profiler API docs --- content/blog/2019-08-01-react-v-16-9.md | 31 ++++++ content/docs/nav.yml | 2 + content/docs/reference-profiler.md | 119 ++++++++++++++++++++++++ package.json | 3 +- 4 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 content/blog/2019-08-01-react-v-16-9.md create mode 100644 content/docs/reference-profiler.md diff --git a/content/blog/2019-08-01-react-v-16-9.md b/content/blog/2019-08-01-react-v-16-9.md new file mode 100644 index 00000000000..ee3152525a7 --- /dev/null +++ b/content/blog/2019-08-01-react-v-16-9.md @@ -0,0 +1,31 @@ +--- +title: "React v16.0.0" +author: [bvaughn] +--- + +Other release notes here... + +## [`React.Profiler`](/docs/profiler.html) {#profiler} + +The `Profiler` measures how often a React application renders and what the "cost" of rendering is. Its purpose is to help identify parts of an application that are slow and may benefit from optimizations such as memoization. + +The profiler accepts a callback function ([`onRender`](/docs/profiler.html#onrender-callback)) which React calls any time a descendant component "commits" an update. + +```js{2,7} +render( + + + +
+ + +); +``` + +To learn more about the `Profiler` and the parameters passed to the `onRender` callback, check out [the `Profiler` docs](/docs/profiler.html). + +> Note: This profiler does not record times in production mode. +> +> Profiling adds some additional overhead, so it is disabled in the production build. +> React provides a special production build with profiling enabled. +> Read more about how to use this bundle at [fb.me/react-profiling](https://fb.me/react-profiling) diff --git a/content/docs/nav.yml b/content/docs/nav.yml index 4d4a7571f3a..8e98ea4d04e 100644 --- a/content/docs/nav.yml +++ b/content/docs/nav.yml @@ -59,6 +59,8 @@ title: Optimizing Performance - id: portals title: Portals + - id: profiler + title: Profiler - id: react-without-es6 title: React Without ES6 - id: react-without-jsx diff --git a/content/docs/reference-profiler.md b/content/docs/reference-profiler.md new file mode 100644 index 00000000000..f1aea52eadc --- /dev/null +++ b/content/docs/reference-profiler.md @@ -0,0 +1,119 @@ +--- +id: profiler +title: Profiler API +layout: docs +category: Reference +permalink: docs/profiler.html +--- + +The `Profiler` measures how often a React application renders and what the "cost" of rendering is. +Its purpose is to help identify parts of an application that are slow and may benefit from [optimizations such as memoization](https://reactjs.org/docs/hooks-faq.html#how-to-memoize-calculations). + +> Note: +> +> Profiling adds some additional overhead, so **it is disabled in [the production build](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build)**. +> +> To opt into production profiling, React provides a special production build with profiling enabled. +> Read more about how to use this build at [fb.me/react-profiling](https://fb.me/react-profiling) + +## Usage + +A `Profiler` can be added anywhere within a React tree to measure the cost of rendering that part of the tree. +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. + +For example, to profile a `Navigation` component and its descendants: + +```js{3} +render( + + + + +
+ +); +``` + +Multiple `Profiler` components can be used to measure different parts of an application: +```js{3,6} +render( + + + + + +
+ + +); +``` + +`Profiler` components can also be nested to measure different components within the same subtree: +```js{2,6,8} +render( + + + + + + + + + + + + +); +``` + +> Note +> +> Although `Profiler` is a light-weight component, it should be used only when necessary; each use adds some CPU and memory overhead to an application. + +## `onRender` Callback + +The `Profiler` requires an `onRender` function as a prop. +React calls calls this function any time a component within the profiled tree "commits" an update. +It receives parameters describing what was rendered and how long it took. + +```js +function onRenderCallback( + id, // the "id" prop of the Profiler tree that has just committed + phase, // either "mount" (if the tree just mounted) or "update" (if it re-rendered) + actualDuration, // time spent rendering the committed update + baseDuration, // estimated time to render the entire subtree without memoization + startTime, // when React began rendering this update + commitTime, // when React committed this update + interactions // the Set of interactions belonging to this update +) { + // Aggregate or log render timings... +} +``` + +Let's take a closer look at each of the props: + +* **`id: string`** - +The `id` prop of the `Profiler` tree that has just committed. +This can be used to identify which tree was committed if a shared callback is used to profile multiple parts of an application. +* **`phase: "mount" | "update"`** - +Identifies whether the tree has just been mounted for the first time or re-rendered due to a change in `props`, `state`, or hooks. +* **`actualDuration: number`** - +Time spent rendering the `Profiler` and its descendants for the current update. +This indicates how well the subtree makes use of memoization (e.g. [`React.memo`](/docs/react-api.html#reactmemo), [`useMemo`](/docs/hooks-reference.html#usememo), [`shouldComponentUpdate`](/docs/hooks-faq.html#how-do-i-implement-shouldcomponentupdate)). +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: number`** - +Duration of the most recent `render` time for each individual component within the `Profiler` tree. +This value estimates a worst-case cost of rendering (e.g. the initial mount or a tree with no memoization). +* **`startTime: number`** - +Timestamp when React began rendering the current update. +* **`commitTime: number`** - +Timestamp when React committed the current update. +This value is shared between all `Profiler`s in a commit, enabling them to be grouped if desirable. +* **`interactions: Set`** - +Set of ["interactions"](http://fb.me/react-interaction-tracing) that were being traced the update was scheduled (e.g. when `render` or `setState` were called). + +> Note +> +> Interactions can be used to identify the cause of an update, althoguh the API for tracing them is still experimental. +> +> Learn more about it at [fb.me/react-interaction-tracing](http://fb.me/react-interaction-tracing) \ No newline at end of file diff --git a/package.json b/package.json index ba61ccc95bd..10ed4e01a0a 100644 --- a/package.json +++ b/package.json @@ -86,7 +86,8 @@ "nit:examples": "prettier --config examples/.prettierrc --list-different \"examples/**/*.js\"", "prettier": "yarn format:source && yarn format:examples", "prettier:diff": "yarn nit:source && yarn nit:examples", - "reset": "rimraf ./.cache" + "reset": "rimraf ./.cache", + "start": "yarn dev" }, "devDependencies": { "@babel/preset-flow": "^7.0.0", From e6d718c3cc4182fa7cb22e5145e3303844151814 Mon Sep 17 00:00:00 2001 From: Brian Vaughn Date: Sun, 28 Jul 2019 09:11:04 -0700 Subject: [PATCH 2/4] Small wording tweaks --- content/blog/2019-08-01-react-v-16-9.md | 14 ++++++++------ content/docs/reference-profiler.md | 10 +++++----- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/content/blog/2019-08-01-react-v-16-9.md b/content/blog/2019-08-01-react-v-16-9.md index ee3152525a7..96a4b4a94c6 100644 --- a/content/blog/2019-08-01-react-v-16-9.md +++ b/content/blog/2019-08-01-react-v-16-9.md @@ -7,9 +7,10 @@ Other release notes here... ## [`React.Profiler`](/docs/profiler.html) {#profiler} -The `Profiler` measures how often a React application renders and what the "cost" of rendering is. Its purpose is to help identify parts of an application that are slow and may benefit from optimizations such as memoization. +The `Profiler` measures how often a React application renders and what the "cost" of rendering is. Its purpose is to help identify parts of an application that are slow and may benefit from [optimizations such as memoization](/docs/hooks-faq.html#how-to-memoize-calculations). -The profiler accepts a callback function ([`onRender`](/docs/profiler.html#onrender-callback)) which React calls any time a descendant component "commits" an update. +A `Profiler` can be added anywhere in a React tree to measure the cost of rendering that part of the tree. +It requires two props: an `id` (string) and an [`onRender` callback](/docs/profiler.html#onrender-callback) (function) which React calls any time a component within the tree "commits" an update. ```js{2,7} render( @@ -24,8 +25,9 @@ render( To learn more about the `Profiler` and the parameters passed to the `onRender` callback, check out [the `Profiler` docs](/docs/profiler.html). -> Note: This profiler does not record times in production mode. +> Note: > -> Profiling adds some additional overhead, so it is disabled in the production build. -> React provides a special production build with profiling enabled. -> Read more about how to use this bundle at [fb.me/react-profiling](https://fb.me/react-profiling) +> Profiling adds some additional overhead, so **it is disabled in [the production build](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build)**. +> +> To opt into production profiling, React provides a special production build with profiling enabled. +> Read more about how to use this build at [fb.me/react-profiling](https://fb.me/react-profiling) diff --git a/content/docs/reference-profiler.md b/content/docs/reference-profiler.md index f1aea52eadc..a7cc5f2799e 100644 --- a/content/docs/reference-profiler.md +++ b/content/docs/reference-profiler.md @@ -18,7 +18,7 @@ Its purpose is to help identify parts of an application that are slow and may be ## Usage -A `Profiler` can be added anywhere within a React tree to measure the cost of rendering that part of the tree. +A `Profiler` can be added anywhere in a React tree to measure the cost of rendering that part of the tree. 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. For example, to profile a `Navigation` component and its descendants: @@ -94,13 +94,13 @@ Let's take a closer look at each of the props: * **`id: string`** - The `id` prop of the `Profiler` tree that has just committed. -This can be used to identify which tree was committed if a shared callback is used to profile multiple parts of an application. +This can be used to identify which part of the tree was committed if you are using multiple profilers. * **`phase: "mount" | "update"`** - -Identifies whether the tree has just been mounted for the first time or re-rendered due to a change in `props`, `state`, or hooks. +Identifies whether the tree has just been mounted for the first time or re-rendered due to a change in props, state, or hooks. * **`actualDuration: number`** - Time spent rendering the `Profiler` and its descendants for the current update. This indicates how well the subtree makes use of memoization (e.g. [`React.memo`](/docs/react-api.html#reactmemo), [`useMemo`](/docs/hooks-reference.html#usememo), [`shouldComponentUpdate`](/docs/hooks-faq.html#how-do-i-implement-shouldcomponentupdate)). -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. +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: number`** - Duration of the most recent `render` time for each individual component within the `Profiler` tree. This value estimates a worst-case cost of rendering (e.g. the initial mount or a tree with no memoization). @@ -108,7 +108,7 @@ This value estimates a worst-case cost of rendering (e.g. the initial mount or a Timestamp when React began rendering the current update. * **`commitTime: number`** - Timestamp when React committed the current update. -This value is shared between all `Profiler`s in a commit, enabling them to be grouped if desirable. +This value is shared between all profilers in a commit, enabling them to be grouped if desirable. * **`interactions: Set`** - Set of ["interactions"](http://fb.me/react-interaction-tracing) that were being traced the update was scheduled (e.g. when `render` or `setState` were called). From 7d330f83ba18d4105cbfe234088993915ebc11ea Mon Sep 17 00:00:00 2001 From: Brian Vaughn Date: Sun, 28 Jul 2019 09:14:08 -0700 Subject: [PATCH 3/4] Added wording about arbitrary release date to fake blog post --- content/blog/2019-08-01-react-v-16-9.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/blog/2019-08-01-react-v-16-9.md b/content/blog/2019-08-01-react-v-16-9.md index 96a4b4a94c6..f5de425f0f0 100644 --- a/content/blog/2019-08-01-react-v-16-9.md +++ b/content/blog/2019-08-01-react-v-16-9.md @@ -3,7 +3,9 @@ title: "React v16.0.0" author: [bvaughn] --- -Other release notes here... +The release date above is arbitrary and should be ignored. + +Other v16.6 release notes would go here. ## [`React.Profiler`](/docs/profiler.html) {#profiler} From ab6a07af6fc97fb6dca8de38a8b3c9a7593720d4 Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Thu, 8 Aug 2019 20:03:18 +0100 Subject: [PATCH 4/4] This is in https://github.com/reactjs/reactjs.org/pull/2208 now --- content/blog/2019-08-01-react-v-16-9.md | 35 ------------------------- 1 file changed, 35 deletions(-) delete mode 100644 content/blog/2019-08-01-react-v-16-9.md diff --git a/content/blog/2019-08-01-react-v-16-9.md b/content/blog/2019-08-01-react-v-16-9.md deleted file mode 100644 index f5de425f0f0..00000000000 --- a/content/blog/2019-08-01-react-v-16-9.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "React v16.0.0" -author: [bvaughn] ---- - -The release date above is arbitrary and should be ignored. - -Other v16.6 release notes would go here. - -## [`React.Profiler`](/docs/profiler.html) {#profiler} - -The `Profiler` measures how often a React application renders and what the "cost" of rendering is. Its purpose is to help identify parts of an application that are slow and may benefit from [optimizations such as memoization](/docs/hooks-faq.html#how-to-memoize-calculations). - -A `Profiler` can be added anywhere in a React tree to measure the cost of rendering that part of the tree. -It requires two props: an `id` (string) and an [`onRender` callback](/docs/profiler.html#onrender-callback) (function) which React calls any time a component within the tree "commits" an update. - -```js{2,7} -render( - - - -
- - -); -``` - -To learn more about the `Profiler` and the parameters passed to the `onRender` callback, check out [the `Profiler` docs](/docs/profiler.html). - -> Note: -> -> Profiling adds some additional overhead, so **it is disabled in [the production build](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build)**. -> -> To opt into production profiling, React provides a special production build with profiling enabled. -> Read more about how to use this build at [fb.me/react-profiling](https://fb.me/react-profiling)