Nuxt

@virtual-frame/nuxt provides first-class Nuxt integration with server rendering. The remote page is fetched during SSR inside a Nitro server route and embedded in the response — the user sees styled content on first paint with zero layout shift, and the client resumes live updates without an extra network request.

Installation

npm install virtual-frame @virtual-frame/nuxt @virtual-frame/vue @virtual-frame/store

Server Route (Server Rendering)

Create a Nitro server route to fetch the remote page during SSR. The route runs on the server, keeping node-html-parser out of the client bundle.

// server/api/frame.ts
import { fetchVirtualFrame, prepareVirtualFrameProps } from "@virtual-frame/nuxt/server";

const REMOTE_URL = process.env.REMOTE_URL ?? "http://localhost:3009";

export default defineEventHandler(async () => {
  const frame = await fetchVirtualFrame(REMOTE_URL);
  return await prepareVirtualFrameProps(frame);
});

<!-- pages/index.vue -->
<script setup>
import { VirtualFrame } from "@virtual-frame/nuxt";

const { data } = await useFetch("/api/frame");
</script>

<template>
  <VirtualFrame v-if="data" v-bind="data" />
</template>

Selector Projection

Project only a specific part of the remote page:

// server/api/frame.ts
export default defineEventHandler(async () => {
  const frame = await fetchVirtualFrame(REMOTE_URL);
  return await prepareVirtualFrameProps(frame, {
    selector: "#counter-card",
  });
});

Multiple Projections from One Fetch

Fetch once, display multiple sections — both VirtualFrame instances share a single hidden iframe:

// server/api/frame.ts
export default defineEventHandler(async () => {
  const frame = await fetchVirtualFrame(REMOTE_URL);
  return {
    fullFrame: await prepareVirtualFrameProps(frame),
    counterFrame: await prepareVirtualFrameProps(frame, {
      selector: "#counter-card",
    }),
  };
});

<!-- pages/index.vue -->
<script setup>
import { VirtualFrame } from "@virtual-frame/nuxt";

const { data } = await useFetch("/api/frame");
</script>

<template>
  <div v-if="data">
    <VirtualFrame v-bind="data.fullFrame" />
    <VirtualFrame v-bind="data.counterFrame" />
  </div>
</template>

Remote Side

The remote is a normal Nuxt app. Add the bridge script as a client plugin — it auto-initialises when loaded inside an iframe and is a no-op when loaded standalone:

// plugins/bridge.client.ts
import "virtual-frame/bridge";

export default defineNuxtPlugin(() => {});

See the Shared Store section below for how to read and write the bridged store from the remote.

Shared Store

A shared store keeps state in sync between the host app and the remote app (including every projected frame) over a MessagePort bridge. Writes on either side propagate to the other automatically, and every useStore(...) subscription re-renders when the underlying value changes.

The store lives in the host — the remote connects to it at runtime via the hidden iframe VirtualFrame mounts. You do not duplicate the store on the remote: the remote-side useStore() returns a proxy that forwards reads and writes across the port.

1. Create the store on the host

// composables/store.ts
import { createStore } from "@virtual-frame/store";

export const store = createStore();
store.count = 0;

createStore() returns a plain reactive object. Assign initial values directly — nested objects and arrays are supported. Paths are addressed as string arrays: ["count"], ["user", "name"], ["items", 0].

2. Pass the store to <VirtualFrame> on the host

<!-- pages/index.vue -->
<script setup>
import { VirtualFrame } from "@virtual-frame/nuxt";
import { useStore } from "@virtual-frame/vue";
import { store } from "~/composables/store";

const { data } = await useFetch("/api/frame");
// Subscribe to a path — returns a reactive Vue `Ref`.
const count = useStore < number > (store, ["count"]);
</script>

<template>
  <div v-if="data">
    <p>Host count: {{ count ?? 0 }}</p>
    <button @click="store.count = (count ?? 0) + 1">Increment from host</button>
    <button @click="store.count = 0">Reset</button>

    <!-- Any VirtualFrame that receives :store joins the same sync bridge. -->
    <VirtualFrame v-bind="data.fullFrame" :store="store" />
    <VirtualFrame v-bind="data.counterFrame" :store="store" />
  </div>
</template>

• Host reads/writes are direct: store.count operates on the host's in-memory object — no serialisation, no round-trip.
• Passing :store wires up the bridge: when the hidden iframe loads and the remote signals vf-store:ready, the component opens a MessageChannel, transfers one port to the iframe, and calls connectPort() on the host side. Multiple <VirtualFrame> instances sharing the same src share one iframe and one port — the store is bridged exactly once.

