React Integration

For embedded React apps outside Storybook, the current customer-facing integration uses the embedded bridge plus the iteration runtime. Bootstrap both during client startup, not from inside the mounted React tree.

If your React app is rendered through Storybook and Itera should load the Storybook manager URL, use Storybook Integration and the @iteraai/react-component-inspector/storybook entrypoint. The standard root bootstrap helpers remain the right path for non-Storybook apps and for direct iframe.html fallback debugging.

Install

npm install @iteraai/react-component-inspector @iteraai/inspector-protocol

Your app should already provide compatible react and react-dom versions to satisfy the inspector package peer dependencies.

Preferred startup path

import { bootstrapEmbeddedInspectorBridge } from '@iteraai/react-component-inspector';
import { bootIterationInspectorRuntime } from '@iteraai/react-component-inspector/iterationInspector';

const bridge = bootstrapEmbeddedInspectorBridge({
  enabled: true,
  hostOrigins: [
    'https://app.iteradev.ai',
    'https://preview.iteradev.ai',
  ],
});

bootIterationInspectorRuntime();

window.addEventListener('beforeunload', () => {
  bridge.destroy();
});

Use your own environment flags around enabled, but keep the call site early in startup.

If your app is deployed inside Itera-managed infrastructure, you usually do not need to inject those inspector env values yourself. Itera infrastructure already supplies the documented values during deployment. Manual env wiring is mainly for local development and customer-managed deployments.

What this does

• bootstrapEmbeddedInspectorBridge() initializes the embedded bridge in development mode, enables the tree, props, and highlight capabilities, and defaults to runtimeConfig: { adapter: 'fiber' }.
• The bootstrap helper also installs the inline React DevTools backend hook unless you opt out with installInlineBackendHook: false.
• bootIterationInspectorRuntime() starts the separate element-selection runtime and posts runtime_ready when it is able to talk to the parent frame.

Trusted host origins

hostOrigins must contain the exact hosted-editor origins that are allowed to control the inspector. The helper accepts either an array or a comma-separated string and trims empty values.

If hostOrigins resolves to an empty list, or if you set enabled: false, killSwitchActive: true, or mode: 'production', the bridge stays disabled.

Messages from untrusted origins are ignored before protocol parsing, so a wrong origin usually looks like a silent bridge.

Initialize before React is interactive

For the best immediate fiber results, install the inline backend hook before React hydration or ReactDOM.createRoot(...) makes the app interactive. Avoid waiting for:

• a mounted component
• useEffect
• a route-level lazy import
• a user action that starts the runtime later

For Next.js, that usually means instrumentation-client.ts. For Vite-style or CRA-style apps, that means the browser entrypoint before ReactDOM.createRoot(...).

Late bootstrap can still work, but initial inspection is more likely to be incomplete or start on a fallback path until fiber data becomes available.

fiber vs framework-specific targets

Prefer the default fiber path. The runtime config supports the framework-specific adapter target strings next, vite, and cra for tag adapters and fiber fallback behavior, but they are not the first recommendation for a normal integration.

Only reach for initInspectorBridge() or a custom adapterFactory when you need lower-level control such as secure HELLO session-token validation, custom adapter wiring, or explicit telemetry hooks.