nextjs-knowledge-patch_skill

Overview

This skill provides an up-to-date reference for Next.js App Router changes (v15.3 → 16.x) and practical guidance when writing modern Next.js code. It focuses on new conventions like proxy.ts, the opt-in cache model ("use cache"), navigation hooks, typed routes, and breaking changes that affect migration and daily development. Use it to avoid runtime errors and to adopt new caching, routing, and tooling patterns safely.

How this skill works

The skill explains what to change and why: replace middleware.ts with proxy.ts for Node.js request interception, apply the "use cache" directive to opt-in to component/function caching, and use the new caching APIs (updateTag, refresh, revalidateTag) with their updated signatures. It also covers navigation primitives (onNavigate, useLinkStatus), auto-generated PageProps types, typedRoutes configuration, and important breaking changes introduced in 16.0. Practical examples and quick-reference rules are included for each area.

When to use it

• When migrating a codebase from Next.js 15.x to 16.x or starting a new 16.x project
• When implementing request interception or replacing middleware with proxy.ts
• When you need predictable server-side caching or Partial Prerendering (use cache)
• When enabling typed route validation and CI type generation (typedRoutes / next typegen)
• When adopting navigation UX improvements like onNavigate and useLinkStatus

Best practices

• Rename middleware.ts to proxy.ts and export a proxy(request) function for Node runtime interception
• Opt into caching explicitly: set cacheComponents: true and add "use cache" to server components or functions
• Use updateTag() inside Server Actions for immediate read-your-writes workflows and revalidateTag(tag, profile) with a cacheLife profile for eventual invalidation
• Prefer typedRoutes in next.config for compile-time href validation and run next typegen in CI
• Ensure async access for params/searchParams/cookies/headers (await usage) and add default.js files for all parallel route slots

Example use cases

• Protect navigations when there are unsaved changes by using <Link onNavigate> and calling e.preventDefault()
• Create a cached server component with "use cache" to serve static shells and dynamic holes via Suspense
• Invalidate search results by calling revalidateTag('search-results', 'hours') after indexing updates
• Run next typegen in CI to catch invalid route hrefs before merging
• Move analytics/micro-ops to instrumentation-client to run before app code