3. Consume the store on the remote

On the remote, use useStore from @virtual-frame/nuxt/store (singleton that connects to the incoming MessagePort) together with useStore from @virtual-frame/vue (reactive subscription):

<script setup>
import { useStore as useRemoteStore } from "@virtual-frame/nuxt/store";
import { useStore } from "@virtual-frame/vue";

const store = useRemoteStore();
const count = useStore < number > (store, ["count"]);
</script>

<template>
  <button @click="store.count = (count ?? 0) + 1">Count: {{ count ?? 0 }}</button>
</template>

Two imports, two different functions, both named useStore:

Import	Purpose
useStore from @virtual-frame/nuxt/store	Remote singleton. Returns the StoreProxy for the remote app. Sets up the MessagePort bridge on first call.
useStore from @virtual-frame/vue	Reactive subscription. Takes a StoreProxy + path and returns a Vue Ref<T>.

Standalone fallback

When the remote page is loaded directly in the browser (not through a VirtualFrame), there is no host and no port. In that case useRemoteStore() returns a plain in-memory store, so the page still works as a standalone Nuxt app. Writes stay local; reads return whatever was last written.

Tips

• Initialise on the host, not the remote. The host's values are the source of truth on first connect. Anything the remote writes before the port is open is kept local until the bridge finishes handshaking.
• Keep values serialisable. Values cross a postMessage boundary — prefer plain objects, arrays, primitives. No class instances, functions, or DOM nodes.
• Namespace per feature. For multiple features in one app, group keys under stable prefixes (["cart", "items"], ["auth", "user"]).
• One store per remote URL is typical. Pass the same store to every frame that targets the same remote.

How Server Rendering Works

Client-Side Navigation (Proxy)

When the remote app performs client-side navigation, it needs to fetch data from the remote server. The proxy option ensures these requests reach the correct server by routing them through a server middleware on the host.

Without proxy, client-side navigation in the remote app will fail with network errors. This is required whenever the host and remote run on different origins.

1. Add a proxy to the host's Nuxt config

// nuxt.config.ts (host)
const REMOTE_URL = process.env.REMOTE_URL ?? "http://localhost:3009";

export default defineNuxtConfig({
  nitro: {
    devProxy: {
      "/__vf": {
        target: REMOTE_URL,
        changeOrigin: true,
        prependPath: true,
      },
    },
  },
});

2. Pass the proxy option

// server/api/frame.ts
export default defineEventHandler(async () => {
  const frame = await fetchVirtualFrame(REMOTE_URL);
  return await prepareVirtualFrameProps(frame, { proxy: "/__vf" });
});

TIP

The proxy prefix (/__vf) is a convention — you can use any path that doesn't conflict with your host app's routes. For multiple remotes, use a different prefix for each.

API Reference

<VirtualFrame>

Client component that displays server-fetched content and resumes live mirroring.

Prop	Type	Default	Description
src	string	—	Remote URL to fetch and project
selector	string	—	CSS selector for partial projection
isolate	"open" | "closed"	"open"	Shadow DOM mode
streamingFps	number | Record<string, number>	—	Canvas/video streaming FPS
store	StoreProxy	—	Shared store for cross-frame state sync
proxy	string	—	Same-origin proxy prefix for client-side navigation

useStore(store, selector?)

Subscribes to a store path and returns a reactive Vue Ref.

import { useStore } from "@virtual-frame/vue";

const count = useStore<number>(store, ["count"]); // reactive ref
const snapshot = useStore(store); // all changes

useRemoteStore()

Remote-side composable. Returns the shared store singleton and sets up the MessagePort bridge. Import from @virtual-frame/nuxt/store.

import { useStore as useRemoteStore } from "@virtual-frame/nuxt/store";

const store = useRemoteStore();

fetchVirtualFrame(url, options?)

Server-only. Fetches a remote page and produces a server render result. Import from @virtual-frame/nuxt/server.

prepareVirtualFrameProps(frame, options?)

Server-only. Converts a server render result into serialisable props for <VirtualFrame>. Returns a Promise — always await it.

Option	Type	Default	Description
selector	string	—	CSS selector for partial projection
isolate	"open" | "closed"	"open"	Shadow DOM mode
proxy	string	—	Same-origin proxy prefix for client-side navigation

Examples

• Nuxt example — pnpm example:nuxt