Bippy: React Internals Hacking Toolkit

Common errors

• TypeError: Cannot read properties of undefined (reading 'current')

  cause Bippy's internal hooks were not successfully established because the `instrument` function was called after React had already initialized.
  fix Move `import { instrument } from 'bippy'; instrument({...});` to the very top of your application's main entry file, ensuring it executes before any React-related imports or rendering calls.

• Error: Could not find __REACT_DEVTOOLS_GLOBAL_HOOK__ on window.

  cause Bippy failed to find the expected React DevTools global hook object on `window` before React initialized, or another library clobbered it.
  fix Verify that Bippy is the absolute first script to run. If other development tools or libraries that also interact with React internals are present, they might be conflicting. Try isolating Bippy's usage or investigating load order.

Warnings

• breaking Bippy relies heavily on undocumented and unstable React internal APIs (e.g., Fiber tree structure, global hooks). These internals can change without warning in any React version, potentially breaking your application or causing unexpected behavior, including runtime errors or memory leaks.
  Fix: This package is explicitly for advanced debugging, tooling, or experimental use cases, and is NOT recommended for production environments. Be prepared for frequent maintenance and breakage with new React versions. Thorough testing with each React update is essential.
• gotcha Bippy's `instrument` function MUST be called BEFORE React is imported or initialized (e.g., `ReactDOM.createRoot().render()`) in your application. Failure to do so will result in Bippy being unable to hook into React's internals, leading to silent failures or errors.
  Fix: Ensure that `import { instrument } from 'bippy'; instrument({...});` is the absolute first executable code in your application's main entry file (e.g., `src/index.ts` or `src/main.js`), preceding any other imports, especially those related to React.
• gotcha The exact structure of React's Fiber nodes (`memoizedProps`, `memoizedState`, `dependencies`, `type`, etc.) can vary subtly between major React versions (v17, v18, v19). While Bippy provides some abstractions, direct Fiber inspection may require version-specific handling.
  Fix: When performing deep Fiber introspection, consult Bippy's documentation and potentially React's official source code for the specific version you are targeting. Test your tooling across all target React versions.

Install

• npm install bippy npm
• yarn add bippy yarn
• pnpm add bippy pnpm

Imports

• instrument
  wrong:

  const { instrument } = require('bippy')

  correct:

  import { instrument } from 'bippy'

  The `instrument` function is the primary entry point and MUST be called BEFORE React is loaded in your application to properly set up the global hook.
• onCommitFiberRoot
  wrong:

  import onCommitFiberRoot from 'bippy'

  correct:

  import { onCommitFiberRoot } from 'bippy'

  A named export function used as a callback within the `instrument` configuration, triggered when React commits a Fiber root.
• traverseFiber
  wrong:

  const { traverseFiber } = require('bippy')

  correct:

  import { traverseFiber } from 'bippy'

  A utility function to recursively traverse the React Fiber tree starting from a given Fiber node, simplifying access to child, sibling, and return pointers.

Quickstart

Demonstrates how to initialize Bippy's instrumentation BEFORE React loads, hooking into the `onCommitFiberRoot` event to traverse and log details about every Fiber in the React tree upon each commit cycle.

import { instrument, onCommitFiberRoot, traverseFiber } from 'bippy'; // Must be imported BEFORE React

// This block MUST execute before any React import or ReactDOM.createRoot call.
// For a typical SPA, place this at the very top of your main entry file (e.g., index.ts/js).

instrument({
  onCommitFiberRoot: (root) => {
    console.log('React commit detected for root:', root.current); // root.current is the actual Fiber root
    traverseFiber(root.current, (fiber) => {
      // This callback runs for every fiber in the current React tree upon commit.
      // 'fiber' contains properties like type, memoizedProps, memoizedState, etc.
      if (fiber.elementType && typeof fiber.elementType === 'function') {
        // Log component names (functional or class components)
        console.log(`Component Fiber: ${fiber.elementType.displayName || fiber.elementType.name || 'AnonymousComponent'}`);
      } else if (fiber.stateNode instanceof HTMLElement) {
        // Log host (DOM) element tags
        console.log(`Host Fiber (DOM): <${fiber.stateNode.tagName.toLowerCase()} />`);
      } else if (fiber.type) {
        // Log other types of fibers (e.g., HostText, Suspense, Provider)
        console.log(`Other Fiber Type: ${typeof fiber.type === 'symbol' ? fiber.type.toString() : fiber.type}`);
      }
    });
  },
  // Additional hooks can be configured here, e.g., onMount, onUnmount
  // onMount: (fiber) => console.log('Fiber Mounted:', fiber),
  // onUnmount: (fiber) => console.log('Fiber Unmounted:', fiber),
});

console.log('Bippy instrumentation activated successfully. Your React app will now be monitored.');

// Your React application's entry point would typically follow here,
// e.g., import ReactDOM from 'react-dom/client'; ReactDOM.createRoot(...).render(...);