fixdog-sdk

Option+Click any React component to instantly see its source location.

GIF demo placeholder goes here

Quick start (3 steps)

1. npm install fixdog-sdk
2. In your app entry, import and init:

   import { init } from "fixdog-sdk";
   init();

3. Option/Alt + click a component in the browser to log its source.

Installation

• Next.js / Vite / CRA: npm install fixdog-sdk (or yarn add, pnpm add)
• Works in React 16.8+ through React 19. No runtime deps.

Usage

import { init, Inspector } from "fixdog-sdk";

// simple
init();

// with options
init({
  borderColor: "#ff6b6b",
  onClick: (info) => console.log("clicked", info),
});

// manual control
const inspector = new Inspector({ enabled: true });
inspector.activate();
inspector.deactivate();
inspector.destroy();

React provider (optional)

import { InspectorProvider } from "fixdog-sdk/react";

export function App() {
  return (
    <InspectorProvider options={{}}>
      <YourApp />
    </InspectorProvider>
  );
}

Options

| option | type | default | description | | ----------------- | ----------------------------- | -------------- | ---------------------------------------- | | onClick | (info) => void | undefined | Called on click with source info | | onHover | (info \| null) => void | undefined | Called when hover target changes | | shortcut | string | ctrl+shift+x | Toggle persistent inspect mode | | useOptionClick | boolean | true | Enable Option/Alt + click activation | | enabled | boolean | !production | Auto-disabled in prod unless forced true | | zIndex | number | 999999 | Overlay/tooltip stacking | | borderColor | string | #61dafb | Highlight + tooltip border color | | tooltipPosition | 'auto' \| 'top' \| 'bottom' | auto | Tooltip placement preference |

API

• init(options?) → Inspector singleton (auto-activates)
• new Inspector(options?) → manual instance
  • .activate() enable listeners and overlay
  • .deactivate() remove listeners and hide overlay
  • .destroy() cleanup overlay
• InspectorProvider React wrapper (optional)

SourceInfo

interface SourceInfo {
  componentName: string;
  fileName: string;
  lineNumber: number;
  columnNumber: number;
  fiber?: any; // raw React fiber
  element?: Element; // DOM element
}

How it works

• Grabs the nearest React fiber on Option/Alt click (or persistent mode).
• Walks up the fiber tree to _debugSource for fileName:line:column.
• Shows an overlay + tooltip; logs formatted message and passes full info to callbacks.

Troubleshooting

• Source not available: Ensure dev/build has _debugSource (development or React Refresh). Production builds often strip it.
• Next.js / RSC: Server Components don’t have client-side fibers; ensure the inspected component is a client component.
• Plain HTML element: No React fiber → nothing to log.
• Iframes / shadow DOM: Inspector stays within the current document; shadow hosts are walked, but cross-iframe is skipped.

Testing locally

1. npm install
2. npm link
3. Create a test app (e.g., npm create vite@latest test-app -- --template react-ts)
4. In that app: npm link fixdog-sdk
5. Import and run init() in main.tsx, then Option/Alt+click in the browser.

Build

• npm run build (Rollup → ESM + CJS + types)
• npm run dev (watch)

Contributing

PRs welcome. Please keep the bundle lean and TypeScript strict.

License

MIT © fixdog