Next Best Practices

Next.js Best Practices

Use the project's installed Next.js version as the source of truth. This skill is baselined against the latest stable documentation for Next.js 16.3.3, but project-local, version-matched docs take precedence.

Start With the Project's Mode

Before proposing code:

1. Read package.json, the lockfile, next.config.*, and the relevant app/ or pages/ files.
2. If present, follow the Next.js-managed block in the repository's AGENTS.md and read the matching docs in node_modules/next/dist/docs/.
3. Confirm whether cacheComponents and partialPrefetching are enabled. They materially change caching, prerendering, and <Link> behavior.
4. Preserve the existing router. Do not migrate from Pages Router to App Router unless the task requests it.
5. Treat canary and experimental.* features as opt-in. Do not enable them merely because they exist in the latest docs.

For version detection, bundled docs, Turbopack defaults, and the stable-versus-experimental boundary in 16.3, read version-and-tooling.

Cache Components Mode Gate

Read cache-components before changing caching mode and core-navigation before changing prefetch behavior.

Current Decision Rules

• Prefer Server Components. Add 'use client' only at the smallest boundary that needs state, effects, event handlers, or browser APIs.
• Keep secrets and privileged data access in server-only modules. Server Actions are reachable POST entry points: authenticate, authorize, and validate inside every action.
• Await params, searchParams, cookies(), and headers() in Server Components. In Client Components, unwrap promise props with React use() where appropriate.
• Use useActionState for action results and pending state, and useOptimistic for reversible optimistic UI.
• Use updateTag in a Server Action for read-your-own-writes. Use revalidateTag(tag, 'max') for stale-while-revalidate.
• In 16.3, prefer retry() in error.tsx; use stable catchError from next/error for component-level boundaries. Use reset() only when re-fetching Server Component output is intentionally unnecessary.
• Use next/root-params only for parameters above a root layout and only from Server Components. Continue using the async params prop for ordinary dynamic segments.
• Do not tune defaults without evidence. Next.js 16.3 already enables small prefetch-response inlining, Turbopack build caching, dev caching, and memory eviction.

References

Read only the references relevant to the task.

Verification

Use the project's package manager and existing scripts. In proportion to the change:

1. Run the narrow test or type check first.
2. Read next dev or next build diagnostics; Cache Components errors offer distinct stream, cache, or block fixes with different trade-offs.
3. Exercise the affected route in a real browser. Verify loading, error, navigation, and mutation states, not only compilation.
4. For instant-navigation work, validate the intended click-time UI in development and add an instant() Playwright regression test when the project already uses the 16.3 tooling.

Do not report a navigation as instant from code inspection alone: prefetching is disabled in development and the production loading shell must be inspected or tested explicitly.