bippy

Understanding these terms is essential for using bippy:

• fiber: A "unit of execution" in React, representing a component or DOM element.
• commit: The process of applying changes to the host tree (e.g., DOM mutations).
• render: The process of building the fiber tree by executing component functions or classes.
• host tree: The tree of UI elements that React mutates (e.g., DOM elements).
• reconciler (or "renderer"): Custom bindings for React (e.g., react-dom, react-native, react-three-fiber) used to mutate the host tree.
• rendererID: The ID of the reconciler, starting at 1.
• root: A special FiberRoot type containing the container fiber in its current property.

A React Fiber is a unit of execution representing either a component (function/class) or a host element (DOM node). Fibers contain the application's state, props, and context.

While React's internal Fiber structure is complex and changes between versions, bippy provides stable utility functions to interact with them:

• Traversal: Use traverseRenderedFibers to detect which fibers actually rendered, or traverseFiber to walk the entire tree (bypassing the need to manually follow child, sibling, and return pointers).
• Data Access: Use traverseProps, traverseState, and traverseContexts to access data (bypassing the need to manually access memoizedProps, memoizedState, and dependencies).
• Identity: Use setFiberId and getFiberId to assign and retrieve unique identities for fibers.

In Next.js 15.3+, use the instrumentation-client.js file to ensure bippy loads before React hydration. Create this file at the root of your application (or inside the src folder if using a src directory structure).

// instrumentation-client.ts
import "bippy";

If you are building a library and want to minimize bundle size, you can avoid importing the full bippy package (~4 KB gzipped). Instead, use bippy/install-hook-only to install the hook without the utility functions, then import only the specific utilities you need from bippy/core.

import "bippy/install-hook-only"; // only installs the hook
import { getRDTHook, traverseFiber } from "bippy/core"; // import only what you need
import * as React from "react"; // import react AFTER the hook is installed

const hook = getRDTHook();
// define your own utilities or use only specific ones

Install bippy via npm. Critical Requirement: You must import bippy before any React code is executed in your application. Bippy works by hijacking the window.__REACT_DEVTOOLS_GLOBAL_HOOK__ property, which React uses to report its internals. If imported too late, React will not attach its internals to the hook, and bippy will not function.

npm install bippy

In Vite, import bippy at the very top of your main entry point (e.g., src/main.tsx or src/main.ts) before any React imports.

// src/main.tsx
import "bippy";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";

// ... rest of your code

To instrument your application with bippy, you must ensure the __REACT_DEVTOOLS_GLOBAL_HOOK__ is loaded before React is executed. Use safelyInstallRDTHook() to initialize the hook in client environments. This function is typically used as a side effect at the very top of your entry point.

CRITICAL: This must be imported and called before any other imports that might trigger React execution (e.g., importing components or your main App file).

The instrument function accepts an options object with the following lifecycle hooks:

• onCommitFiberRoot(rendererID, root): Called when React is ready to commit a fiber root (i.e., it has rendered the app and is ready to apply changes to the host tree like DOM mutations).
• onPostCommitFiberRoot(rendererID, root): Called after React has committed a fiber root and effects have run.
• onCommitFiberUnmount(rendererID, fiber): Called when a specific fiber unmounts.

Parameters:

• rendererID: The ID of the reconciler (e.g., react-dom), starting at 1. Multiple reconcilers may exist.
• root: A FiberRoot object containing the container fiber in its current property.
• fiber: The specific fiber being unmounted.

Use the instrument function to install the React DevTools global hook. This allows you to intercept React fiber lifecycle events by providing custom handlers.

Important: instrument must be imported BEFORE react in your application entry point to ensure the hook is successfully installed.

Use these utilities to query properties and identity of React fibers:

• isValidFiber(fiber): Checks if an object is a valid React Fiber.
• getDisplayName(fiber): Returns the component's display name.
• getType(fiber): Returns the underlying component definition (e.g., the function or class).
• isHostFiber(fiber): Returns true if the fiber is a host fiber (e.g., a DOM node).
• isCompositeFiber(fiber): Returns true if the fiber is a composite fiber (e.g., a component).
• getFiberId(fiber) / setFiberId(fiber): Manages a persistent identity for fibers (which are anonymous by default).
• getFiberStack(fiber): Returns an array representing the stack of fibers from the current fiber up to the root [fiber, fiber.return, ...].