Analog

@virtual-frame/analog provides first-class Analog.js 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/analog @virtual-frame/angular @virtual-frame/store

Server Route (Server Rendering)

Create an Analog API route (Nitro server handler) to fetch the remote page during SSR. The route runs on the server, keeping node-html-parser out of the client bundle.

// src/server/routes/api/frame.ts
import { fetchVirtualFrame, prepareVirtualFrameProps } from "@virtual-frame/analog/server";
import { defineEventHandler } from "h3";

const REMOTE_URL = process.env["REMOTE_URL"] ?? "http://localhost:3011";

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

// src/app/pages/index.page.ts
import { Component, inject, TransferState, makeStateKey } from "@angular/core";
import { HttpClient } from "@angular/common/http";
import { toSignal } from "@angular/core/rxjs-interop";
import { VirtualFrameComponent } from "@virtual-frame/analog";

const FRAME_KEY =
  makeStateKey<
    Awaited<ReturnType<typeof import("@virtual-frame/analog/server").prepareVirtualFrameProps>>
  >("vf-frame");

@Component({
  selector: "app-home",
  standalone: true,
  imports: [VirtualFrameComponent],
  template: `
    @if (frame(); as f) {
      <virtual-frame [src]="f.src" [isolate]="f.isolate" [vfHtml]="f._vfHtml"></virtual-frame>
    }
  `,
})
export default class HomeComponent {
  private http = inject(HttpClient);
  private state = inject(TransferState);

  frame = toSignal(
    this.http.get("/api/frame").pipe(
      // Cache SSR-fetched props via TransferState so the client
      // does not re-fetch after hydration.
      (src) => src,
    ),
  );
}

Selector Projection

Project only a specific part of the remote page:

// src/server/routes/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 <virtual-frame> instances share a single hidden iframe:

// src/server/routes/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",
    }),
  };
});

// src/app/pages/index.page.ts — template
template: `
  @if (data(); as d) {
    <virtual-frame [src]="d.fullFrame.src"
                   [isolate]="d.fullFrame.isolate"
                   [vfHtml]="d.fullFrame._vfHtml"></virtual-frame>
    <virtual-frame [src]="d.counterFrame.src"
                   [isolate]="d.counterFrame.isolate"
                   [selector]="d.counterFrame.selector"
                   [vfHtml]="d.counterFrame._vfHtml"></virtual-frame>
  }
`;

See the Shared Store section below for host + remote bridge wiring.

Remote Side

The remote is a normal Analog.js app. Import the bridge script from main.ts — it auto-initialises when loaded inside an iframe and is a no-op when loaded standalone:

// src/main.ts
import "zone.js";
import "@angular/compiler";
import { bootstrapApplication } from "@angular/platform-browser";
import { AppComponent } from "./app/app.component";
import { appConfig } from "./app/app.config";

// Virtual Frame bridge — auto-initialises inside an iframe.
import "virtual-frame/bridge";

bootstrapApplication(AppComponent, appConfig).catch(console.error);

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 injectStoreValue(...) subscriptions re-render via Angular signals when the underlying value changes.

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

1. Create the store on the host

// src/app/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 <virtual-frame> on the host

// src/app/pages/index.page.ts
import { Component, signal } from "@angular/core";
import { VirtualFrameComponent, injectStoreValue } from "@virtual-frame/analog";
import { store } from "../store";

@Component({
  selector: "app-home",
  standalone: true,
  imports: [VirtualFrameComponent],
  template: `
    <p>Host count: {{ count() ?? 0 }}</p>
    <button (click)="inc()">Increment from host</button>
    <button (click)="reset()">Reset</button>

    <!-- Any <virtual-frame> that receives [store] joins the same sync bridge. -->
    <virtual-frame
      [src]="frame().src"
      [isolate]="frame().isolate"
      [vfHtml]="frame()._vfHtml"
      [store]="store"
    ></virtual-frame>
  `,
})
export default class HomeComponent {
  store = store;
  count = injectStoreValue<number>(store, ["count"]);
  inc() {
    store["count"] = (this.count() ?? 0) + 1;
  }
  reset() {
    store["count"] = 0;
  }
  frame = signal({ src: "", isolate: "open" as const, _vfHtml: "" });
}

• 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 <virtual-frame> 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 injectStore from @virtual-frame/analog/store (singleton that connects to the incoming MessagePort) together with injectStoreValue for reactive subscriptions:

import { Component } from "@angular/core";
import { injectStore, injectStoreValue } from "@virtual-frame/analog/store";

@Component({
  selector: "app-counter",
  standalone: true,
  template: `<button (click)="inc()">Count: {{ count() ?? 0 }}</button>`,
})
export class CounterComponent {
  store = injectStore();
  count = injectStoreValue<number>(this.store, ["count"]);
  inc() {
    this.store["count"] = (this.count() ?? 0) + 1;
  }
}

Call	Returns	Purpose
injectStore()	StoreProxy	Remote singleton. Connects to the host store over MessagePort on first call.
injectStoreValue(store, ["count"])	Signal<T>	Reactive subscription. Re-renders dependents via Angular signals.

Standalone fallback

When the remote page is loaded directly in the browser (not through a virtual frame), there is no host and no port. In that case injectStore() returns a plain in-memory store, so the page still works as a standalone Analog.js 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 dev-proxy on the host.

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

1. Add a dev proxy to the host's Vite config

// vite.config.ts (host)
import { defineConfig } from "vite";
import analog from "@analogjs/platform";

const REMOTE_URL = process.env["REMOTE_URL"] ?? "http://localhost:3011";

export default defineConfig({
  plugins: [analog()],
  server: {
    proxy: {
      "/__vf": {
        target: REMOTE_URL,
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/__vf/, ""),
      },
    },
  },
});

2. Pass the proxy option

// src/server/routes/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

<virtual-frame>

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

Input	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
vfHtml	string	—	SSR HTML from prepareVirtualFrameProps()

injectStore()

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

injectStoreValue(store, path?)

Subscribes to a store path and returns an Angular Signal.

import { injectStore, injectStoreValue } from "@virtual-frame/analog/store";

const store = injectStore();
const count = injectStoreValue<number>(store, ["count"]);

fetchVirtualFrame(url, options?)

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

prepareVirtualFrameProps(frame, options?)

Server-only. Converts a server render result into serialisable props for <virtual-frame>. 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

• Analog example — pnpm example:analog