bippy 0.0.24 → 0.1.0

package/README.md

@@ -1,19 +1,34 @@
+> [!WARNING]
+> ⚠️⚠️⚠️ **this project may break production apps and cause unexpected behavior** ⚠️⚠️⚠️
+>
+> this project uses react internals, which can change at any time. it is not recommended to depend on internals unless you really, _really_ have to. by proceeding, you acknowledge the risk of breaking your own code or apps that use your code.
+
 # <img src="https://github.com/aidenybai/bippy/blob/main/.github/assets/bippy.png?raw=true" width="60" align="center" /> bippy
 
-a hacky way to get fibers from react. used internally for [`react-scan`](https://github.com/aidenybai/react-scan).
+[![size](https://img.shields.io/bundlephobia/minzip/bippy?label=gzip&style=flat&colorA=000000&colorB=000000)](https://bundlephobia.com/package/bippy)
+[![version](https://img.shields.io/npm/v/bippy?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/bippy)
+[![downloads](https://img.shields.io/npm/dt/bippy.svg?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/bippy)
 
-bippy works by monkey-patching `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` with [custom handlers](https://github.com/facebook/react/blob/6a4b46cd70d2672bc4be59dcb5b8dede22ed0cef/packages/react-refresh/src/ReactFreshRuntime.js#L427). this gives us access to react internals without needing to use react devtools.
+a hacky way to get fibers from react. <small>used internally by [`react-scan`](https://github.com/aidenybai/react-scan)</small>
 
-> [!WARNING]
-> this project uses react internals, which can change at any time. **this is not recommended for usage and may break production apps** - unless you acknowledge this risk and know exactly you're doing.
+bippy _attempts\*_ to solve two problems:
+
+1. it's not possible to write instrumentation for React without the end user changing code
+2. doing anything useful with fibers requires you to know react source code very well
+
+bippy allows you to access fiber information from outside of react and provides friendly low-level utils for interacting with fibers.
+
+<sub><sup>\*disclaimer: "attempt" used loosely, i highly recommend not relying on this in production</sub></sup>
 
-## tutorial: create a mini react-scan
+## how it works
 
-[`react-scan`](https://github.com/aidenybai/react-scan) is a tool that highlights renders in your react app. under the hood, it uses bippy to detect rendered fibers.
+bippy allows you to **access** and **use** fibers from outside of react.
 
-fibers are how "work" is represented in react. each fiber either represents a composite (function/class component) or a host (dom element). [here is a live visualization](https://jser.pro/ddir/rie?reactVersion=18.3.1&snippetKey=hq8jm2ylzb9u8eh468) of what the fiber tree looks like, and here is a [deep dive article](https://jser.dev/2023-07-18-how-react-rerenders/).
+a react fiber is a "unit of execution." this means react will do something based on the data in a fiber. each fiber either represents a composite (function/class component) or a host (dom element).
 
-a simplified version of a fiber looks roughly like this:
+> here is a [live visualization](https://jser.pro/ddir/rie?reactVersion=18.3.1&snippetKey=hq8jm2ylzb9u8eh468) of what the fiber tree looks like, and here is a [deep dive article](https://jser.dev/2023-07-18-how-react-rerenders/).
+
+fibers are useful because they contain information about the React app (component props, state, contexts, etc.). a simplified version of a fiber looks roughly like this:
 
 ```typescript
 interface Fiber {
@@ -23,6 +38,9 @@ interface Fiber {
   child: Fiber | null;
   sibling: Fiber | null;
 
+  // stateNode is the host fiber (e.g. DOM element)
+  stateNode: Node | null;
+
   // parent fiber
   return: Fiber | null;
 
@@ -34,12 +52,26 @@ interface Fiber {
 
   // contexts (useContext)
   dependencies: Dependencies | null;
+
+  // effects (useEffect, useLayoutEffect, etc.)
+  updateQueue: any;
 }
 ```
 
+here, the `child`, `sibling`, and `return` properties are pointers to other fibers in the tree.
+
+additionally, `memoizedProps`, `memoizedState`, and `dependencies` are the fiber's props, state, and contexts.
+
+while all of the information is there, it's not super easy to work with, and changes frequently across different versions of react. bippy simplifies this by providing utility functions like:
+
+- `createFiberVisitor` to detect renders and `traverseFiber` to traverse the overall fiber tree
+  - _(instead of `child`, `sibling`, and `return` pointers)_
+- `traverseProps`, `traverseState`, and `traverseContexts` to traverse the fiber's props, state, and contexts
+  - _(instead of `memoizedProps`, `memoizedState`, and `dependencies`)_
+
 however, fibers aren't directly accessible by the user. so, we have to hack our way around to accessing it.
 
-luckily, react [reads from a property](https://github.com/facebook/react/blob/6a4b46cd70d2672bc4be59dcb5b8dede22ed0cef/packages/react-reconciler/src/ReactFiberDevToolsHook.js#L48) in the window object: `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` and runs handlers on it when certain events happen. this is intended for react devtools, but we can use it to our advantage.
+luckily, react [reads from a property](https://github.com/facebook/react/blob/6a4b46cd70d2672bc4be59dcb5b8dede22ed0cef/packages/react-reconciler/src/ReactFiberDevToolsHook.js#L48) in the window object: `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` and runs handlers on it when certain events happen. this property must exist before react's bundle is executed. this is intended for react devtools, but we can use it to our advantage.
 
 here's what it roughly looks like:
 
@@ -48,119 +80,38 @@ interface __REACT_DEVTOOLS_GLOBAL_HOOK__ {
   // list of renderers (react-dom, react-native, etc.)
   renderers: Map<RendererID, ReactRenderer>;
 
-  // called when react has rendered everythign and ready to apply changes to the host tree (e.g. DOM mutations)
+  // called when react has rendered everything for an update and is ready to
+  // apply changes to the host tree (e.g. DOM mutations)
   onCommitFiberRoot: (
     rendererID: RendererID,
-    fiber: Record<string, unknown>,
-    commitPriority?: number,
-    didError?: boolean,
+    root: FiberRoot,
+    commitPriority?: number
   ) => void;
-}
-```
-
-we can use bippy's utils and the `onCommitFiberRoot` handler to detect renders!
-
-### 0. setup
-
-first, [create a new react project via stackblitz](https://stackblitz.com/fork/github/vitejs/vite/tree/main/packages/create-vite/template-react?file=src/App.jsx&terminal=dev)
-
-then, install bippy:
-
-```bash
-npm install bippy
-```
 
-finally, re-run the dev server:
-
-```bash
-npm run dev
-```
-
-### 1. use `onCommitFiberRoot` to get fibers
-
-let's use `instrument` to stub the `__REACT_DEVTOOLS_GLOBAL_HOOK__` object, and setup a custom handler for `onCommitFiberRoot`.
-
-```jsx
-import { instrument } from 'bippy'; // must be imported BEFORE react
-
-// rest of your code ...
-
-instrument({
-  onCommitFiberRoot(rendererID, root) {
-    const fiberRoot = root.current;
-    console.log('fiberRoot', fiberRoot);
-  },
-});
-```
-
-running this should log `fiberRoot` to the console. i recommend you playing with this code to get a feel for how fibers work.
-
-### 2. create a fiber visitor
-
-now, let's create a fiber visitor with `createFiberVisitor` to "visit" fibers that render. not every fiber actually renders, so we need to filter for the ones that do.
-
-```jsx
-import { instrument, createFiberVisitor } from 'bippy'; // must be imported BEFORE react
-
-// rest of your code ...
-
-const visit = createFiberVisitor({
-  onRender(fiber) {
-    console.log('fiber render', fiber);
-  },
-});
+  // called when effects run
+  onPostCommitFiberRoot: (rendererID: RendererID, root: FiberRoot) => void;
 
-instrument({
-  onCommitFiberRoot(rendererID, root) {
-    visit(rendererID, root);
-  },
-});
+  // called when a specific fiber unmounts
+  onCommitFiberUnmount: (rendererID: RendererID, Fiber: Fiber) => void;
+}
 ```
 
-### 3. determine DOM nodes to highlight
+bippy works by monkey-patching `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` with our own custom handlers. bippy simplifies this by providing utility functions like:
 
-next, we need to identify which DOM nodes we are going to highlight. we can do this by checking if the fiber is a host fiber, or if it's not, find the nearest host fiber.
+- `instrument` to safely patch `window.__REACT_DEVTOOLS_GLOBAL_HOOK__`
+  - _(instead of directly mutating `onCommitFiberRoot`, ...)_
+- `secure` to wrap your handlers in a try/catch and determine if handlers are safe to run
+  - _(instead of rawdogging `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` handlers, which may crash your app)_
 
-```jsx
-import {
-  instrument,
-  isHostFiber,
-  getNearestHostFiber,
-  createFiberVisitor,
-} from 'bippy'; // must be imported BEFORE react
+## examples
 
-// rest of your code ...
+the best way to understand bippy is to [read the source code](https://github.com/aidenybai/bippy/blob/main/src/core.ts). here are some examples of how you can use it:
 
-const highlightFiber = (fiber) => {
-  if (!(fiber instanceof HTMLElement)) return;
+### a mini react-scan
 
-  console.log('highlight dom node', fiber.stateNode);
-};
-
-const visit = createFiberVisitor({
-  onRender(fiber) {
-    if (isHostFiber(fiber)) {
-      highlightFiber(fiber);
-    } else {
-      // can be a component
-      const hostFiber = getNearestHostFiber(fiber);
-      highlightFiber(hostFiber);
-    }
-  },
-});
-
-instrument({
-  onCommitFiberRoot(rendererID, root) {
-    visit(rendererID, root);
-  },
-});
-```
+here's a mini toy version of [`react-scan`](https://github.com/aidenybai/react-scan) that highlights renders in your app.
 
-### 4. highlight DOM nodes
-
-now, let's implement the `highlightFiber` function to highlight the DOM node. the simplest way is to just overlay a div (with a red border) on top of the DOM node.
-
-```jsx
+```javascript
 import {
   instrument,
   isHostFiber,
@@ -168,11 +119,9 @@ import {
   createFiberVisitor,
 } from 'bippy'; // must be imported BEFORE react
 
-// rest of your code ...
-
 const highlightFiber = (fiber) => {
   if (!(fiber.stateNode instanceof HTMLElement)) return;
-
+  // fiber.stateNode is a DOM element
   const rect = fiber.stateNode.getBoundingClientRect();
   const highlight = document.createElement('div');
   highlight.style.border = '1px solid red';
@@ -188,33 +137,155 @@ const highlightFiber = (fiber) => {
   }, 100);
 };
 
+/**
+ * `createFiberVisitor` traverses the fiber tree and determines which
+ * fibers have actually rendered.
+ *
+ * A fiber tree contains many fibers that may have not rendered. this
+ * can be because it bailed out (e.g. `useMemo`) or because it wasn't
+ * actually rendered (if <Child> re-rendered, then <Parent> didn't
+ * actually render, but exists in the fiber tree).
+ */
 const visit = createFiberVisitor({
   onRender(fiber) {
-    if (isHostFiber(fiber)) {
-      highlightFiber(fiber);
-    } else {
-      // can be a component
-      const hostFiber = getNearestHostFiber(fiber);
-      highlightFiber(hostFiber);
-    }
+    /**
+     * `getNearestHostFiber` is a utility function that finds the
+     * nearest host fiber to a given fiber.
+     *
+     * a host fiber for `react-dom` is a fiber that has a DOM element
+     * as its `stateNode`.
+     */
+    const hostFiber = getNearestHostFiber(fiber);
+    highlightFiber(hostFiber);
   },
 });
 
-instrument({
-  onCommitFiberRoot(rendererID, root) {
-    visit(rendererID, root);
-  },
-});
+/**
+ * `instrument` is a function that installs the React DevTools global
+ * hook and allows you to set up custom handlers for React fiber events.
+ */
+instrument(
+  /**
+   * `secure` is a function that wraps your handlers in a try/catch
+   * and prevents it from crashing the app. it also prevents it from
+   * running on unsupported React versions and during production.
+   *
+   * this is not required but highly recommended to provide "safeguards"
+   * in case something breaks.
+   */
+  secure({
+    /**
+     * `onCommitFiberRoot` is a handler that is called when React is
+     * ready to commit a fiber root. this means that React is has
+     * rendered your entire app and is ready to apply changes to
+     * the host tree (e.g. via DOM mutations).
+     */
+    onCommitFiberRoot(rendererID, root) {
+      visit(rendererID, root);
+    },
+  })
+);
 ```
 
-### 5. profit
+### a mini why-did-you-render
+
+here's a mini toy version of [`why-did-you-render`](https://github.com/welldone-software/why-did-you-render) that logs why components re-render.
 
-try a completed version [here](https://bippy.million.dev)
+```typescript
+import {
+  instrument,
+  isHostFiber,
+  createFiberVisitor,
+  isCompositeFiber,
+  getDisplayName,
+  traverseProps,
+  traverseContexts,
+  traverseState,
+} from 'bippy'; // must be imported BEFORE react
 
-you can learn more about bippy by [reading the source code](https://github.com/aidenybai/bippy/blob/main/src/index.ts).
+const visit = createFiberVisitor({
+  onRender(fiber) {
+    /**
+     * `isCompositeFiber` is a utility function that checks if a fiber is a composite fiber.
+     * a composite fiber is a fiber that represents a function or class component.
+     */
+    if (!isCompositeFiber(fiber)) return;
+
+    /**
+     * `getDisplayName` is a utility function that gets the display name of a fiber.
+     */
+    const displayName = getDisplayName(fiber);
+    if (!displayName) return;
+
+    const changes = [];
+
+    /**
+     * `traverseProps` is a utility function that traverses the props of a fiber.
+     */
+    traverseProps(fiber, (propName, next, prev) => {
+      if (next !== prev) {
+        changes.push({
+          name: `prop ${propName}`,
+          prev,
+          next,
+        });
+      }
+    });
+
+    let contextId = 0;
+    /**
+     * `traverseContexts` is a utility function that traverses the contexts of a fiber.
+     * Contexts don't have a "name" like props, so we use an id to identify them.
+     */
+    traverseContexts(fiber, (next, prev) => {
+      if (next !== prev) {
+        changes.push({
+          name: `context ${contextId}`,
+          prev,
+          next,
+          contextId,
+        });
+      }
+      contextId++;
+    });
+
+    let stateId = 0;
+    /**
+     * `traverseState` is a utility function that traverses the state of a fiber.
+     *
+     * State don't have a "name" like props, so we use an id to identify them.
+     */
+    traverseState(fiber, (value, prevValue) => {
+      if (next !== prev) {
+        changes.push({
+          name: `state ${stateId}`,
+          prev,
+          next,
+        });
+      }
+      stateId++;
+    });
+
+    console.group(
+      `%c${displayName}`,
+      'background: hsla(0,0%,70%,.3); border-radius:3px; padding: 0 2px;'
+    );
+    for (const { name, prev, next } of changes) {
+      console.log(`${name}:`, prev, '!==', next);
+    }
+    console.groupEnd();
+  },
+});
 
-looking for a more robust version of our mini react-scan? try out [react-scan](https://github.com/aidenybai/react-scan).
+instrument(
+  secure({
+    onCommitFiberRoot(rendererID, root) {
+      visit(rendererID, root);
+    },
+  })
+);
+```
 
 ## misc
 
-the original bippy character is owned and created by [@dairyfreerice](https://www.instagram.com/dairyfreerice). this project is not related to the bippy brand, i just think the character is cute
+the original bippy character is owned and created by [@dairyfreerice](https://www.instagram.com/dairyfreerice). this project is not related to the bippy brand, i just think the character is cute.