next-partial-prefetching-optimizer

1---2name: next-partial-prefetching-optimizer3description: >4  Optimize what selected Next.js client navigations include before the click5  under Partial Prefetching. Use after Cache Components and Partial Prefetching6  are adopted when the user wants selected URL-specific UI to be instant,7  wants reusable content to wait for navigation, or needs to choose between8  default, viewport, and intent prefetching. Requires Next.js 16.3+.9---10 11# Partial Prefetching optimizer12 13Optimize each requested source link and destination as its own contract. Turn14the requested prefetched UI, navigation-only UI, and trigger into a production15[`instant()`](https://nextjs.org/docs/app/guides/instant-navigation#prevent-regressions-with-e2e-tests)16test. Record the current behavior, make the smallest optimization, verify the17differential, and keep the passing test as regression coverage.18 19Before making framework changes, read the bundled Optimizing prefetching guide20at21`node_modules/next/dist/docs/01-app/02-guides/optimizing-prefetching.md`. If the22bundled guide is unavailable, use the [online23guide](https://nextjs.org/docs/app/guides/optimizing-prefetching). It is the24source of truth for prefetch stages, `prefetch={true}`, session-specific UI,25and cost trade-offs.26 27When the work changes what belongs in the App Shell, follow the28[Instant navigation](https://nextjs.org/docs/app/guides/instant-navigation) and29[Caching](https://nextjs.org/docs/app/getting-started/caching) docs for cache30placement, Suspense boundaries, loading UI, and authorization.31 32The guides own framework behavior and implementation patterns. This skill owns33the navigation contract, production rig, trustworthy RED-to-GREEN loop, parity34check, differential, and report.35 36This is not an adoption skill. If Cache Components or Partial Prefetching are37not adopted, use their adoption skills and return to this workflow. If the App38Shell itself cannot commit under `instant()`, use39`next-cache-components-optimizer` first, then resume the selected navigation.40 41Run the workflow unattended. Resolve the contract from the request and the42existing application. Stop for user input only when a product decision is43genuinely blocked and cannot be inferred safely without changing cost,44freshness, authorization, or user-visible behavior.45 46## Reporting to the user47 48This loop runs unattended, so do not stop between implementation steps. Finish49the navigations the user named, then check in. The rig, lock, RED/GREEN loop,50and stage names are internal scaffolding; report the product behavior instead.51 52- **Speak their language.** Describe the source link and result in terms of53  what the user sees before and after the click, not the validation mechanics.54- **Show, don't tell.** Drive the exact link in a production browser so the user55  sees which content is already available and which content streams after the56  click. If a live demonstration is unavailable, attach before/after captures.57- **Give them a concise click-through list, not a technical results table.** Use58  one line per navigation with the source URL, link to click, UI ready before59  the click, UI that waits for navigation, and whether prefetching starts in the60  viewport or after intent.61- **Only surface a question for a genuine fork.** Ask when the choice changes62  cost, freshness, authorization, or visible behavior. If the user already63  requested a PR or named every navigation, finish that scope without asking64  again.65 66## Define the contract67 68Inspect the source route, the exact link or interaction, the destination's69Suspense boundaries, its data reads, existing prefetch policy, and any existing70`instant()` test. Record:71 72- which destination UI should be ready before the click;73- which reusable UI should wait for navigation;74- whether per-link prefetching should start in the viewport or only after75  intent.76 77The trigger is part of the contract. Two links to the same URL may use78different prefetch policies and need separate tests.79 80Use the guide's cost model when the trigger is not already specified. Do not81silently increase the number of links that can invoke the server or cache data82whose freshness contract is unknown.83 84## Reuse the production rig85 86Read an existing `instant-nav.rig.md`. Cache Components optimization, Partial87Prefetching adoption, and this optimizer share the same build, auth, data, and88Playwright contract. Add the exact source link, destination markers, and89prefetch budget instead of creating another rig.90 91If the project has no rig, use [`rig-template.md`](rig-template.md) to discover92and record one. The measured run must be a production build or93preview where `experimental.exposeTestingApiInProductionBuild` is enabled only94for testing. Development can help diagnose a route, but automatic link95prefetching is production-only.96 97## Prove the current behavior98 99Search for an existing `instant()` test for the exact source link and100destination. Extend it when it already covers the same behavior. Otherwise,101add a focused click-driven test using the guide's102[prefetched and deferred content testing](https://nextjs.org/docs/app/guides/optimizing-prefetching#test-prefetched-and-deferred-content)103pattern.104 105Keep one production browser test per source-link, destination, and trigger106contract. Do not loop over several destinations or collect their readiness107results in one test. Focused tests can still run serially in one browser worker.108 109First, run an unlocked scaffold that proves the link reaches the exact pathname110and query and that the selected UI eventually renders for the test user. Do not111ship this scaffold.112 113Then run the same interaction inside `instant()`. The existing App Shell must114stay visible, while the guide's positive and negative assertions capture the115prefetched result. After the lock releases, every selected region must116eventually render.117 118Read [`reference/red-test-robustness.md`](reference/red-test-robustness.md)119before treating this failure as RED. A timeout before the URL changes, a120missing App Shell, a redirect, missing data, or a stale preview indicates a rig121or route problem. It does not justify changing prefetching.122 123If the complete desired contract already passes under the lock, stop. Never124add `prefetch={false}` merely to manufacture a RED.125 126Only test files and the configuration needed to expose the testing API may127change before these runs finish. Run builds and tests in the foreground. If the128harness moves one into the background, wait for it to exit and continue the129loop in the same task. A written test or a build still in progress is not130verification.131 132## Make the smallest optimization133 134Follow the Optimizing prefetching guide for stage and link policy. If the135contract also requires changing cache placement, Suspense, or loading UI,136follow the static-shell documentation used by137`next-cache-components-optimizer`. Preserve the existing freshness and138authorization behavior. Change only what the selected contract requires.139 140When reusable UI should wait for navigation, follow the141[`unstable_navigation()`](https://nextjs.org/docs/app/api-reference/functions/navigation)142reference, including its comparison with `connection()`. Then verify both143properties independently. The `instant()` assertion proves that the UI is144absent from the prefetch; it does not prove that the underlying work stayed145reusable. Verify that reusable work remains cached below the stage boundary.146 147When the contract needs an explicit runtime stage, follow the API references148for [`unstable_prefetch()`](https://nextjs.org/docs/app/api-reference/functions/prefetch)149and150[`unstable_navigation()`](https://nextjs.org/docs/app/api-reference/functions/navigation).151 152Work one accepted navigation to GREEN before moving to another. Do not create153an app-wide Link or cache abstraction from a single case.154 155If the optimization adds or expands a cache boundary, follow156[Revalidating](https://nextjs.org/docs/app/getting-started/revalidating).157When a writer can change that cached data, test the complete lifecycle: populate158the cache, perform the mutation, then read the data again and verify the updated159value. A passing `instant()` test proves prefetched readiness, not mutation160freshness.161 162## Verify and ship163 164Keep the passing locked test for the real source link as regression coverage.165Preserve the loaded page's content, ordering, empty and error states,166authorization, freshness, redirects, and direct-load behavior.167 168Finally, remove only the optimization and rerun the test:169 170- the App Shell stays GREEN;171- the selected prefetch contract returns RED.172 173Reapply the optimization and require GREEN again. This differential proves the174test guards the exact link policy instead of unrelated cached state. Ship only175the final positive test.176 177Report the verified result using the user-facing format above. Be precise that178prefetching is best-effort; the App Shell remains the fallback when it has not179completed.180 181Treat request counts, transferred bytes, and cache behavior as measurements,182not as part of the `instant()` contract. Do not classify requests using private183RSC URLs or internal headers such as `next-router-prefetch`. The public testing184API verifies the rendered result, not the protocol stage that produced each185request.186 187## Completion checklist188 189- [ ] Cache Components and Partial Prefetching were already adopted.190- [ ] The target UI, trigger, freshness, and authorization constraints were191      resolved from the request and existing application.192- [ ] The test clicks the exact source link and verifies the exact destination.193- [ ] Each source-link, destination, and trigger contract has its own test.194- [ ] The unlocked baseline and locked RED used the same production artifact.195- [ ] The App Shell stayed visible throughout the RED/GREEN loop.196- [ ] The selected UI is present and navigation-only UI is absent under lock.197- [ ] Reusable navigation-only work remains cached below its navigation stage.198- [ ] After populating any new cache whose data can be updated, a mutation test199      confirms the next read returns the expected data.200- [ ] Loaded content, freshness, authorization, and direct visits are unchanged.201- [ ] Removing only the optimization returns the contract to RED.202- [ ] The final positive `instant()` regression test ships.203 204## Handoff205 206Finish every navigation named in the request. If Cache Components or Partial207Prefetching are not adopted, use `next-cache-components-adoption` or208`next-partial-prefetching-adoption`, then return to this workflow. If the App209Shell cannot commit under `instant()`, use `next-cache-components-optimizer`210and resume the selected navigation afterward. Do not leave a build or test for211the user to monitor.212 213Report additional optimization candidates without changing them unless they214are already in scope. Do not broaden a selected per-link policy into an app-wide215Link or cache abstraction.216 217## Files218 219- `rig-template.md`: production build, test context, navigation contract, and220  unattended loop discovery for projects without an existing221  `instant-nav.rig.md`.222- `reference/red-test-robustness.md`: trustworthy RED and differential checks.223 224## Further reading225 226- [Optimizing prefetching](https://nextjs.org/docs/app/guides/optimizing-prefetching)227- [Instant navigation](https://nextjs.org/docs/app/guides/instant-navigation)228- [Caching](https://nextjs.org/docs/app/getting-started/caching)229- [Prefetching](https://nextjs.org/docs/app/guides/prefetching)230