react-os-shell

A desktop-style React UI shell — windows, taskbar, start menu, sticky notes, frosted-glass theming — plus 16 bundled apps (utilities, games, Google integrations).

Status: v0.1.0 — extracted from a production ERP where it's been running for a small team. Public API is stabilising; expect minor shape changes before 1.0.

→ Live demo

A backend-less playground hosted on GitHub Pages. Wallpapers, themes, sticky notes, the spreadsheet, the calendar, all wired to localStorage so the page survives a refresh. Source is in examples/demo/.

_{The screenshot is auto-captured against the deployed demo by .github/workflows/screenshot.yml. Run it manually: gh workflow run "Capture hero screenshot" (or use the Actions tab).}

What's in the box

Shell: <Layout>, <StartMenu>, <Desktop> (with sticky notes + folders), <WindowManager>, <Modal> (standard / compact / widget styles), <PopupMenu>, <ConfirmDialog>, <GlobalSearch> (Cmd-K), <ShortcutHelp>, <NotificationBell>, <BugReportDetail>, <StatusBadge>, frosted-glass theming, <GoogleConnectModal>.

Apps (16 ship in the package):

• Utilities (7): Calculator, Notepad, Spreadsheet, Weather, CurrencyConverter, PomodoroTimer, WorldClock
• Games (6): Chess, Checkers, Minesweeper, Sudoku, Tetris, 2048
• Google (3): Calendar, Email (Gmail), GeminiChat

15 of the 16 ship in the bundledApps registry today; the remaining one (WorldClock) is exported individually but needs consumer-supplied prefs wiring before slotting into bundledApps. The bundled Customization settings page is also exported separately for consumers to register at /settings/customization.

Hooks: useWindowManager, useTheme, full hotkey/nav system (useNewHotkey, useEditHotkey, useModalNav, useModalSave, useModalDuplicate, useTableNav, useMultiModal), useGoogleAuth, useEmailUnread.

Themes: light + dark (frosted-glass tinting; the package ships base styles, additional theme variants like pink/green/grey/blue can layer on top).

Install

npm i react-os-shell

Peer deps you should already have in a typical React + Tailwind v4 app:

npm i react react-dom react-router-dom @tanstack/react-query react-hook-form \
      tailwindcss @headlessui/react @heroicons/react

Quick start (~50 lines)

// App.tsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import {
  Layout,
  WindowManagerProvider,
  ConfirmProvider,
  ShellAuthProvider,
  ShellPrefsProvider,
  ShellEntityFetcherProvider,
  StatusBadgeProvider,
  setShellApiClient,
  setShellAuthBridge,
  setShellWindowRegistry,
  createWindowRegistry,
  useLocalStoragePrefs,
} from 'react-os-shell';
import { bundledApps } from 'react-os-shell/apps';
import 'react-os-shell/styles.css';
import axios from 'axios';

const apiClient = axios.create({ baseURL: '/api' });
setShellApiClient(apiClient);
setShellWindowRegistry(createWindowRegistry(bundledApps));
setShellAuthBridge({ user: { first_name: 'Demo' }, logout: () => {} });

const navSections = [
  { to: '/', label: 'Home' },
  { label: 'Games', items: bundledApps['/chess'] ? [
    { to: '/chess', label: 'Chess' },
    { to: '/tetris', label: 'Tetris' },
    { to: '/2048', label: '2048' },
  ] : [] },
];

const queryClient = new QueryClient();

export default function App() {
  const prefs = useLocalStoragePrefs('my-app');
  return (
    <QueryClientProvider client={queryClient}>
      <ConfirmProvider>
        <BrowserRouter>
          <ShellAuthProvider value={{ hasAnyPerm: () => true }}>
            <ShellPrefsProvider value={prefs}>
              <ShellEntityFetcherProvider value={(endpoint, id) => apiClient.get(`${endpoint}${id}/`).then(r => r.data)}>
                <StatusBadgeProvider groups={{}}>
                  <WindowManagerProvider>
                    <Routes>
                      <Route path="*" element={<Layout navSections={navSections} navIcons={{}} />} />
                    </Routes>
                  </WindowManagerProvider>
                </StatusBadgeProvider>
              </ShellEntityFetcherProvider>
            </ShellPrefsProvider>
          </ShellAuthProvider>
        </BrowserRouter>
      </ConfirmProvider>
    </QueryClientProvider>
  );
}

That gives you the full desktop with all 12 utility/game/Google apps reachable through the start menu's Games / Utilities trays. Add your own entity windows by extending the registry, and wire the notification / bug-report / sticky-note systems through optional config callbacks when you want them.

Concepts

Window registry

Every window the shell can open lives in a WindowRegistry map. Two entry shapes:

• Page — { component: LazyExoticComponent, label, size?, widget?, … }. Opened via openPage(routeKey).
• Entity — { endpoint, render(entity, …), title(entity), footer?, … }. Opened via openEntity(typeKey, id). The shell GETs ${endpoint}${id}/ (via the consumer-supplied entity fetcher) and hands the result to render.

Compose multiple partial maps with createWindowRegistry(...maps):

import { bundledApps } from 'react-os-shell/apps';
import { erpEntities } from './shell-config/erpEntities';

const windows = createWindowRegistry(bundledApps, erpEntities);
setShellWindowRegistry(windows);

Nav sections

Layout renders the start menu from a (NavSection | NavItem)[] you pass in:

const navSections = [
  { to: '/', label: 'Home' },
  { label: 'Clients', items: [
    { to: '/orders', label: 'Sales Orders', perms: ['view_order'] },
    { to: '/clients', label: 'Clients' },
  ]},
];

