Repository navigation
docs: add guide for optimizing the static shell - #97737
Merged
Merged
Conversation
Contributor
Stats from current PR🔴 1 regression, 1 improvement
📊 All Metrics📖 Metrics GlossaryDev Server Metrics:
Build Metrics:
Change Thresholds:
⚡ Dev Server
📦 Dev Server (Webpack) (Legacy)📦 Dev Server (Webpack)
⚡ Production Builds
📦 Production Builds (Webpack) (Legacy)📦 Production Builds (Webpack)
📦 Bundle SizesBundle Sizes⚡ TurbopackClient Main Bundles
Server Middleware
Build DetailsBuild Manifests
Build Cache
📦 WebpackClient Main Bundles
Polyfills
Pages
Server Edge SSR
Middleware
Build DetailsBuild Manifests
Build Cache
🔄 Shared (bundler-independent)Runtimes
📝 Changed Files (33 files)Files with changes:
View diffsapp-page-exp..ntime.dev.jsfailed to diffapp-page-exp..time.prod.jsDiff too large to display app-page-tur..ntime.dev.jsfailed to diffapp-page-tur..time.prod.jsDiff too large to display app-page-tur..ntime.dev.jsfailed to diffapp-page-tur..time.prod.jsDiff too large to display app-page.runtime.dev.jsfailed to diffapp-page.runtime.prod.jsDiff too large to display app-route-ex..ntime.dev.jsDiff too large to display app-route-ex..time.prod.jsDiff too large to display app-route-tu..ntime.dev.jsDiff too large to display app-route-tu..time.prod.jsDiff too large to display app-route-tu..ntime.dev.jsDiff too large to display app-route-tu..time.prod.jsDiff too large to display app-route.runtime.dev.jsDiff too large to display app-route.ru..time.prod.jsDiff too large to display dev-validati..ntime.dev.jsfailed to diffdev-validati..ntime.dev.jsfailed to diffdev-validati..ntime.dev.jsfailed to diffdev-validati..ntime.dev.jsfailed to diffpages-api-tu..ntime.dev.jsDiff too large to display pages-api-tu..time.prod.jsDiff too large to display pages-api.runtime.dev.jsDiff too large to display pages-api.ru..time.prod.jsDiff too large to display pages-turbo...ntime.dev.jsDiff too large to display pages-turbo...time.prod.jsDiff too large to display pages.runtime.dev.jsDiff too large to display pages.runtime.prod.jsDiff too large to display server.runtime.prod.jsDiff too large to display use-cache-pr..ntime.dev.jsDiff too large to display use-cache-pr..ntime.dev.jsDiff too large to display use-cache-pr..ntime.dev.jsDiff too large to display use-cache-pr..ntime.dev.jsDiff too large to display 📎 Tarball URLCommit: c5854eb |
Contributor
Tests PassedCommit: 5842cd1 |
Contributor
|
All broken links are now fixed, thank you! |
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
This was referenced Aug 24, 2026
gaojude
approved these changes
Aug 27, 2026
aurorascharff
added a commit
that referenced
this pull request
Aug 27, 2026
## What Adds an agent eval for the static-shell optimization workflow in #97737. The fixture uses a release-operations route with a request-specific viewer, reusable checklist, live rollout data, and both direct and client navigation. ## Why This tests whether agents can transfer the guide and optimizer skill to a difficult refactor that is similar to, but not copied from, the guide example. ## Verification - Claude Sonnet 4.6: baseline 2/7, bundled docs 2/7, optimizer skill 6/7 - The skill treatment passed every final-code criterion; its only miss was executing the browser RED-to-GREEN loop because the sandbox lacked Chromium libraries - Browser-dependent fixtures now provision those libraries during setup; a follow-up attempt passed setup but stalled before producing a transcript
aurorascharff
changed the base branch from
canary
to
codex/adoption-skill-evals
August 27, 2026 17:06
aurorascharff
added a commit
that referenced
this pull request
Sep 8, 2026
Adds an agent eval for the static-shell optimization workflow in #97737. The fixture uses a release-operations route with a request-specific viewer, reusable checklist, live rollout data, and both direct and client navigation. This tests whether agents can transfer the guide and optimizer skill to a difficult refactor that is similar to, but not copied from, the guide example. - Claude Sonnet 4.6: baseline 2/7, bundled docs 2/7, optimizer skill 6/7 - The skill treatment passed every final-code criterion; its only miss was executing the browser RED-to-GREEN loop because the sandbox lacked Chromium libraries - Browser-dependent fixtures now provision those libraries during setup; a follow-up attempt passed setup but stalled before producing a transcript
aurorascharff
force-pushed
the
codex/optimize-static-shell-guide
branch
from
September 8, 2026 21:08
a2a4dca to
2d3e336
Compare
aurorascharff
added a commit
that referenced
this pull request
Sep 10, 2026
Adds an agent eval for the static-shell optimization workflow in #97737. The fixture uses a release-operations route with a request-specific viewer, reusable checklist, live rollout data, and both direct and client navigation. This tests whether agents can transfer the guide and optimizer skill to a difficult refactor that is similar to, but not copied from, the guide example. - Claude Sonnet 4.6: baseline 2/7, bundled docs 2/7, optimizer skill 6/7 - The skill treatment passed every final-code criterion; its only miss was executing the browser RED-to-GREEN loop because the sandbox lacked Chromium libraries - Browser-dependent fixtures now provision those libraries during setup; a follow-up attempt passed setup but stalled before producing a transcript
aurorascharff
force-pushed
the
codex/optimize-static-shell-guide
branch
from
September 10, 2026 09:20
8ee42d4 to
b1698b2
Compare
aurorascharff
added a commit
that referenced
this pull request
Sep 10, 2026
Adds an agent eval for the static-shell optimization workflow in #97737. The fixture uses a release-operations route with a request-specific viewer, reusable checklist, live rollout data, and both direct and client navigation. This tests whether agents can transfer the guide and optimizer skill to a difficult refactor that is similar to, but not copied from, the guide example. - Claude Sonnet 4.6: baseline 2/7, bundled docs 2/7, optimizer skill 6/7 - The skill treatment passed every final-code criterion; its only miss was executing the browser RED-to-GREEN loop because the sandbox lacked Chromium libraries - Browser-dependent fixtures now provision those libraries during setup; a follow-up attempt passed setup but stalled before producing a transcript
aurorascharff
force-pushed
the
codex/optimize-static-shell-guide
branch
from
September 10, 2026 13:34
e81343d to
06887cd
Compare
aurorascharff
changed the base branch from
canary
to
codex/partial-prefetching-optimizer
September 10, 2026 13:34
aurorascharff
added a commit
that referenced
this pull request
Sep 10, 2026
## Summary - add a Partial Prefetching optimizer Skill for selected source Links and destinations - keep prefetch stages and Link policy in the public [Optimizing prefetching guide](https://nextjs.org/docs/app/guides/optimizing-prefetching), and rely on the same static-shell documentation as the Cache Components optimizer for cache placement, Suspense, loading UI, and authorization - keep the Skill focused on the product decision, production `instant()` loop, differential verification, and mutation freshness when an optimization adds a cache around mutable data - reference the canonical [`unstable_prefetch()`](https://nextjs.org/docs/app/api-reference/functions/prefetch) and [`unstable_navigation()`](https://nextjs.org/docs/app/api-reference/functions/navigation) docs instead of explaining the APIs again in the Skill - link cache-writing optimizations to the canonical [Revalidating](https://nextjs.org/docs/app/getting-started/caching-and-revalidating#revalidating) documentation and verify a populated-cache mutation in the Skill and eval - bundle a self-contained production rig aligned with the related adoption and optimizer Skills, tuned to record each source-link and prefetch-stage contract - add an eval that compares baseline, the bundled guide, and the local Skill against the same prefetched-UI and cache-freshness goal - document the optimizer in the AI agents guide This follows the same guide/Skill split as #97737. Partial Prefetching adoption preserves existing behavior; this optimizer is the later decision about what is worth preparing before a click and what should wait for navigation. Related: #97712, #97737, #97759, #98122, #98175 ## Eval One run per treatment with Claude Opus 4.8 and Claude Sonnet 4.5, using a fixed Claude Haiku 4.5 judge. The bundled-guide and Skill treatments use a local Next.js tarball containing the new guide and API references. | Model | Treatment | Criteria | Score change | Overall | Duration | Tokens processed | Total run cost | Cost change | | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | Opus 4.8 | Baseline | 10/10 (100%) | — | Pass | 18m 42s | 3.39M | $3.46 | — | | Opus 4.8 | Bundled guide | 9/10 (90%) | -10 pp | Fail | 13m 37s | 3.02M | $2.84 | -18.0% | | Opus 4.8 | Local Skill | 10/10 (100%) | +10 pp | Pass | 17m 22s | 2.80M | $2.54 | -10.6% | | Sonnet 4.5 | Baseline | 2/10 (20%) | — | Fail | 15m 55s | 1.97M | $1.06 | — | | Sonnet 4.5 | Bundled guide | 5/10 (50%) | +30 pp | Fail | 15m 49s | 2.17M | $1.11 | +4.5% | | Sonnet 4.5 | Local Skill | 8/10 (80%) | +30 pp | Fail | 15m 31s | 1.41M | $0.77 | -30.4% | Token totals count each unique model message once and include uncached input, cache creation, cache reads, and output. Cache reads account for most of the total in every treatment. Total run cost applies the current AI Gateway base rates to each token category: Opus 4.8 costs $5/M input, $6.25/M cache writes, $0.50/M cache reads, and $25/M output; Sonnet 4.5 costs $3/M input, $3.75/M cache writes, $0.30/M cache reads, and $15/M output. The six agent runs cost $11.78 in total. Compared with baseline, the Opus Skill run maintained a 100% criteria pass rate while reducing cost by 26.7%. The Sonnet Skill run improved the criteria pass rate from 20% to 80%, a 60 percentage-point increase, while reducing cost by 27.3%. The stronger model could solve the fixture without the Skill, although it independently searched the bundled Next.js documentation and took slightly longer than the Skill treatment. The Opus guide-only run implemented the correct behavior but missed the required RED-before-GREEN proof. The Sonnet treatments show a clearer progression. Baseline did not implement the required caching, navigation stage, `instant()` contract, or cache invalidation. The bundled guide added the cached summary and production test, but missed the navigation stage, deferred-state assertions, tag invalidation, and RED-before-GREEN proof. The Skill treatment completed the `instant()` RED-to-GREEN loop and final production behavior, but left `connection()` in the related-sessions read and used path revalidation instead of tagging the cached read. It therefore passed 8 of 10 criteria but failed the overall eval. All six measured runs completed through grading. Chromium and its system dependencies are provisioned before the agent starts, so missing browser libraries did not determine these results. ## Verification - `pnpm --filter=next build` - `pnpm prettier --check` for the changed guide, prompt, Skill, and eval fixture - `pnpm exec tsc -p evals/evals/agent-051-optimize-partial-prefetching/tsconfig.json --noEmit` - `node --check run-evals.js` - `git diff --check` - packed a local Next.js tarball and confirmed it contains the optimizer guide plus the `navigation()` and `prefetch()` references - verified the `navigation()` contract in the minimal reproduction and NextBeats on Next.js 16.4.0-canary.22 - merged the latest `canary`, preserving both generic fixture setup and Playwright provisioning <!-- NEXT_JS_LLM -->
Base automatically changed from
codex/partial-prefetching-optimizer
to
canary
September 10, 2026 20:27
aurorascharff
marked this pull request as ready for review
September 10, 2026 20:29
aurorascharff
marked this pull request as ready for review
September 11, 2026 14:02
This was referenced Sep 11, 2026
gaojude
approved these changes
Sep 17, 2026
icyJoseph
reviewed
Sep 23, 2026
icyJoseph
reviewed
Sep 23, 2026
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Unresolved moderate findings remain in the Playwright lifecycle guidance and evaluation coverage.
Review effort: Lite
Findings: 1
Open (2)
What changed in this PR
Adds an “Optimizing the static shell” guide, aligns related optimizer Skills and verification workflows, and introduces a production evaluation fixture.
Changes:
- Adds static-shell optimization patterns and cross-links.
- Strengthens
instant()testing and marker guidance. - Adds and registers the static-shell evaluation fixture.
| File | Description |
|---|---|
skills/next-partial-prefetching-optimizer/reference/red-test-robustness.md |
Strengthens committed-marker guidance. |
skills/next-partial-prefetching-adoption/rig-template.md |
Adds visible DOM-marker requirements. |
skills/next-cache-components-optimizer/test-template.md |
Clarifies focused tests and initial-load behavior. |
skills/next-cache-components-optimizer/SKILL.md |
Delegates framework patterns to the new guide. |
skills/next-cache-components-optimizer/rig-template.md |
Refines Playwright lifecycle guidance. |
skills/next-cache-components-optimizer/reference/red-test-robustness.md |
Expands RED validation checks. |
skills/next-cache-components-optimizer/reference/real-app-patterns.md |
Removes duplicated framework patterns. |
skills/next-cache-components-optimizer/reference/patterns.md |
Removes duplicated framework patterns. |
evals/README.md |
Documents browser-dependent eval setup. |
evals/evals/agent-050-optimize-static-shell/tsconfig.json |
Adds eval TypeScript configuration. |
evals/evals/agent-050-optimize-static-shell/tests/helpers.ts |
Adds eval URL helpers. |
evals/evals/agent-050-optimize-static-shell/PROMPT.md |
Defines the static-shell optimization task. |
evals/evals/agent-050-optimize-static-shell/playwright.config.ts |
Configures the production Playwright rig. |
evals/evals/agent-050-optimize-static-shell/package.json |
Defines fixture dependencies and scripts. |
evals/evals/agent-050-optimize-static-shell/next.config.ts |
Enables Cache Components and test API exposure. |
evals/evals/agent-050-optimize-static-shell/next-env.d.ts |
Adds Next.js type references. |
evals/evals/agent-050-optimize-static-shell/lib/releases.ts |
Provides fixture data sources. |
evals/evals/agent-050-optimize-static-shell/instant-nav.rig.md |
Documents the production test contract. |
evals/evals/agent-050-optimize-static-shell/EVAL.ts |
Defines evaluation checks. |
evals/evals/agent-050-optimize-static-shell/data/launch-checklist.json |
Supplies reusable checklist data. |
evals/evals/agent-050-optimize-static-shell/app/releases/[release]/viewer-controls.tsx |
Defines viewer UI and skeleton. |
evals/evals/agent-050-optimize-static-shell/app/releases/[release]/release-panels.tsx |
Defines checklist and rollout panels. |
evals/evals/agent-050-optimize-static-shell/app/releases/[release]/page.tsx |
Defines the release route. |
evals/evals/agent-050-optimize-static-shell/app/releases/[release]/layout.tsx |
Defines the release layout. |
evals/evals/agent-050-optimize-static-shell/app/page.tsx |
Adds the navigation source page. |
evals/evals/agent-050-optimize-static-shell/app/layout.tsx |
Adds the fixture root layout. |
evals/eval.config.json |
Registers the new eval fixture. |
docs/01-app/02-guides/streaming.mdx |
Links to the new guide. |
docs/01-app/02-guides/optimizing-the-static-shell.mdx |
Adds the static-shell guide. |
docs/01-app/02-guides/optimizing-prefetching.mdx |
Adds optimizer guidance. |
docs/01-app/02-guides/migrating-to-cache-components.mdx |
Links the new guide and canonical Skill. |
docs/01-app/02-guides/instant-navigation.mdx |
Updates static-shell guidance. |
docs/01-app/02-guides/ai-agents.mdx |
Updates optimizer Skill documentation. |
docs/01-app/02-guides/adopting-partial-prefetching.mdx |
Links the canonical adoption Skill. |
docs/01-app/01-getting-started/08-caching.mdx |
Links the new workflow guide. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
devjiwonchoi
approved these changes
Oct 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Adds an Optimizing the static shell guide that follows one team settings route through focused Suspense boundaries, deferred authentication, cache-versus-stream decisions, loading-state reuse, shared layouts, and parallel routes.
Updates
next-cache-components-optimizerto use that guide and the canonical Insight pages as its framework source of truth. The original phase-based Skill workflow is preserved, including the production rig, exact test contract, trustworthy RED-to-GREEN loop, parity check, differential, and reporting. Reusable implementation guidance now links to the corresponding guide section instead of being duplicated in Skill-only references.Clarifies that the optimizer can target either a direct page load or a named client navigation. Both use the same App Shell patterns and
instant()verification loop. When the destination App Shell is already instant and the goal is to include additional URL-specific content before a click, the Skill hands off to the Partial Prefetching optimizer.Aligns the Cache Components and Partial Prefetching optimizers around the same workflow: define the contract, reuse the production rig, prove current behavior, make the smallest optimization, verify and ship. Their framework-specific decisions remain separate. The Partial Prefetching adoption rig also receives the shared visible, committed DOM-marker rule because it uses the same
instant()testing API.Why?
The optimizer's framework patterns are useful outside the agent workflow. Keeping them in public docs gives developers and agents one source of truth while each Skill stays focused on its product decision and reliable production verification.
Eval
The corrected-contract comparison uses Claude Opus 4.8 and Claude Sonnet 4.5 with a fixed Claude Haiku 4.5 judge. It compares the baseline, bundled guide, production Skill from
canary, and proposed local Skill. The bundled-guide and Skill treatments use a local Next.js tarball containing the new guide.The eval now contains 11 granular checks so product behavior, test quality, and workflow discipline are visible independently. They cover configuration, direct and client-navigation
instant()coverage, exact shell markers, preserved data sources, reusable and request-time UI placement, all completed-route variants, viewer-cookie behavior, trustworthy RED, full-suite GREEN, and the bounded differential. The prompt names the Aurora, Nebula, unknown-release, and viewer-cookie parity cases explicitly.All eight treatments were rerun against this 11-check rubric.
Token totals count each unique model message once and include uncached input, cache creation, cache reads, and output. Total run cost applies the current AI Gateway base rates to each token category. Judge cost is excluded.
The eight runs processed 31.87M tokens and cost $24.91 in total, excluding the judge. This is one run per model and treatment, so the comparison is descriptive rather than a stable pass-rate measurement.
The proposed Opus Skill is the only treatment to pass every check. Baseline and production Skill each passed 9/11, but both skipped the bounded differential. Baseline also missed the viewer-cookie timing lock. Production Skill omitted exact loading-state coverage. The guide-only treatment implemented the product behavior but missed an exact selector, trustworthy RED, and the differential.
The proposed Sonnet Skill preserved the exact
instant()contract, but replaced the existing runtime file read with a build-time import. It then stopped using the documented production command, encountered port conflicts from starting another Playwright server lifecycle, and never completed parity, GREEN, or a valid differential. This is a model adherence failure rather than a sandbox or credential failure. It shows that the restored workflow is sufficient for Opus but still too easy for Sonnet to abandon after it encounters test friction.Verification