Shared Contexts

Shared Contexts are named objects that act as a global state store shared between all applications in the io.Connect environment. They are the primary mechanism for cross-app data synchronization.

FDC3 MappingShared Contexts map to FDC3 App Channels. Use FDC3-compliant context types like fdc3.contact or fdc3.instrument for maximum interoperability.

Overview

The Shared Contexts API is accessible via the io.contexts object. Contexts persist even after the publishing app disconnects, ensuring subscriber apps always have the latest state.

Key characteristics:

Named — each context has a unique string name (e.g., "SelectedClient")
Persistent — data remains available after the publisher disconnects
Global — visible to all apps in the environment
Mergeable — update() merges properties; set() replaces entirely

Setting Contexts

Use set() to create a new shared context or completely replace an existing one:

io.contexts.set(name: string, data: object): Promise<void>

Set a context

const clientData = {
  type: "fdc3.contact",
  id: { email: "jane@example.com" },
  name: "Jane Smith",
};

// Creates the context, or replaces its value entirely
await io.contexts.set("SelectedClient", clientData);

set() overwrites the entire context object. Use update() if you only want to modify specific properties.

Updating Contexts

Use update() to merge new properties into an existing context. New properties are added, existing ones are updated. Set a property to null to remove it.

io.contexts.update(name: string, data: object): Promise<void>

Update specific properties

// Merge new data — existing properties are preserved
await io.contexts.update("SelectedClient", {
  portfolio: { totalValue: 1250000 },
});

// Remove a property by setting it to null
await io.contexts.update("SelectedClient", {
  portfolio: null,
});

Updating Specific Paths

For deeply nested updates, use setPath() to target a specific property path:

Set a specific path

await io.contexts.setPath(
  "SelectedClient",
  "portfolio.holdings[0].quantity",
  500
);

Getting Contexts

Retrieve the current value of a context at any time:

Get context value

const data = await io.contexts.get("SelectedClient");
console.log(data.name); // "Jane Smith"

Subscribing for Updates

Subscribe to receive real-time notifications whenever a context changes. The callback fires immediately with the current value, then on every subsequent update.

io.contexts.subscribe(name: string, callback: (data, delta, removed, unsubscribe, extraData) => void): Promise<() => void>

Subscribe to context updates

const unsubscribe = await io.contexts.subscribe(
  "SelectedClient",
  (data, delta, removed) => {
    console.log("Full context:", data);
    console.log("Changed properties:", delta);
    console.log("Removed keys:", removed);
  }
);

// Later: clean up
unsubscribe();

React Pattern

In React, use the useIOConnect hook or useEffect with cleanup:

React subscription pattern

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

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

function ClientDisplay() {
  const [client, setClient] = useState<ClientData | null>(null);

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

  if (!client) return <p>No client selected</p>;

  return (
    <div>
      <h2>{client.name}</h2>
      <p>{client.id.email}</p>
    </div>
  );
}

Listing All Contexts

List available contexts

// Returns an array of context names
const contextNames = io.contexts.all();
// ["SelectedClient", "AppSettings", "MarketData"]

Destroying Contexts

Destroy a context

await io.contexts.destroy("SelectedClient");

API Reference

Parameter	Type	Description
`name`required	`string`	The unique name of the shared context.
`data`required	`object`	The context data object. Supports any serializable structure.

Best Practices

Use FDC3-compliant context types (fdc3.contact, fdc3.instrument) for interoperability
Always return the unsubscribe function in useEffect cleanups
Prefer update() over set() for partial modifications to avoid overwriting other subscribers' data
Use descriptive context names like "SelectedClient" rather than generic names
Keep context objects reasonably small — don't store large datasets in contexts

← PreviousData Sharing Overview Next →Channels