ShellUI Documentation

Welcome to the ShellUI documentation.

ShellUI is a lightweight microfrontend shell: one host app, many embedded URLs, shared navigation, themes, and settings. When you need sign-in, you connect a backend (Supabase, the ShellUI identity service, or no backend for public shells) and configure authentication in shellui.config.ts—login routes, sessions, and guarded navigation are built into the shell.

Use the sections below as a map, or follow the recommended path in order.

Recommended path

1. Installation — Install the ShellUI CLI and verify your environment.
2. Quick Start — Create shellui.config.ts, run the dev server, and build for production.
3. Backend — Choose a provider (shellui, supabase, or none), set backend.url, and optional tenant or Supabase keys.
4. Authentication — Enable login methods, use /login and /login/callback, and protect routes with requiresAuth.
5. Navigation — Define sidebar items, groups, and auth-aware visibility (hideWhenLoggedOut).
6. SDK — Read user and settings from embedded apps; call shellui.login() for iframe-safe OAuth.

From there, pick layout, themes, i18n, and advanced features as your product needs them.

Core features

Navigation and layout

• Navigation — Icons, groups, localization, opening modes, and route protection
• Layouts — Sidebar, fullscreen, Windows desktop (experimental), or app bar
• Modals and drawers — Overlays and side panels for nav targets

Customization

• Themes — Light and dark modes, fonts, and colors
• Internationalization — Localized navigation and UI

User interface

• Toast notifications — Toasts with actions and styles
• Alert dialogs — Confirm and alert patterns

Advanced

• Application settings — Per-app settings panels in Settings
• Cookie consent — Cookie registry and consent storage
• Legal documents — Privacy, terms, and notices from markdown (including on the login page)
• Service worker — Offline support and update prompts
• SDK integration — Programmatic shell APIs for embedded apps

Reference

• CLI — Commands, config file shape, and backend fields
• Core package — React runtime and exports such as useAuth
• SDK — JavaScript SDK API
• Tauri — Desktop packaging

Developer resources

• Development guide — Contributing to ShellUI
• Publishing guide — Releasing packages