Items with perms are filtered through <ShellAuthProvider value={{ hasAnyPerm }}>.

useWindowManager

The hook every component uses to open / close / minimise windows:

const { openPage, openEntity, closeEntity, openWindows } = useWindowManager();

openPage('/calculator');
openEntity('order', 'uuid-123');

API reference

All exports are named — import { Modal, ... } from 'react-os-shell'.

Components

Export	Purpose
Layout	Top-level shell — desktop + taskbar + start menu. Mount once inside your providers.
StartMenu / Desktop / WindowManagerProvider	Used internally by Layout; rarely instantiated directly.
Modal, ModalActions, CopyButton, CancelButton	Window primitive supporting standard / compact / widget styles.
PopupMenu, PopupMenuItem, PopupMenuDivider, PopupMenuLabel	Right-click / context-menu primitive.
ConfirmProvider, confirm	Imperative confirm({ title, body }) returning a Promise.
GlobalSearch	Cmd-K command palette. Pass providers: SearchProvider[] to add results.
ShortcutHelp	The keyboard cheatsheet shown on ?.
NotificationBell	Taskbar bell — config via <Layout notifications={…}>.
BugReportDetail	Used inside an entity-window registry entry; reads from <BugReportConfigProvider>.
StatusBadge	Coloured pill rendering a status string. Map status→semantic group via <StatusBadgeProvider groups={{...}}>.
GoogleConnectModal	UI for entering Google OAuth client ID.

Providers + setters

Export	Use
<ShellAuthProvider value={{ hasAnyPerm }}>	Permission-filter nav items.
<ShellPrefsProvider value={{ prefs, save }}>	Where the shell reads/writes user prefs (theme, taskbar pos, sticky notes, …). Use useLocalStoragePrefs(key) for a backend-less default.
<ShellEntityFetcherProvider value={(endpoint, id) => …}>	How the modal stack fetches entity data.
<BugReportConfigProvider value={{ submit, list?, resolve? }}>	Wire the bug-report flow to your backend.
<DesktopHostProvider value={{ stickyResolver?, saveShortcuts?, … }}>	Sticky-note ref resolver + persistence callbacks.
<StatusBadgeProvider groups={{ status: 'success' | ... }}>	Status string → semantic group.
setShellApiClient(axios)	Module-level: register your axios instance once.
setShellAuthBridge({ user, logout })	Module-level: register user identity / logout handler.
setShellWindowRegistry(registry)	Module-level: register your composed WindowRegistry.

Hooks

Export	Purpose
useWindowManager()	{ openPage, openEntity, closeEntity, openWindows, … }
useTheme()	{ theme, resolved } — current theme + system-resolved value.
useNewHotkey(handler)	Cmd/Ctrl+N — for "create new entity" buttons.
useEditHotkey(handler)	Alt+Shift+E — for "edit" toggle.
useModalNav({ onPrev, onNext })	←/→ to step through siblings inside a modal.
useModalSave(handler)	Cmd-S inside a modal.
useModalDuplicate(handler)	Alt-D inside a modal.
useTableNav({ rows, cols, onCell })	Arrow-key cell navigation in editable grids.
useMultiModal()	Manages multi-window stacking + activate/blur.
useGoogleAuth({ clientId? })	Google Identity Services wrapper — token + scopes.
useEmailUnread()	Live unread-count for the Gmail badge.
useShellAuth() / useShellPrefs() / useShellEntityFetcher() / useBugReport() / useDesktopHost()	Context readers — the shell uses these internally; consumers may also call them.

Apps barrel — react-os-shell/apps

Export	Type
bundledApps	WindowRegistry — 12 ready-to-mount apps.
utilityApps, gameApps, googleApps	Subsets of bundledApps.
Calculator, Spreadsheet, Weather, CurrencyConverter, PomodoroTimer, Chess, Checkers, Sudoku, Tetris, Game2048, Email, GeminiChat	Lazy components — use directly in custom registry entries.

Misc

Export	Notes
createWindowRegistry(...maps)	Variadic merge — later partials override earlier on the same key.
isPageEntry, isEntityEntry	Type guards for WindowRegistryEntry.
glassStyle()	Returns the theme-aware frosted-glass style object.
reportBug(submit)	Captures a screenshot via getDisplayMedia, opens the dialog, hands the payload to your submit.
formatDate(iso)	Locale-aware date formatter.
toast.success / .error / .info	Toast notifications — auto-mounts container.
Kbd constants — MOD, ALT, SHIFT, ENTER, ALT_SHIFT_E, CMD_K, …	Symbol constants for rendering keyboard shortcuts.

Why it exists

Most "desktop UI" demos on the web are toys with hardcoded windows and no escape hatch. This one was extracted from a working ERP where every entity (sales orders, invoices, vendors, …) opens as its own window with consistent header, footer, hotkeys, depth stacking, and split-view. The shell is fully decoupled from any specific backend — every subsystem that needs server data (notifications, bug reports, desktop shortcuts, search, entity fetching) takes its data through callback configs supplied by the consumer. Drop-in localStorage fallbacks ship for prefs and sticky notes so the package works out of the box without a backend.

Examples

• examples/demo — small Vite app showcasing the shell + bundled apps with mock data. Live at victorymau.github.io/react-os-shell, deployed automatically by .github/workflows/pages.yml on every push to main.

Contributing

PRs welcome. Open an issue first for non-trivial changes so we can align on shape.

License

MIT