Skip to content
ppongtongPublic

About

VS code style web shell

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

IDE shell

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.

Folders

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/

Import rules (enforced by npm run lint)

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 } from SidebarPanels.
  • WorkspaceDetailPage syncs what is open, plus actions (openItem, closeItem), into stores/workspace-bridge.ts via useSyncWorkspaceBridge. AgentPanel reads it with useWorkspaceBridge((s) => s.current) for rendering and useWorkspaceBridge.getState() before and after await, so it acts on where the user is now without importing the workspace feature.

React 19.x features used

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.

Add things

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.

About

VS code style web shell

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages