Cookbook — Next.js · cb-nextjs

Owner directive (2026-07-10), canonical. "generate with the Holonprint Loop with gaussian splatting, lenis, tailwind, react, next, use webgl … HTML5, scroll video control." [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:498]

Official docs

Our proven patterns

1. Nested-<main> scroll root. Both HOS Next apps render pages inside <main class="flex-1 overflow-y-auto"> — the page does NOT scroll on window/body. Lenis drives that element; every ScrollTrigger resolves it via SCROLL_ROOT_SELECTOR = '[data-scroll-root], main'. A route can opt into a different container with [data-scroll-root]. [src: HOS-Webdoc/web/src/lib/scroll/scroller.ts:1]
2. One SmoothScrollProvider (root layout) + RouteScrollReset. Lenis is mounted once and persists across route changes; on App Router navigation the scroller resets to top (honoring #hash) and ScrollTrigger re-measures, while per-page triggers are torn down by each module's gsap.context cleanup — avoids stale pin-spacers between two pinned pages. [src: HOS-Webdoc/web/src/components/scroll/SmoothScrollProvider.tsx:3]
3. Server components stay plugin-free. GSAP/Lenis imports live behind 'use client' modules; the register module is the single client entry for plugins. [src: HOS-Webdoc/web/src/lib/scroll/register.ts:11]
4. App = districts surface. The Next app is the WebApp property of the genome ("login → districts → PAD (interface) / POD (data)") — routes map to districts, sections to pads/pods. [src: wiki/organizations/instances/royalorbit/genome.json:314]
5. Deploy gate before ship. tsc 0 errors + build green + route smoke (all pages 200) is the minimum CI gate, the pattern hardened across RUN-010→015 deploys [src: runs/RUN-015-autoloop.json:51].

Gotchas

• Modules that assume window scrolling break silently inside the nested-<main> shell — always resolveScroller(from) from the animating element upward. [src: HOS-Webdoc/web/src/lib/scroll/scroller.ts:14]
• Keep heavy WebGL surfaces lazy: gate them on supportsWebGL() and fall back to CSS siblings. [src: HOS-Webdoc/web/src/lib/scroll/env.ts:14]

Budgets

Route-level LCP/CLS targets: bm-001-web-perf.

Composition

• uses: cb-react · cb-tailwind · cb-lenis (via scroll kit)
• used-by: pb-001-spatial-site-loop (steps 11, 14) · bp-001-spatial-site · cb-patterns-hosweb

See also

• cb-vite — the standalone-site counterpart
• src-hosweb-routes — live route inventory