Vue Integration

@iteraai/vue-component-inspector is the Vue 3 SDK for browser DOM apps embedded in the hosted Itera editor.

Use this package for Vite-style Vue apps first. Nuxt guidance uses the same runtime package and bootstrap helpers; there is no separate Nuxt-specific SDK target in v1.

Supported runtime

• Vue 3 browser DOM apps only
• Vite-style entrypoints first
• Nuxt client-side integrations built on the same package

Out of scope:

• Vue 2
• SSR-only entrypoints
• Non-DOM renderers

Install

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

Preferred embedded bootstrap

For apps where you own createApp(...), bootstrap the inspector before or immediately around app.mount(...):

import { createApp } from 'vue';
import { bootstrapEmbeddedInspectorBridgeOnMount } from '@iteraai/vue-component-inspector';
import { bootIterationInspectorRuntime } from '@iteraai/vue-component-inspector/iterationInspector';
import App from './vue-app';

const app = createApp(App);
const bridge = bootstrapEmbeddedInspectorBridgeOnMount(app, {
  enabled: import.meta.env.DEV,
  hostOrigins: import.meta.env.VITE_ITERA_COMPONENT_INSPECTOR_HOST_ORIGINS,
});

bootIterationInspectorRuntime();

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

app.mount('#app');

If the host does not use iteration selection, you can omit bootIterationInspectorRuntime().

Why explicit app registration is preferred

The Vue bridge can discover mounted apps from DOM containers, but that path is intentionally fallback behavior.

Prefer explicit registration because it:

• makes mounted-app tracking deterministic before the iframe becomes interactive
• works even when the app mounts into custom containers or other non-default DOM layouts
• avoids depending on DOM-only discovery when you want strict startup behavior
• stays aligned with the example consumer and public package bootstrap helpers

bootstrapEmbeddedInspectorBridgeOnMount(...) is the easiest way to get explicit registration. If you need lower-level bridge control, use registerVueAppOnMount(...) or registerMountedVueApp(...) yourself.

Lower-level explicit registration

Use the low-level bridge only when you need custom lifecycle or adapter control:

import { createApp } from 'vue';
import {
  initInspectorBridge,
  registerVueAppOnMount,
} from '@iteraai/vue-component-inspector';
import App from './vue-app';

const app = createApp(App);
const registration = registerVueAppOnMount(app);
const bridge = initInspectorBridge({
  enabled: true,
  hostOrigins: ['https://app.iteradev.ai', 'https://preview.iteradev.ai'],
  runtimeConfig: {
    mountedAppDiscovery: {
      strategy: 'explicit-only',
    },
  },
});

app.mount('#app');

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

Use strategy: 'explicit-only' when you want the bridge to fail closed instead of silently falling back to DOM discovery.

When discovery fallback is acceptable

The default Vue runtime config uses mountedAppDiscovery.strategy: 'auto', which prefers explicit registrations and then falls back to DOM discovery.

Fallback discovery is acceptable when all of these are true:

• the app is a normal Vue 3 DOM app mounted with app.mount(...)
• the mounted container remains connected to the document
• the default Vue mount marker ([data-v-app]) is still present
• you do not need strict, deterministic mounted-app registration during bootstrap

Avoid discovery fallback when:

• you own the app bootstrap and can register explicitly
• the app mounts into a ShadowRoot or other custom container setup
• the app lifecycle detaches and reattaches containers
• you want explicit-only behavior in production or during incident debugging

Nuxt guidance

Nuxt uses the same @iteraai/vue-component-inspector package. Put the bridge in a client-only plugin so it runs in the browser before Nuxt mounts the Vue app:

import { bootstrapEmbeddedInspectorBridgeOnMount } from '@iteraai/vue-component-inspector';
import { bootIterationInspectorRuntime } from '@iteraai/vue-component-inspector/iterationInspector';

export default defineNuxtPlugin((nuxtApp) => {
  const bridge = bootstrapEmbeddedInspectorBridgeOnMount(nuxtApp.vueApp, {
    enabled: true,
    hostOrigins: ['https://app.iteradev.ai', 'https://preview.iteradev.ai'],
  });

  bootIterationInspectorRuntime();

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

Use a file name such as plugins/itera-inspector.client.ts so the bridge only starts in the browser. Do not boot the inspector from server plugins or SSR-only code paths.

Source metadata

Vue tree snapshots can surface best-effort source metadata without extra build tooling when component types expose fields such as __file, file, fileName, or __source.

That baseline is intentionally limited:

• file metadata may be present while line and column are missing
• if only a file is known, the runtime reports line: 1
• runtime-only metadata is not guaranteed to match React-style source parity

If you want consistent file plus line plus column metadata in Vite-based builds, add the optional Vue source-metadata plugin described in Vite-Style Apps.