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