Quick Start

Get a working io.Connect Browser application running in under 10 minutes. This guide walks you through creating a Platform (host) app and a Client (child) app that share data via Shared Contexts.

Prerequisites

  • Node.js 18+ and npm
  • React 18+ with TypeScript
  • An io.Connect license key (for Browser Platform)
No license yet?Contact interop.io to request a trial license key.

Step 1: Create the Platform App

The Platform app acts as the hub in the hub-and-spoke architecture. It initializes the io.Connect environment and manages routing between client apps.

Terminal
npm create vite@latest platform-app -- --template react-ts
cd platform-app
npm install @interopio/browser-platform @interopio/react-hooks

Configure the Provider

Wrap your root component with IOConnectProvider using the browserPlatform factory:

src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import IOBrowserPlatform from "@interopio/browser-platform";
import { IOConnectProvider } from "@interopio/react-hooks";
import type { IOConnectInitSettings } from "@interopio/react-hooks";
import App from "./App";

const settings: IOConnectInitSettings = {
  browserPlatform: {
    factory: IOBrowserPlatform,
    config: {
      licenseKey: import.meta.env.VITE_IOCONNECT_LICENSE_KEY,
    },
  },
};

ReactDOM.createRoot(document.getElementById("root")!).render(
  <IOConnectProvider settings={settings} fallback={<div>Loading...</div>}>
    <App />
  </IOConnectProvider>
);
No React.StrictModeRemove <React.StrictMode> to prevent double-initialization of the io.Connect Platform.

Create an .env file

.env
VITE_IOCONNECT_LICENSE_KEY=your-license-key-here

Step 2: Create a Client App

Client apps connect to the Platform hub. They use the browser factory instead of browserPlatform.

Terminal
npm create vite@latest client-app -- --template react-ts
cd client-app
npm install @interopio/browser @interopio/react-hooks
src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import IOBrowser from "@interopio/browser";
import { IOConnectProvider } from "@interopio/react-hooks";
import type { IOConnectInitSettings } from "@interopio/react-hooks";
import App from "./App";

const settings: IOConnectInitSettings = {
  browser: {
    factory: IOBrowser,
  },
};

ReactDOM.createRoot(document.getElementById("root")!).render(
  <IOConnectProvider settings={settings} fallback={<div>Connecting...</div>}>
    <App />
  </IOConnectProvider>
);

Step 3: Share Data via Contexts

Now let's make the apps communicate. The Platform app will publish a selected client, and the Client app will subscribe to it.

Publisher (Platform App)

src/App.tsx
import { useContext } from "react";
import { IOConnectContext } from "@interopio/react-hooks";

function App() {
  const io = useContext(IOConnectContext);

  const selectClient = async (clientId: string) => {
    await io?.contexts.update("SelectedClient", {
      type: "fdc3.contact",
      id: { email: clientId },
      name: "Jane Smith",
    });
  };

  return (
    <div>
      <h1>Platform App</h1>
      <button onClick={() => selectClient("jane@example.com")}>
        Select Jane Smith
      </button>
    </div>
  );
}

export default App;

Subscriber (Client App)

src/App.tsx
import { useContext, useState } from "react";
import { IOConnectContext, useIOConnect } from "@interopio/react-hooks";

interface ClientData {
  type: string;
  id: { email: string };
  name: string;
}

function App() {
  const io = useContext(IOConnectContext);
  const [client, setClient] = useState<ClientData | null>(null);

  useIOConnect(async (io) => {
    const unsub = await io.contexts.subscribe(
      "SelectedClient",
      (data: ClientData) => setClient(data)
    );
    return () => unsub();
  }, []);

  return (
    <div>
      <h1>Client App</h1>
      {client ? (
        <div>
          <p>Name: {client.name}</p>
          <p>Email: {client.id.email}</p>
        </div>
      ) : (
        <p>Waiting for client selection...</p>
      )}
    </div>
  );
}

export default App;

Step 4: Run Both Apps

Terminal
# Terminal 1 — Platform (must start first)
cd platform-app && npm run dev -- --port 3000

# Terminal 2 — Client
cd client-app && npm run dev -- --port 3001
The Client app must be loaded as an iframe within the Platform, or both must be on the same origin for the io.Connect Browser messaging to work. See the Architecture Overview for details.

What's Next?

← PreviousIntroduction