Skip to content
Vue Remote logo Vue Remote logo Vue Remote

Getting Started

What this guide covers

Section titled “What this guide covers”

This guide helps you bootstrap the render sync layer between:

  • a host product that owns allowed UI components;
  • an independent remote extension runtime.

@omnicajs/vue-remote handles synchronized rendering. Business APIs, auth, discovery, and marketplace logic stay in adjacent tooling.

Install

Section titled “Install”
Terminal window
yarn add @omnicajs/vue-remote @remote-ui/rpc

IDE tooling

Section titled “IDE tooling”

To get remote-native template refs typed as remote element proxies in remote SFCs, add the Vue tooling plugin:

{
  "vueCompilerOptions": {
    "plugins": [
      "@omnicajs/vue-remote/tooling"
    ]
  }
}

What to expect:

  • <div ref="panel" /> inside *.remote.vue or an SFC marked with <script setup remote> is inferred as a remote proxy from @omnicajs/vue-remote/remote, not as HTMLDivElement.
  • useTemplateRef(...), ref(null), and shallowRef(null) follow the same remote boundary model for native refs.
  • Host component refs keep their component-instance typing.

IDE recommendations:

  • VS Code: use the Vue - Official extension.
  • PhpStorm / WebStorm: use Vue Language Server (Volar) and enable the service-powered type engine for the most accurate type evaluation.
  • Other IDEs: if they are backed by @vue/language-server or another Volar-compatible Vue language client, they should also honor vueCompilerOptions.plugins.

If you are developing inside this repository instead of consuming the published package, use ./tooling.cjs in vueCompilerOptions.plugins.

1. Bootstrap host runtime

Section titled “1. Bootstrap host runtime”

On the host side:

  1. Register host components with createProvider(...).
  2. Create render channel receiver with createReceiver().
  3. Render HostedTree and pass provider + receiver.
  4. Start remote runtime (iframe/worker) and pass receiver.receive into run(...).

See: Host Components and Overview.

2. Bootstrap remote runtime

Section titled “2. Bootstrap remote runtime”

On the remote side:

  1. Create remote root with createRemoteRoot(channel, options).
  2. Create app with createRemoteRenderer(root).createApp(...).
  3. Define host-exposed components via defineRemoteComponent(...).
  4. Mount root and app during run(...), cleanup in release().

See: Remote Components and Overview.

3. Connect host and remote

Section titled “3. Connect host and remote”

Use a channel transport (commonly @remote-ui/rpc) and keep a stable handshake:

  1. Host loads remote runtime URL.
  2. Remote exposes run/release.
  3. Host calls run(channel, hostBridge).
  4. Remote mounts UI through the channel.
  5. Session ends with release().

If you prefer dedicated worker runtime over iframe transport, see Web Worker Runtime. For iframe-specific setup, see Iframe Integration. For explicit channel handshakes across custom containers, see MessagePort Transport. For Electron/Tauri process-separated runtimes, see Desktop IPC Transport. For cross-process or cross-machine sessions, see Socket Transport. For local harnesses and tests, you can also run host + remote in one runtime via In-Memory Transport (dev/test only). For a side-by-side selection guide, see Transport Comparison.

4. Validate boundaries

Section titled “4. Validate boundaries”

Before extending further, verify:

  • host controls the exposed component allowlist;
  • props/events crossing runtimes are serializable;
  • remote runtime does not depend on direct browser DOM APIs.

Next

Section titled “Next”