diff --git a/public/images/docs/performance-tracks/changed-props.dark.png b/public/images/docs/performance-tracks/changed-props.dark.png new file mode 100644 index 00000000000..6709a7ea88e Binary files /dev/null and b/public/images/docs/performance-tracks/changed-props.dark.png differ diff --git a/public/images/docs/performance-tracks/changed-props.png b/public/images/docs/performance-tracks/changed-props.png new file mode 100644 index 00000000000..33efe928931 Binary files /dev/null and b/public/images/docs/performance-tracks/changed-props.png differ diff --git a/public/images/docs/performance-tracks/components-effects.dark.png b/public/images/docs/performance-tracks/components-effects.dark.png new file mode 100644 index 00000000000..57e3a30b09f Binary files /dev/null and b/public/images/docs/performance-tracks/components-effects.dark.png differ diff --git a/public/images/docs/performance-tracks/components-effects.png b/public/images/docs/performance-tracks/components-effects.png new file mode 100644 index 00000000000..ff315b99dfb Binary files /dev/null and b/public/images/docs/performance-tracks/components-effects.png differ diff --git a/public/images/docs/performance-tracks/components-render.dark.png b/public/images/docs/performance-tracks/components-render.dark.png new file mode 100644 index 00000000000..c0608b153fc Binary files /dev/null and b/public/images/docs/performance-tracks/components-render.dark.png differ diff --git a/public/images/docs/performance-tracks/components-render.png b/public/images/docs/performance-tracks/components-render.png new file mode 100644 index 00000000000..4367377670c Binary files /dev/null and b/public/images/docs/performance-tracks/components-render.png differ diff --git a/public/images/docs/performance-tracks/overview.dark.png b/public/images/docs/performance-tracks/overview.dark.png new file mode 100644 index 00000000000..07513fe90b8 Binary files /dev/null and b/public/images/docs/performance-tracks/overview.dark.png differ diff --git a/public/images/docs/performance-tracks/overview.png b/public/images/docs/performance-tracks/overview.png new file mode 100644 index 00000000000..835a247cf64 Binary files /dev/null and b/public/images/docs/performance-tracks/overview.png differ diff --git a/public/images/docs/performance-tracks/scheduler-cascading-update.dark.png b/public/images/docs/performance-tracks/scheduler-cascading-update.dark.png new file mode 100644 index 00000000000..beb4512d2d2 Binary files /dev/null and b/public/images/docs/performance-tracks/scheduler-cascading-update.dark.png differ diff --git a/public/images/docs/performance-tracks/scheduler-cascading-update.png b/public/images/docs/performance-tracks/scheduler-cascading-update.png new file mode 100644 index 00000000000..8631c4896f1 Binary files /dev/null and b/public/images/docs/performance-tracks/scheduler-cascading-update.png differ diff --git a/public/images/docs/performance-tracks/scheduler-update.dark.png b/public/images/docs/performance-tracks/scheduler-update.dark.png new file mode 100644 index 00000000000..df252663a4d Binary files /dev/null and b/public/images/docs/performance-tracks/scheduler-update.dark.png differ diff --git a/public/images/docs/performance-tracks/scheduler-update.png b/public/images/docs/performance-tracks/scheduler-update.png new file mode 100644 index 00000000000..79a361d2aa5 Binary files /dev/null and b/public/images/docs/performance-tracks/scheduler-update.png differ diff --git a/public/images/docs/performance-tracks/scheduler.dark.png b/public/images/docs/performance-tracks/scheduler.dark.png new file mode 100644 index 00000000000..7e48020f8ad Binary files /dev/null and b/public/images/docs/performance-tracks/scheduler.dark.png differ diff --git a/public/images/docs/performance-tracks/scheduler.png b/public/images/docs/performance-tracks/scheduler.png new file mode 100644 index 00000000000..1cd07a14478 Binary files /dev/null and b/public/images/docs/performance-tracks/scheduler.png differ diff --git a/src/content/reference/developer-tooling/react-performance-tracks.md b/src/content/reference/developer-tooling/react-performance-tracks.md new file mode 100644 index 00000000000..de22f9d809b --- /dev/null +++ b/src/content/reference/developer-tooling/react-performance-tracks.md @@ -0,0 +1,131 @@ +--- +title: React Performance tracks +version: canary +--- + + + +**This feature 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) + + + + + +React Performance tracks are specialized custom entries that appear on the Performance panel's timeline in your browser developer tools. + + + +These tracks are designed to provide developers with comprehensive insights into their React application's performance by visualizing React-specific events and metrics alongside other critical data sources such as network requests, JavaScript execution, and event loop activity, all synchronized on a unified timeline within the Performance panel for a complete understanding of application behavior. + +
+ React Performance Tracks + React Performance Tracks +
+ + + +--- + +## Usage {/*usage*/} + +React Performance tracks are only available in development and profiling builds of React: + +- **Development**: enabled by default. +- **Profiling**: you can either wrap a subtree that you want to instrument with [``](/reference/react/Profiler) component or have [React Developer Tools extension](/learn/react-developer-tools) enabled. + +If enabled, tracks should appear automatically in the traces you record with the Performance panel of browsers that provide [extensibility APIs](https://developer.chrome.com/docs/devtools/performance/extension). + + + +The profiling instrumentation that powers React Performance tracks adds some additional overhead, so it is disabled in production builds by default. + + + +--- + +## Tracks {/*tracks*/} + +### Scheduler {/*scheduler*/} + +The Scheduler is an internal React concept used for managing tasks with different priorities. This track consists of 4 subtracks, each representing work of a specific priority: + +- **Blocking** - The synchronous updates, which could've been initiated by user interactions. +- **Transition** - Non-blocking work that happens in the background, usually initiated via [`startTransition`](/reference/react/startTransition). +- **Suspense** - Work related to Suspense boundaries, such as displaying fallbacks or revealing content. +- **Idle** - The lowest priority work that is done when there are no other tasks with higher priority. + +
+ Scheduler track + Scheduler track +
+ +#### Renders {/*renders*/} + +Every render pass consists of multiple phases that you can see on a timeline: + +- **Update** - this is what caused a new render pass. +- **Render** - React renders the updated subtree by calling render functions of components. You can see the rendered components subtree on [Components track](/reference/developer-tooling/react-performance-tracks#components), which follows the same color scheme. +- **Commit** - After rendering components, React will submit the changes to the DOM and run layout effects, like [`useLayoutEffect`](/reference/react/useLayoutEffect). +- **Remaining Effects** - React runs passive effects of a rendered subtree. This usually happens after the paint, and this is when React runs hooks like [`useEffect`](/reference/react/useEffect). One known exception is user interactions, like clicks, or other discrete events. In this scenario, this phase could run before the paint. + +
+ Scheduler track: updates + Scheduler track: updates +
+ +[Learn more about renders and commits](/learn/render-and-commit). + +#### Cascading updates {/*cascading-updates*/} + +Cascading updates is one of the patterns for performance regressions. If an update was scheduled during a render pass, React could discard completed work and start a new pass. + +In development builds, React can show you which Component scheduled a new update. This includes both general updates and cascading ones. You can see the enhanced stack trace by clicking on the "Cascading update" entry, which should also display the name of the method that scheduled an update. + +
+ Scheduler track: cascading updates + Scheduler track: cascading updates +
+ +[Learn more about Effects](/learn/you-might-not-need-an-effect). + +### Components {/*components*/} + +The Components track visualizes the durations of React components. They are displayed as a flamegraph, where each entry represents the duration of the corresponding component render and all its descendant children components. + +
+ Components track: render durations + Components track: render durations +
+ +Similar to render durations, effect durations are also represented as a flamegraph, but with a different color scheme that aligns with the corresponding phase on the Scheduler track. + +
+ Components track: effects durations + Components track: effects durations +
+ + + +Unlike renders, not all effects are shown on the Components track by default. + +To maintain performance and prevent UI clutter, React will only display those effects, which had a duration of 0.05ms or longer, or triggered an update. + + + +Additional events may be displayed during the render and effects phases: + +- Mount - A corresponding subtree of component renders or effects was mounted. +- Unmount - A corresponding subtree of component renders or effects was unmounted. +- Reconnect - Similar to Mount, but limited to cases when [``](/reference/react/Activity) is used. +- Disconnect - Similar to Unmount, but limited to cases when [``](/reference/react/Activity) is used. + +#### Changed props {/*changed-props*/} + +In development builds, when you click on a component render entry, you can inspect potential changes in props. You can use this information to identify unnecessary renders. + +
+ Components track: changed props + Components track: changed props +
diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 67935b45978..64e47914a10 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -378,6 +378,14 @@ "title": "Compiling Libraries", "path": "/reference/react-compiler/compiling-libraries" }, + { + "hasSectionHeader": true, + "sectionHeader": "Developer tooling" + }, + { + "title": "React Performance tracks", + "path": "/reference/developer-tooling/react-performance-tracks" + }, { "hasSectionHeader": true, "sectionHeader": "eslint-plugin-react-hooks" @@ -429,7 +437,7 @@ "path": "/reference/eslint-plugin-react-hooks/lints/incompatible-library", "version": "rc" }, - + { "title": "preserve-manual-memoization", "path": "/reference/eslint-plugin-react-hooks/lints/preserve-manual-memoization", @@ -445,7 +453,7 @@ "path": "/reference/eslint-plugin-react-hooks/lints/refs", "version": "rc" }, - + { "title": "set-state-in-effect", "path": "/reference/eslint-plugin-react-hooks/lints/set-state-in-effect",