# Optimize Next.js Cache Component Navigation

Next.js routes can delay their static shell while dynamic data resolves. This skill builds verified instant-navigation tests and guides Cache Components refactors that preserve behavior.

## Install

```bash
npx skillstore add vercel/next-cache-components-optimizer
```

## Metadata

- Status: approved
- Slug: vercel-next-cache-components-optimizer
- Skillstore revision: r1
- Version status: missing
- Tree hash: 6437f3d9fe208c2d5df428cb1a9d1a141affc6f08fef6252dcbcac400186936c
- Author: vercel
- GitHub username: vercel
- License: MIT
- Repository: https://github.com/vercel/next.js/tree/988a6ab72735d5c61f906d6ea0484930aa496713/skills/next-cache-components-optimizer
- Ref: bdb71a4bc34515f37772ae85fd5501f9c2ff33b0
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands, filesystem, env\_access, network
- Quality score: 77
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/vercel-next-cache-components-optimizer
- Manifest: https://skillstore.pages.dev/api/skills/vercel-next-cache-components-optimizer/manifest

## Capabilities

- Checks for Next.js 16.3 or newer and enabled Cache Components.
- Maps the project build, deployment, authentication, and Playwright test rig.
- Creates instant-navigation tests for initial loads and client-side navigation.
- Diagnoses blocking awaits, dynamic reads, Suspense placement, and static-shell gaps.
- Guides focused refactors that reuse existing loading interfaces and preserve behavior.
- Verifies baseline, failure, success, parity, and regression protection.

## Use Cases

- Fix a blocking route: Identify why a route shell waits for dynamic data, then move blocking work behind focused Suspense boundaries.
- Build a reliable test rig: Configure a production-like environment that exposes the testing API only outside production and verifies the deployed revision.
- Prevent navigation regressions: Add hard-navigation and soft-navigation checks that prove meaningful shell content commits before deferred data.

## Prompt Templates

### Check one route

```
Review the route [ROUTE]. Confirm the Next.js and Cache Components prerequisites, then explain what prevents its static shell from committing instantly.
```

### Create an instant test

```
Create a Playwright instant-navigation test for [ROUTE] using [NAVIGATION TYPE]. Use an existing static shell marker and verify the test cannot pass vacuously.
```

### Optimize and verify

```
Optimize [ROUTE] for hard and soft navigation. Reuse existing loading interfaces, preserve behavior, and verify failure without the fix and success with it.
```

### Establish the complete loop

```
Discover this repository build and test rig, document its safeguards, optimize [ROUTES] individually, and provide linked evidence for baseline, differential, parity, and final tests.
```

## Limitations

- Requires Next.js 16.3 or newer with Cache Components enabled.
- Requires a production-like build because development mode cannot provide a valid result.
- Project-specific authentication, deployment, selectors, and test data still require discovery.
- URL-dependent routes may need targeted full prefetching with additional server cost.

## Best Practices

- Verify the testing API is enabled for measured builds and disabled for production.
- Choose a stable synchronous shell marker that is visible to the actual test account.
- Keep a differential result that fails without the fix and passes with it.

## Anti Patterns

- Do not measure instant navigation with development mode, custom timers, or retries.
- Do not place one coarse Suspense boundary around the entire route.
- Do not ship baseline scaffolding or duplicate existing loading interfaces.

## Security Audit

- Audited at: 2026-08-20T08:36:40.305\+00:00
- Summary: All 158 static alerts are false positives caused by Markdown formatting, fixed relative paths, non-secret deployment flags, and official documentation links. No prompt injection, secret collection, arbitrary process execution, path traversal, or data-exfiltration intent was found. The skill provides legitimate Next.js optimization guidance and explicitly keeps its testing API out of production.

## Stats

- Views: 1
- Downloads: 2
- Favorites: 0
- Popularity score: 0