Next.js

For Next.js 15.3 and newer, bootstrap the inspector in instrumentation-client.ts. Next.js runs that file after the HTML document loads and before React hydration begins, which is the preferred timing for the inline backend hook.

If your app does not support instrumentation-client.ts yet, keep the same timing rule and use the earliest client entrypoint you have.

File location

Create instrumentation-client.ts at the project root or under src/.

Example

This is a concrete app-level pattern: start the iteration runtime first, then initialize the dev bridge only when development is enabled and trusted origins are present.

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

const splitHostOrigins = (value: string | undefined) => {
  return (value ?? '')
    .split(',')
    .map((origin) => origin.trim())
    .filter((origin) => origin.length > 0);
};

const inspectorEnabled =
  process.env.NODE_ENV === 'development' &&
  process.env.NEXT_PUBLIC_ITERA_COMPONENT_INSPECTOR_ENABLED === 'true';

if (inspectorEnabled) {
  const hostOrigins = splitHostOrigins(
    process.env.NEXT_PUBLIC_ITERA_COMPONENT_INSPECTOR_HOST_ORIGINS,
  );

  bootIterationInspectorRuntime();

  if (hostOrigins.length > 0) {
    initDevEmbeddedInspectorBridge({
      enabled: true,
      hostOrigins,
    });
  } else {
    console.warn(
      '[itera/component-inspector] Inspector enabled without trusted host origins. Skipping bootstrap.',
    );
  }
}

Example app env convention

The public package does not read environment variables on its own. If you want an environment-driven Next.js setup, these are example app-level env names you can use:

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

• NEXT_PUBLIC_ITERA_COMPONENT_INSPECTOR_ENABLED turns the embedded bridge on during development.
• NEXT_PUBLIC_ITERA_COMPONENT_INSPECTOR_HOST_ORIGINS supplies a comma-separated list of exact trusted Itera editor origins.
• NEXT_PUBLIC_ITERA_COMPONENT_INSPECTOR_KILL_SWITCH can drive killSwitchActive if you choose to wire it in your app code.
• NEXT_PUBLIC_ITERA_DEV_DIAGNOSTICS can gate optional app-level logging if you add your own diagnostics hooks.

Notes

• initDevEmbeddedInspectorBridge() is a thin development shortcut. It still uses the preferred fiber path by default.
• Keep the bootstrap in instrumentation-client.ts when that file convention is available. Starting later from a client component or useEffect can still work, but it is more likely to miss early fiber data.
• If you need secure session-token validation or custom adapter wiring, drop down to initInspectorBridge() from the same early startup file.