community-rule/docs/perf/next16-eval.md

Next 16 substrate evaluation (Phase 3)

Evaluation of experimental.cacheComponents (formerly experimental.ppr) and React Compiler against this repo on Next.js 16.2.6. Performed as a canary build pass without committing either flag to main.

TL;DR

Flag	Recommendation	Why
cacheComponents (PPR successor)	Defer — requires a follow-up refactor before it can ship	Renamed from ppr in Next 16; now a boolean global toggle, no per-route experimental_ppr opt-in. Requires removing force-dynamic from (app) and (admin) layouts and re-expressing session-aware dynamism via Suspense + cache primitives.
React Compiler	Defer — config surface moved + missing dep	Moved out of experimental to the top-level reactCompiler key in Next 16. Requires installing babel-plugin-react-compiler. No blocking codebase incompatibilities found in the canary surface, but the install + eslint plugin setup is its own follow-up task.

Neither flag was shippable as a pure config flip in this audit. The findings below describe what changed in Next 16 and the work each would require.

Repo baseline (Next 16.2.6, Turbopack, no experimental flags)

• Build status: clean (npx next build)
• Static routes: /, /_not-found, /about, /blog, /components-preview, /how-it-works, /learn, /templates, /use-cases
• SSG routes: /blog/[slug], /use-cases/[slug], /use-cases/[slug]/rule
• Dynamic routes: all /api/*, /create, /create/[screenId], /create/review-template/[slug], /login, /monitor, /profile, /rules/[id]
• .next/static total: 3.6 MB (uncompressed)

Note: Next 16 with Turbopack no longer prints per-route first-load JS sizes in the build summary. Bundle analyzer (ANALYZE=true) is the canonical source for size data — see Phase 4a.

3a. cacheComponents (PPR) — DEFER

What changed in Next 16

experimental.ppr has been merged into experimental.cacheComponents:

Error: experimental.ppr has been merged into cacheComponents. The Partial
Prerendering feature is still available, but is now enabled via cacheComponents.

Crucially, the per-route incremental opt-in is gone:

cacheComponents: invalid type: string "incremental", expected a boolean

So cacheComponents: true flips PPR semantics on globally for every route.

Blocker

With cacheComponents: true, the build fails:

./app/(admin)/layout.tsx:6:14
Route segment config "dynamic" is not compatible with `nextConfig.cacheComponents`.
Please remove it.

./app/(app)/layout.tsx:8:14
Route segment config "dynamic" is not compatible with `nextConfig.cacheComponents`.
Please remove it.

Both layouts use export const dynamic = "force-dynamic" to render session-aware chrome (set in Phase 4b of the prior plan). cacheComponents requires expressing that dynamism via <Suspense> boundaries plus unstable_noStore()/unstable_cache() instead of route-segment dynamic.

Estimated work to ship

1. Refactor app/(app)/layout.tsx and app/(admin)/layout.tsx so the ConditionalNavigation session fetch sits inside a <Suspense> boundary with a fallback that matches the generic chrome.
2. Mark the session-reading components with unstable_noStore() (or the stable equivalent in Next 16) so they opt out of the static cache.
3. Verify the existing static routes (/, /about, /blog, etc.) still prerender; add <Suspense> boundaries around any future dynamic islands.
4. Confirm (marketing) routes still serve from CDN with the static shell while the personalized nav island streams.

This is the natural next step after Phase 4b made marketing static, but it's not a config-only change. Ticket separately.

Verification (when shipping)

• (marketing) routes still appear as ○ Static in build output.
• (app)/(admin) routes' static shell prerenders; the personalized nav streams (visible in curl of the HTML — partial shell first, then nav).
• TTFB on (marketing) unchanged or improved.

3b. React Compiler — DEFER

What changed in Next 16

experimental.reactCompiler moved to the top-level reactCompiler key:

⚠ `experimental.reactCompiler` has been moved to `reactCompiler`. Please
update your next.config.mjs file accordingly.

And requires the babel plugin to be installed:

Failed to resolve package babel-plugin-react-compiler while attempting to
resolve React Compiler. We attempted to resolve React Compiler relative
to the next package. Is babel-plugin-react-compiler installed in your
node_modules directory?

Estimated work to ship

1. npm install --save-dev babel-plugin-react-compiler eslint-plugin-react-compiler.
2. Add reactCompiler: { compilationMode: "annotation" } to next.config.mjs (top-level, not under experimental).
3. Enable eslint-plugin-react-compiler and run it against the repo to surface components that would bail (refs mutated during render, reads of non-reactive globals inline, etc.).
4. Incrementally add "use memo" directives to high-render-frequency containers (CreateFlowProvider, AuthModalProvider, list-heavy views).
5. Once stable, flip compilationMode: "all" and remove hand-written useMemo/useCallback where the compiler subsumes them.

Why annotation mode first

We have many hand-rolled memoized containers. The risk of compilationMode: "all" on day one is that the compiler bails on a critical component in a way that changes render counts. Annotation mode lets us migrate one component at a time with eslint enforcement.

Verification (when shipping)

• Bundle size before/after next build with the runtime added.
• Test suite green (npx vitest run — 196 files / 1251 tests today).
• Component render counts unchanged or reduced on key surfaces (use the React DevTools profiler on /create/informational and /).

Impact on Phase 4 (MessagesProvider)

If we later ship cacheComponents, the MessagesProvider refactor's win shrinks meaningfully: the messages dictionary lives in the static shell of every route, and only the dynamic island re-fetches. The static prerender output is already cacheable at the CDN. So Phase 4 should be re-evaluated after the cacheComponents work lands, not before.

If we don't ship cacheComponents, Phase 4's bundle-size measurement (Phase 4a) is still the right gate — measure first, refactor only if the data justifies it.

What to do now

• Skip both flags for this performance follow-ups plan.
• File two follow-up tickets:
  1. "Enable cacheComponents: refactor (app)/(admin) layouts to Suspense + cache primitives, remove force-dynamic from route segments."
  2. "Adopt React Compiler in annotation mode: install plugin, enable eslint rule, migrate top containers."
• Proceed with Phase 4a (measure) and let the data drive Phase 4b.