Improve homepage performance and route payload boundaries

[jderochervlk]

Context

The prerendered homepage currently inherits JavaScript and CSS owned by the React Router root route even when those resources are only needed by content, search, or playground routes. The homepage also has opportunities to reduce DOM complexity, effects, and image transfer costs.

DocsRoot is the React Router root route and should retain only resources genuinely shared by every route. Route-specific resources should move into matched child layouts or lazy boundaries.

Current baseline

• 22 initial JavaScript assets, approximately 275 KB gzip
• Shared root chunk approximately 125 KB gzip
• Initial CSS approximately 14.8 KB gzip
• 419 body elements
• 63 homepage images
• 61 images without width; all 63 without height
• No responsive picture or srcset output

These are starting measurements rather than final budgets. Deterministic build metrics should be recorded and ratcheted down as the work lands.

Proposed PR stack

• Add homepage performance guardrails: production Playwright coverage, stronger Vitest behavior coverage, and deterministic bundle/DOM/image reporting (test: add homepage performance checks #1355)
• Split the large homepage module into small, focused components and remove unused Markdown imports, unnecessary state, and redundant markup (refactor: split homepage component boundaries #1358)
• Improve font loading with self-hosted Red Hat Mono and homepage-only preloads for Inter 400/600/700 and Red Hat Mono 700 (perf(homepage): stabilize font loading [Codex] #1360)
• Refactor clipboard and gallery interactions to reduce effects and imperative DOM work (refactor(homepage): simplify clipboard and gallery interactions [Codex] #1362)
• Add responsive-image Vite integration, tuned source sets, and intrinsic dimensions for all homepage images and videos
• Lazy-load DocSearch, search-insights, and search-specific CSS after activation
• Precompute homepage code highlighting during prerendering
• Move syntax registration out of the root route and make content highlighting dependencies explicit
• Add pathless landing, content, and playground layouts and split Tailwind/CSS ownership by matched route
• Add React Compiler in annotation mode and incrementally opt cleaned homepage modules into compilation

Implementation notes

Tests and measurements

Playwright is already installed and Vitest already uses its browser provider. Add a standalone Playwright configuration for tests against the production/prerendered artifact while keeping Vitest as the component and integration layer.

Test direct loading and client navigation between the homepage, documentation, and playground routes. Assert hydration without page or console errors, preserve critical links and interactions, and avoid timing-based Lighthouse gates in CI.

Root and syntax payloads

The root route currently owns global styles, Highlight.js language registration, the navbar, and the eager search dependency. The homepage also performs runtime highlighting for two static examples and carries an unused Markdown component dependency.

Move fixed homepage highlighting into its prerender loader. Scope content highlighting explicitly so the homepage does not preload Highlight.js core, the full language set, Markdown, or MarkdownComponents.

Route CSS

Split styles into shared foundation, landing, content, playground, and lazy search inputs. Use pathless layouts and route links exports to associate resources with matched routes. Ensure Tailwind theme/preflight is emitted once, and verify cascade order and flashes during client navigation.

Images

Use @responsive-image/react, @responsive-image/vite-plugin, and @responsive-image/core for the five raster placements that benefit from adaptive variants. Keep small illustrations, icons, logos, and video posters simple, but give every image and video accurate intrinsic dimensions and appropriate loading priority.

Measure the responsive-image React runtime because the supported component currently uses an effect per mounted image.

React Compiler

Configure annotation mode targeting React 19 and opt in only homepage modules with stable component boundaries and cleaned-up effects. Keep existing manual memoization during the initial rollout.

Acceptance criteria

• Every layer passes ReScript compilation, Vitest, production build, built-site Playwright tests, and the homepage asset report
• Root JavaScript contains no eager DocSearch, search-insights, or global syntax-language registration
• Homepage initial assets exclude Markdown, MarkdownComponents, and the full Highlight.js runtime
• Search implementation and styles load only after activation
• Responsive raster placements emit picture, srcset, and accurate sizes
• Every homepage image and video has numeric intrinsic dimensions
• Below-fold images do not become initial preload candidates
• Homepage CSS excludes documentation, DocSearch, and playground-only rules
• Direct loads and client transitions preserve styling and syntax highlighting without hydration errors
• Theme and preflight are emitted only once per page
• React Compiler is enabled incrementally without behavior or bundle regressions
• Each completed PR records before/after raw and gzip asset totals

[jderochervlk]

Follow-up boundary audit after the first four stack layers: DocsRoot is the React Router root module, but currently exports no loader (hasLoader: false in the generated manifest). The root payload is dominated by eager search and syntax imports, not loader data.

For the root-boundary work, isolate DocSearch/search-insights and search CSS behind activation first, then prerender the fixed homepage highlighting and move full syntax registration into content boundaries. Route/layout CSS ownership should follow those changes; pathless layouts alone will not split Tailwind output.

Documentation category collections can later move into subgroup loaders, but this is a separate data/build cleanup. Keep all filesystem-backed loaders and MDX work outside any root or layout shared with runtime /try.

The current interaction layer measures 273,627 bytes of initial gzip JavaScript, 14,906 bytes of gzip CSS, and 409 body elements. Existing media/dimension gaps remain for the responsive-image slice.

[jderochervlk]

Implementation progress for the homepage performance stack:

• test: add homepage performance checks #1355: production Playwright/Vitest guardrails, deterministic asset budgets, and Lighthouse against completed Cloudflare deployments.
• refactor: split homepage component boundaries #1358, perf(homepage): stabilize font loading [Codex] #1360, refactor(homepage): simplify clipboard and gallery interactions [Codex] #1362: focused components, self-hosted/preloaded fonts, and simplified clipboard/gallery interactions.
• perf(homepage): load DocSearch on demand [Codex] #1363, perf(homepage): prerender the highlighted code examples [Codex] #1364, perf(homepage): load syntax grammars at content boundaries [Codex] #1365: activation-only search, prerendered homepage highlighting, and content-owned syntax registration.
• perf(homepage): optimize responsive images and reserve media dimensions [Codex] #1366, perf(homepage): split CSS by route group [Codex] #1367: responsive media with intrinsic dimensions and matched-route CSS.
• perf: opt homepage and navbar into React Compiler [Codex] #1369: React Compiler in React 19 annotation mode for Intro, InstallInstructions, and TrustedBy. Local verification, independent review and all ten current-head CI checks are complete; the PR is ready for review.

Using the recorded #1355 guardrail baseline, rather than the earlier approximate issue measurements:

Metric	Baseline	Current compiler build
Initial JavaScript, raw bytes	1,410,064	972,705
Initial JavaScript, gzip bytes	284,515	146,537
Initial CSS, raw bytes	80,247	45,176
Initial CSS, gzip bytes	14,725	10,366
Initial JavaScript requests	21	25
Initial CSS requests	3	3
Body elements	418	415
Images missing width / height	61 / 63	0 / 0
Videos missing width / height	3 / 3	0 / 0

That is 48.5% less initial gzip JavaScript and 29.6% less gzip CSS. The compiler layer itself adds 427 gzip JavaScript bytes over #1367; CSS and DOM remain unchanged.

Implementation details:

• DocsRoot has no loader; the work removes eager imports and gives child routes ownership of their resources.
• Responsive-image generates AVIF/WebP variants at build time. Native picture/img markup consumes its metadata without adding the React component runtime or per-image effects.
• Homepage/content use pathless layouts; /try owns its stylesheet directly. Custom theme tokens, fonts, and preflight emit once. Shared shell utilities repeat where needed to preserve responsive cascade ordering.
• Font assets are same-origin, so no external preconnect is needed.

Lighthouse remains informational: three deployed-preview runs, a current artifact per branch, and comparison against the PR target branch with N/A for missing baselines. No score threshold is enforced.

All ten PRs are ready for review, have passing latest CI, and request review from @fhammerschmidt. Nothing has been merged. Two existing #1364 review threads remain pending the previously requested approval. Existing /try/404 baseline errors and the installation page's missing-YAML highlighting warning remain outside this performance work; this does not claim they are fixed. The YAML warning was reproduced on production and on the pre-boundary #1364 preview.