Features

Your apps, one shared interface

Bring independently built web apps into the same navigation and layout. Shellui loads each app in an iframe, so you can keep its framework and deployment workflow. Use the software development kit (SDK) to connect your app to shared interface features.

Connect your app to the shell

Add @shellui/sdk to your embedded app and call shellui.init(). Your app can then open a dialog, show a notification, or navigate through the shell. The SDK handles communication between the iframe and its parent window. Your app must allow iframe embedding.

1. Load the SDK

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

2. Call init

Initialize the SDK to connect your app to the shell and receive its settings.

3. Call shared features

Use the SDK to show notifications, open dialogs, and navigate between apps.

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

await shellui.init();

shellui.toast({
  title: "Connected to Shellui",
  description: "This notification appears in the shell.",
  type: "success",
});

Choose a layout for your product

Set layout in shellui.config.json. Every embedded app inherits it. Default is sidebar.

Production layouts are sidebar, sidebar-inset, app-bar, app-bar-inset, and floating. Design the app to fill its iframe so it follows the layout you pick.

Sidebar

Persistent navigation beside the iframe. Config value: sidebar.

Sidebar inset

Same sidebar, with a chrome tray wrapping a rounded content frame. Config value: sidebar-inset.

App bar

Compact top navigation. Config value: app-bar.

App bar inset

Top bar with the same chrome tray around the app. Config value: app-bar-inset.

Floating

Glass chrome over full-bleed content. Desktop uses a floating sidebar; smaller viewports use a bottom tab bar. Config value: floating.

Windows

Taskbar and one window per nav item. Proof of concept; not for production. Config value: windows.

fullscreen hides navigation chrome. Size iframe UI to 100% of the iframe, not 100vh.

Show dialogs and notifications across the shell

Open toasts, dialogs, modals, and drawers from your app using @shellui/sdk. Shellui renders them outside the iframe, so they can use the full shell area. The examples below show the available calls.

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);
});

Theme, language, and floating actions

Let people choose their theme and language once in the shell settings. Your apps can read those preferences through the SDK and update their own interface. App-specific actions can appear above the content or as a floating button.

The JavaScript framework starters from shellui init include theme and language integration through @shellui/sdk/tiny. Use the full SDK when your app also needs dialogs, authentication, or storage.

Match the shell to your brand

Choose a built-in theme or define your own colors using the shadcn/ui CSS variable model. Store your theme in shellui.config.json or load theme files from themesDir.

Enable several themes to let people switch between them in Settings → Appearance. This example starts with the Shellui theme and makes two other palettes available.

shellui.config.json
{
  "theme": "shellui",
  "themes": ["shellui", "claude", "shadcn"],
  "activeTheme": "shellui"
}

Use the SDK to apply the selected colors in your app. The themes guide covers custom palettes and theme files.

Keep language settings consistent

Choose the languages available in Settings → Language. The built-in shell interface supports English and French. This configuration enables both.

Translate navigation labels and other configurable text with a LocalizedString object. Your apps listen for language changes through the SDK and supply their own translations. Shell layouts currently use left-to-right text direction.

shellui.config.json
{
  "language": ["en", "fr"]
}

Add actions for the current screen

Use shellui.actions.set to add a back button, title, or action buttons for the current screen. Shellui renders the controls and sends clicks to your app. The example below adds a back button and page title.

Update the actions when your app changes screens, or call shellui.actions.clear() to remove them. Switching to another app through the shell clears the previous app's actions automatically.

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

await shellui.init();

shellui.actions.set({
  back: { id: "back", onClick: () => history.back() },
  title: "Inbox",
});

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