Build and Rendering Pipeline

Explain why the **OS Shell** uses Rsbuild/Rspack, how that differs from other apps in the monorepo, and how React 18 development behavior should influence shell

Purpose

Explain why the OS Shell uses Rsbuild/Rspack, how that differs from other apps in the monorepo, and how React 18 development behavior should influence shell code. For deployable app inventory, see monorepo-workspace-guide.md.

Current Status

Surface	Build tool	Config
OS Shell	Rsbuild (Rspack)	`apps/os-shell/rsbuild.config.ts`
Founder site	Vite	`apps/esmadrider-me`
Docs site	Next.js (Fumadocs)	`apps/docs/next.config.mjs`
UI workshop	Storybook	`apps/ui-workshop`
API worker	Wrangler + bundler	`apps/api-worker/wrangler.jsonc`
`packages/*`	Consumed as TS source	package `tsconfig` only

Not implemented: Module Federation, qiankun, or runtime-loaded remote micro-frontends in production. Treat those as future direction only.

Why Rsbuild for the Shell

Context: The shell is a large, stateful SPA with many lazy boundaries (apps, iframes), long dev sessions, and strict bundle governance.

Decision: Use Rsbuild on Rspack for apps/os-shell.

Practical benefits for this repo:

Dev feedback — fast rebuild loop for shell chrome and window layer work.
Production bundling — code splitting and asset pipeline suitable for Cloudflare Pages deploy (pnpm build:os, deploy:os).
Tooling alignment — webpack/Rspack ecosystem fits future advanced splitting if needed.
Monorepo consumption — workspace packages resolve through the shell bundler without each package needing its own app build.

What we are not claiming: Rsbuild is mandatory for every Próx app. Standalone or iframe apps may use Vite or another bundler when they deploy outside the shell bundle.

Shell vs App Build Freedom

Layer	Build owner	Notes
Shell chrome, window host, registry	`apps/os-shell` Rsbuild	Single deploy artifact
`packages/os-apps`	Compiled into shell via imports	No separate production URL for package apps today
`local-module` shell apps	Same shell bundle	e.g. keyboard shortcuts, display options
Iframe apps	Guest origin builds itself	`packages/app-registry` supplies dev/prod URLs
Future standalone app	Own `apps/<name>` build	Registers as iframe or isolated host per manifest

Anti-pattern: Importing apps/os-shell/src/shell/** from an iframe guest or from packages/os-apps.

React 18 and StrictMode

Current: apps/os-shell/src/index.tsx wraps the tree in <React.StrictMode>.

Concurrent mindset: Prefer transitions and non-blocking updates for heavy UI; avoid assuming synchronous mount-only side effects.

StrictMode in development: Effects and certain lifecycles may run twice. Shell code must:

Register and clean up listeners in effect cleanups.
Guard store hydration so duplicate runs do not corrupt layout.
Avoid “fixing” StrictMode by removing it without fixing root cause.

Related: Boot gradient application runs before createRoot in applyBootShellAppearance() so the loading screen matches persisted theme without relying on a single effect pass.

App Runtime vs Bundle

Runtime kinds (from manifests) do not always equal separate bundles:

Runtime kind	Bundle behavior (current)
`os-package`	Eager or lazy chunk via shell import graph
`local-module`	Shell bundle
`iframe`	Separate origin; sandboxed in `AppWindow`
`route-app` / `isolated-app`	Planned hosts; contract types exist

Iframe apps (docs, ui-workshop, scalar, api explorer, esmadrider-me) load on demand when a window opens — they do not all ship inside the shell JS payload.

Future Direction (not shipped)

Module Federation or similar for independently versioned app bundles.
Shared vendor chunk policy across shell and first-party apps.
SSR for shell — not current; shell assumes browser OS.

Document any adoption here and in core-architecture-thinking.md when code lands.

apps/os-shell/rsbuild.config.ts
apps/os-shell/src/index.tsx
.agents/skills/rsbuild-best-practices/SKILL.md
data-flow.md
../ai/os-startup-flow.md

Build and Rendering Pipeline

On this page