Features

Microfrontend

Host your application in the Shellui iframe. Load the SDK, initialize it, and communicate with the shell through the postMessage API.

Run your application in Shellui

Your app does not replace the shell. It runs inside an iframe that Shellui hosts. The shell owns navigation, layout, and chrome. Your application owns its own UI, in any stack you choose.

To connect the two, load @shellui/sdk in the iframe and call init. After that handshake, every message between the app and the shell goes through the postMessage API. The SDK wraps that channel so you do not talk to window.parent by hand.

1. Load the SDK

Include @shellui/sdk in the app that will run inside the iframe.

2. Call init

Initialize the SDK so the shell and your application can handshake and agree on the channel.

3. Use postMessage

All further communication travels over postMessage — layout, theme, navigation, and the rest of the shell API.

app.ts
import { shellui } from "@shellui/sdk";

await shellui.init();

shellui.addMessageListener("SHELLUI_SETTINGS_UPDATED", (data) => {
  const { settings } = data.payload;
  applyTheme(settings.appearance?.colorScheme);
});

shellui.sendMessageToParent({
  type: "CUSTOM_MESSAGE",
  payload: { ready: true },
});

Layouts

The shell can present the same iframe in three layout modes. Pick one in config; every microfrontend inherits it.

Sidebar

Colored sidebar navigation with the application canvas beside it. The default app chrome.

Top bar

The sidebar hides and navigation moves to a top bar, giving the iframe more horizontal space.

Window

The app opens as a desktop window with a title bar and taskbar, alongside other windows.

Basic UI features

The shell already owns toasts, dialogs, modals, drawers, theme, and language. From the iframe you call them on shellui after init — no extra overlay stack in your app.

toast.ts
import { shellui } from "@shellui/sdk";

await shellui.init();

shellui.toast({
  title: "Success!",
  description: "Operation completed.",
  type: "success",
});
dialog.ts
import { shellui } from "@shellui/sdk";

await shellui.init();

shellui.dialog({
  title: "Confirm delete",
  description: "Are you sure you want to delete this item?",
  mode: "okCancel",
  onOk: () => deleteItem(),
  onCancel: () => {},
});
modal.ts
import { shellui } from "@shellui/sdk";

await shellui.init();

shellui.openModal("/compose");
drawer.ts
import { shellui } from "@shellui/sdk";

await shellui.init();

shellui.openDrawer({
  url: "/filters",
  position: "right",
  size: "400px",
});
theme.ts
import { shellui } from "@shellui/sdk";

await shellui.init();

shellui.addMessageListener("SHELLUI_SETTINGS_UPDATED", (data) => {
  const { appearance } = data.payload.settings;
  applyTheme(appearance?.colorScheme);
});
locale.ts
import { shellui } from "@shellui/sdk";

await shellui.init();

shellui.addMessageListener("SHELLUI_SETTINGS_UPDATED", (data) => {
  const { language } = data.payload.settings;
  applyLanguage(language?.code);
});

Next, see how Authentication handles sign-in, protected routes, and identity integration.