Cookbook — Vite · cb-vite

Owner directive (2026-07-10), canonical. "Make canonically optimal performance for any type of Environment … after the loading the experience is as fluid and light as scientifically possible." [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:459]

Official docs

Our proven patterns

1. Vite for standalone spatial sites; Next for app shells. The Royal Orbit scroll-film ships as a Vite site (window-scrolled, one index.html of chapter <section>s); PAD/POD app surfaces ship on Next (see cb-nextjs). Choose by surface, not preference.
2. Framework-agnostic engine package. The splat engine is vanilla TS with "main": "src/index.ts" and subpath exports (./contracts, ./styles/*) so Vite consumes sources directly — no prebuild step, instant HMR into the engine. [src: HOS-Instance/packages/engine/package.json:7]
3. Static splat assets under public/assets/splats/ addressed by the manifest URL constant — Vite copies them untouched; no import-graph bloat from binary assets. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:36]
4. Typecheck as its own gate. tsc --noEmit runs as a separate script from the Vite build; the build gate in pb-001-spatial-site-loop requires both. [src: HOS-Instance/packages/engine/package.json:14]
5. ?lite=1 verification mode — a URL flag, not a build flavor, so one production bundle serves weak-hardware QA. [src: HOS-Instance/packages/engine/src/engine/quality.ts:16]

Gotchas

• Preview/headless boots can report a 0×0 viewport before layout — the renderer's measure-fallback chain exists for exactly this; do not "fix" it away in dev. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:49]
• Serve .splat files with long-lived immutable cache headers in production; the manifest (small, versioned) is the only mutable entry point. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:30]

Budgets

Bundle and loading budgets are governed by bm-001-web-perf; splat payloads by bm-002-splat-budget.

Composition

• uses: cb-threejs, cb-spark (what it bundles)
• used-by: pb-001-spatial-site-loop (steps 1, 14) · bp-001-spatial-site

See also

• cb-nextjs — the app-shell counterpart