A VS Code–style web shell: activity bar, plugins, TanStack Router file routes, workspace explorer, stacked sidebar panels (Explorer + Agent), tabs, breadcrumbs and activity dialogs.
Live demo: https://ppongtong.github.io/ide-shell/
Stack: React 19.3 · React Compiler 1.0 · TanStack Router (file-based) · Zustand 5 · Vite 8 · TypeScript 6.0 · ESLint 10
npm install
npm run dev # http://localhost:5173
npm test # Node built-in unit tests (registry + search-params)
npm run lint # TypeScript, React hooks/Compiler rules, folder import rules
npm run build # tsc + eslint + vite build
npm run build:demo # one self-contained HTML file in dist-demo/ (hash URLs)
TypeScript is pinned to 6.0 because typescript-eslint does not support TypeScript 7 yet.
src/
app/ startup wiring + the IDE frame
main.tsx render <AppProvider><RouterProvider/></AppProvider>
router.ts createRouter({ routeTree })
plugins.ts the one list of features to load
app-registry.tsx createRegistry(plugins) + <AppProvider>
shell/ Shell, ActivityBar, Breadcrumbs, DialogHost, PluginPageHost
routes/ thin TanStack file routes → feature pages
__root.tsx component: Shell
index.tsx redirect → /workspaces
workspaces/route.tsx layout + workspace list loader, crumb "Workspaces"
workspaces/index.tsx list
workspaces/$wsId.tsx ?item & ?panels, loader, Breadcrumbs → details
settings.tsx
$activityId/$.tsx catch-all for plugin pages (/reports, /reports/q1)
routeTree.gen.ts generated by the router plugin — do not edit
features/ one folder = one plugin
workspace/ Workspaces + New workspace buttons, Explorer, item types, tabs, editors
agent/ Agent button + Agent panel
reports/ example plugin page with its own sub-views
settings/ Settings button + page
lib/plugin-system/ the IDE plugin SDK: types, registry, ShellLocation, search-params
stores/ app-wide state & cross-feature bridges (shell-store, workspace-bridge, persist)
components/ui/ reusable UI: ActivityBarButton, Breadcrumb, Modal, ResizableStack
styles/
| Folder | May import | Must not import |
|---|---|---|
app/ |
anything | — |
app/shell/ |
lib, stores, components | features, routes |
routes/ |
a feature's index.ts, app/shell, lib |
— |
features/* |
lib, stores, components, its own folder (relative) | app, routes, other features |
stores/ |
lib | app, routes, features, components |
lib/ |
— | everything above it |
components/ |
— | app, routes, features, stores, lib |
Features talk to each other only through lib/plugin-system (the IDE plugin SDK) and shared stores in stores/. Examples:
- Sidebar panels receive
{ workspace }fromSidebarPanels. WorkspaceDetailPagesyncs what is open, plus actions (openItem,closeItem), intostores/workspace-bridge.tsviauseSyncWorkspaceBridge.AgentPanelreads it withuseWorkspaceBridge((s) => s.current)for rendering anduseWorkspaceBridge.getState()before and afterawait, so it acts on where the user is now without importing the workspace feature.
| Feature | Where | Why |
|---|---|---|
<Activity> (19.2) |
features/workspace/components/EditorHost.tsx |
Open tabs stay mounted while hidden (keyed per workspace + tab): edits survive tab switches |
<Activity> (19.2) |
components/ui/ResizableStack.tsx |
Hidden sidebar panels keep their state (agent chat) |
<ViewTransition> (19.3) |
features/agent/components/AgentPanel.tsx |
New messages animate in |
useEffectEvent (19.2) |
app/shell/Shell.tsx, WorkspaceDetailPage.tsx |
Effects read latest values without extra dependencies |
Actions: useActionState, useFormStatus, <form action> |
NewWorkspaceDialog.tsx |
Declarative form validation and pending state |
useTransition + useOptimistic |
AgentPanel.tsx |
Messages appear immediately while clearing the chat input right away |
use(Context) |
lib/plugin-system/registry.ts |
Read context cleanly |
<Context value> |
app/app-registry.tsx |
No .Provider |
| ref as a prop, ref cleanup functions | components/ui/Modal.tsx, ResizableStack.tsx |
No forwardRef; attaches/cleans up DOM nodes directly |
<title> in components |
pages | Tab title follows the page |
| React Compiler 1.0 | vite.config.ts |
Automatic memoization: no useMemo/useCallback/memo |
Gotcha: give effects a block body: useEffect(() => { doThing(); }, []). An arrow that returns something (useEffect(() => doThing())) can hand React a value that isn't a cleanup function and crash the tree.
Note on <ViewTransition>: it only animates updates React runs as Transitions. Router and Zustand updates are synchronous, so route changes and tab switches don't animate through it.
| To add | Do |
|---|---|
| Explorer item type | itemTypes: [{ type, label, icon, editor: lazy(...) }] in a feature's plugin.ts |
| Sidebar panel + toggle | a panels entry + an activity { kind: 'togglePanel', panelId } |
| Full-page activity | an activity { kind: 'route', to: '/<id>', page: lazy(...) } — no route file needed |
| Button that opens a dialog | an activity { kind: 'dialog', dialog: lazy(...) } — gets a close prop |
| Core screen with typed URLs | a file in src/routes/ + an activity whose to points at it |
Then add the plugin to src/app/plugins.ts. Data in features/*/api/ is mock data.