{"files":[{"status":"M","path":"packages\/react-devtools\/CHANGELOG.md"},{"status":"A","path":"packages\/react-devtools\/OVERVIEW.md"}],"body":"","patch":"diff --git a\/packages\/react-devtools\/CHANGELOG.md b\/packages\/react-devtools\/CHANGELOG.md\nindex 6ae043731f..47c21f16b1 100644\n--- a\/packages\/react-devtools\/CHANGELOG.md\n+++ b\/packages\/react-devtools\/CHANGELOG.md\n@@ -17,7 +17,7 @@\n #### Improved performance\n The legacy DevTools extension used to add significant performance overhead, making it unusable for some larger React applications. That overhead has been effectively eliminated in version 4.\n \n-[Learn more](https:\/\/github.com\/bvaughn\/react-devtools-experimental\/blob\/master\/OVERVIEW.md) about the performance optimizations that made this possible.\n+[Learn more](https:\/\/github.com\/facebook\/react\/blob\/master\/packages\/react-devtools\/OVERVIEW.md) about the performance optimizations that made this possible.\n \n #### Component stacks\n \n@@ -43,7 +43,7 @@ Filter preferences are remembered between sessions.\n \n #### No more in-line props\n \n-Components in the tree no longer show in-line props. This was done to [make DevTools faster](https:\/\/github.com\/bvaughn\/react-devtools-experimental\/blob\/master\/OVERVIEW.md) and to make it easier to browse larger component trees.\n+Components in the tree no longer show in-line props. This was done to [make DevTools faster](https:\/\/github.com\/facebook\/react\/blob\/master\/packages\/react-devtools\/OVERVIEW.md) and to make it easier to browse larger component trees.\n \n You can view a component's props, state, and hooks by selecting it:\n \ndiff --git a\/packages\/react-devtools\/OVERVIEW.md b\/packages\/react-devtools\/OVERVIEW.md\nnew file mode 100644\nindex 0000000000..7c82287913\n--- \/dev\/null\n+++ b\/packages\/react-devtools\/OVERVIEW.md\n@@ -0,0 +1,270 @@\n+# Overview\n+\n+The React DevTools extension consists of multiple pieces:\n+* The **frontend** portion is the extension you see (the Components tree, the Profiler, etc.).\n+* The **backend** portion is invisible. It runs in the same context as React itself. When React commits changes to e.g. the DOM, the backend is responsible for notifying the frontend by sending a message through the **bridge** (an abstraction around e.g. `postMessage`).\n+\n+One of the largest performance bottlenecks of the old React DevTools was the amount of bridge traffic. Each time React commits an update, the backend sends every fiber that changed across the bridge, resulting in a lot of (JSON) serialization. The primary goal for the DevTools rewrite was to reduce this traffic. Instead of sending everything across the bridge, **the backend should only send the minimum amount required to render the Components tree**. The frontend can request more information (e.g. an element's props) on demand, only as needed.\n+\n+The old DevTools also rendered the entire application tree in the form of a large DOM structure of nested nodes. A secondary goal of the rewrite was to avoid rendering unnecessary nodes by using a windowing library (specifically [react-window](https:\/\/github.com\/bvaughn\/react-window)).\n+\n+## Components panel\n+\n+### Serializing the tree\n+\n+Every React commit that changes the tree in a way DevTools cares about results in an \"_operations_\" message being sent across the bridge. These messages are lightweight patches that describe the changes that were made. (We don't resend the full tree structure like in legacy DevTools.)\n+\n+The payload for each message is a typed array. The first two entries are numbers that identify which renderer and root the update belongs to (for multi-root support). Then the strings are encoded in a [string table](#string-table). The rest of the array depends on the operations being made to the tree.\n+\n+No updates are required for most commits because we only send the following bits of information: element type, id, parent id, owner id, name, and key. Additional information (e.g. props, state) requires a separate [\"_inspectElement_\" message](#inspecting-an-element).\n+\n+#### String table\n+\n+The string table is encoded right after the first two numbers.\n+\n+It consists of:\n+\n+1. the total length of next items that belong to string table\n+2. for each string in a table:\n+ 1. encoded size\n+ 2. a list of its UTF encoded codepoints\n+\n+For example, for `Foo` and `Bar` we would see:\n+\n+```\n+[\n+ 8, \/\/ string table length\n+ 3, \/\/ encoded display name size\n+ 70, \/\/ \"F\"\n+ 111, \/\/ \"o\"\n+ 111, \/\/ \"o\"\n+ 3, \/\/ encoded display name size\n+ 66, \/\/ \"B\"\n+ 97, \/\/ \"a\"\n+ 114, \/\/ \"r\"\n+]\n+```\n+\n+Later operations will reference strings by a one-based index. For example, `1` would mean `\"Foo\"`, and `2` would mean `\"Bar\"`. The `0` string id always represents `null` and isn't explicitly encoded in the table.\n+\n+#### Adding a root node\n+\n+Adding a root to the tree requires sending 4 numbers:\n+\n+1. add operation constant (`1`)\n+1. fiber id\n+1. element type constant (`8 === ElementTypeRoot`)\n+1. profiling supported flag\n+\n+For example, adding a root fiber with an id of 1:\n+```js\n+[\n+ 1, \/\/ add operation\n+ 1, \/\/ fiber id\n+ 8, \/\/ ElementTypeRoot\n+ 1, \/\/ this root's renderer supports profiling\n+]\n+```\n+\n+#### Adding a leaf node\n+\n+Adding a leaf node takes a variable number of numbers since we need to decode the name (and potentially the key):\n+\n+1. add operation constant (`1`)\n+1. fiber id\n+1. element type constant (e.g. `1 === ElementTypeClass`)\n+1. parent fiber id\n+1. owner fiber id\n+1. string table id for `displayName`\n+1. string table id for `key`\n+\n+For example, adding a function component `` with an id 2:\n+```js\n+[\n+ 1, \/\/ add operation\n+ 2, \/\/ fiber id\n+ 1, \/\/ ElementTypeClass\n+ 1, \/\/ parent id\n+ 0, \/\/ owner id\n+ 3, \/\/ encoded display name size\n+ 1, \/\/ id of \"Foo\" displayName in the string table\n+ 0, \/\/ id of null key in the string table (always zero for null)\n+]\n+```\n+\n+#### Removing a node\n+\n+Removing a fiber from the tree (a root or a leaf) requires sending:\n+\n+1. remove operation constant (`2`)\n+1. how many items were removed\n+1. number of children\n+ * (followed by a children-first list of removed fiber ids)\n+\n+For example, removing fibers with ids of 35 and 21:\n+```js\n+[\n+ 2, \/\/ remove operation\n+ 2, \/\/ number of removed fibers\n+ 35, \/\/ first removed id\n+ 21, \/\/ second removed id\n+]\n+```\n+\n+#### Re-ordering children\n+\n+1. re-order children constant (`3`)\n+1. fiber id\n+1. number of children\n+ * (followed by an ordered list of child fiber ids)\n+\n+For example:\n+```js\n+[\n+ 3, \/\/ re-order operation\n+ 15, \/\/ fiber id\n+ 2, \/\/ number of children\n+ 35, \/\/ first child id\n+ 21, \/\/ second child id\n+]\n+```\n+\n+#### Updating tree base duration\n+\n+While profiling is in progress, we send an extra operation any time a fiber is added or a updated in a way that affects its tree base duration. This information is needed by the Profiler UI in order to render the \"snapshot\" and \"ranked\" chart views.\n+\n+1. tree base duration constant (`4`)\n+1. fiber id\n+1. tree base duration\n+\n+For example, updating the base duration for a fiber with an id of 1:\n+```js\n+[\n+ 4, \/\/ tree base duration operation\n+ 1, \/\/ fiber id\n+ 32, \/\/ new tree base duration value\n+]\n+```\n+\n+## Reconstructing the tree\n+\n+The frontend stores its information about the tree in a map of id to objects with the following keys:\n+\n+* id: `number`\n+* parentID: `number`\n+* children: `Array`\n+* type: `number` (constant)\n+* displayName: `string | null`\n+* key: `number | string | null`\n+* ownerID: `number`\n+* depth: `number` ^{1<\/sup>\n+* weight: `number` ^{2<\/sup>\n+\n+^{1<\/sup> The `depth` value determines how much padding\/indentation to use for the element when rendering it in the Components panel. (This preserves the appearance of a nested tree, even though the view is a flat list.)\n+\n+^{2<\/sup> The `weight` of an element is the number of elements (including itself) below it in the tree. We cache this property so that we can quickly determine the total number of Components as well as to find the Nth element within that set. (This enables us to use windowing.) This value needs to be adjusted each time elements are added or removed from the tree, but we amortize this over time to avoid any big performance hits when rendering the tree.\n+\n+#### Finding the element at index N\n+\n+The tree data structure lets us impose an order on elements and \"quickly\" find the Nth one using the `weight` attribute.\n+\n+First we find which root contains the index:\n+```js\n+let rootID;\n+let root;\n+let rootWeight = 0;\n+for (let i = 0; i < this._roots.length; i++) {\n+ rootID = this._roots[i];\n+ root = this._idToElement.get(rootID);\n+ if (root.children.length === 0) {\n+ continue;\n+ } else if (rootWeight + root.weight > index) {\n+ break;\n+ } else {\n+ rootWeight += root.weight;\n+ }\n+}\n+```\n+\n+We skip the root itself because don't display them in the tree:\n+```js\n+const firstChildID = root.children[0];\n+```\n+\n+Then we traverse the tree to find the element:\n+```js\n+let currentElement = this._idToElement.get(firstChildID);\n+let currentWeight = rootWeight;\n+while (index !== currentWeight) {\n+ for (let i = 0; i < currentElement.children.length; i++) {\n+ const childID = currentElement.children[i];\n+ const child = this._idToElement.get(childID);\n+ const { weight } = child;\n+ if (index <= currentWeight + weight) {\n+ currentWeight++;\n+ currentElement = child;\n+ break;\n+ } else {\n+ currentWeight += weight;\n+ }\n+ }\n+}\n+```\n+\n+## Inspecting an element\n+\n+When an element is mounted in the tree, DevTools sends a minimal amount of information about it across the bridge. This information includes its display name, type, and key- but does _not_ include things like props or state. (These values are often expensive to serialize and change frequently, which would add a significant amount of load to the bridge.)\n+\n+Instead DevTools lazily requests additional information about an element only when it is selected in the \"Components\" tab. At that point, the frontend requests this information by sending a special \"_inspectElement_\" message containing the id of the element being inspected. The backend then responds with an \"_inspectedElement_\" message containing the additional details.\n+\n+### Polling strategy\n+\n+Elements can update frequently, especially in response to things like scrolling events. Since props and state can be large, we avoid sending this information across the bridge every time the selected element is updated. Instead, the frontend polls the backend for updates about once a second. The backend tracks when the element was last \"inspected\" and sends a special no-op response if it has not re-rendered since then.\n+\n+### Deeply nested properties\n+\n+Even when dealing with a single component, serializing deeply nested properties can be expensive. Because of this, DevTools uses a technique referred to as \"dehyration\" to only send a shallow copy of the data on initial inspection. DevTools then fills in the missing data on demand as a user expands nested objects or arrays. Filled in paths are remembered (for the currently inspected element) so they are not \"dehyrated\" again as part of a polling update.\n+\n+### Inspecting hooks\n+\n+Hooks present a unique challenge for the DevTools because of the concept of _custom_ hooks. (A custom hook is essentially any function that calls at least one of the built-in hooks. By convention custom hooks also have names that begin with \"use\".)\n+\n+So how does DevTools identify custom functions called from within third party components? It does this by temporarily overriding React's built-in hooks and shallow rendering the component in question. Whenever one of the (overridden) built-in hooks are called, it parses the call stack to spot potential custom hooks (functions between the component itself and the built-in hook). This approach enables it to build a tree structure describing all of the calls to both the built-in _and_ custom hooks, along with the values passed to those hooks. (If you're interested in learning more about this, [here is the source code](https:\/\/github.com\/facebook\/react\/blob\/master\/packages\/react-debug-tools\/src\/ReactDebugHooks.js).)\n+\n+> **Note**: DevTools obtains hooks info by re-rendering a component.\n+> Breakpoints will be invoked during this additional (shallow) render,\n+> but DevTools temporarily overrides `console` methods to suppress logging.\n+\n+### Performance implications\n+\n+To mitigate the performance impact of re-rendering a component, DevTools does the following:\n+* Only function components that use _at least one hook_ are rendered. (Props and state can be analyzed without rendering.)\n+* Rendering is always shallow.\n+* Rendering is throttled to occur, at most, once per second.\n+* Rendering is skipped if the component has not updated since the last time its properties were inspected.\n+\n+## Profiler\n+\n+The Profiler UI is a powerful tool for identifying and fixing performance problems. The primary goal of the new profiler is to minimize its impact (CPU usage) while profiling is active. This can be accomplished by:\n+* Minimizing bridge traffic.\n+* Making expensive computations lazy.\n+\n+The majority of profiling information is stored on the backend. The backend push-notifies the frontend of when profiling starts or stops by sending a \"_profilingStatus_\" message. The frontend also asks for the current status after mounting by sending a \"_getProfilingStatus_\" message. (This is done to support the reload-and-profile functionality.)\n+\n+When profiling begins, the frontend takes a snapshot\/copy of each root. This snapshot includes the id, name, key, and child IDs for each node in the tree. (This information is already present on the frontend, so it does not require any additional bridge traffic.) While profiling is active, each time React commits– the frontend also stores a copy of the \"_operations_\" message (described above). Once profiling has finished, the frontend can use the original snapshot along with each of the stored \"_operations_\" messages to reconstruct the tree for each of the profiled commits.\n+\n+When profiling begins, the backend records the base durations of each fiber currently in the tree. While profiling is in progress, the backend also stores some information about each commit, including:\n+* Commit time and duration\n+* Which elements were rendered during that commit\n+* Which interactions (if any) were part of the commit\n+* Which props and state changed (if enabled in profiler settings)\n+\n+This information will eventually be required by the frontend in order to render its profiling graphs, but it will not be sent across the bridge until profiling has completed (to minimize the performance impact of profiling).\n+\n+### Combining profiling data\n+\n+Once profiling is finished, the frontend requests profiling data from the backend one renderer at a time by sending a \"_getProfilingData_\" message. The backend responds with a \"_profilingData_\" message that contains per-root commit timing and duration information. The frontend then combines this information with its own snapshots to form a complete picture of the profiling session. Using this data, charts and graphs are lazily computed (and incrementally cached) on demand, based on which commits and views are selected in the Profiler UI.\n+\n+### Importing\/exporting data\n+\n+Because all of the data is merged in the frontend after a profiling session is completed, it can be exported and imported (as a single JSON object), enabling profiling sessions to be shared between users.\n\\ No newline at end of file\n","commit":{"shortRevision":"600c57a9b9","authorName":"Brian Vaughn","authorEmail":"bvaughn@fb.com","authoredAt":"2019-08-15T11:22:11-07:00","subject":"Added OVERVIEW.md and updated CHANGELOG to point to it (#16405)","revision":"600c57a9b9f36c8de1d3544bdbadd3babba1bcc7"},"parents":["9b5985b3c11929f8fc3bf5092d6c94838c7fe3dc"]}}}}}

dillon1000/react

Files changed