Next Best Practices

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bund...

Security Scan

This is an instruction-only Next.js best-practices guide (no install, no credentials) and its required/declared surface matches the stated purpose; only developer-facing debug examples (local MCP endpoint, reading local font files) merit caution if the agent is permitted network or filesystem access.

Purpose & Capability

Name/description match the provided files: the repository is a collection of Next.js guidance (file conventions, RSC boundaries, routing, images/fonts, bundling, etc.). No unrelated environment variables, binaries, or install steps are requested. All files are documentation/examples consistent with a linter/guide style skill.

Instruction Scope

SKILL.md and the included files are human-oriented guidance and code samples for writing Next.js apps. Most instructions stay on-topic. One notable section (debug-tricks.md) documents using the local dev MCP endpoint (/_next/mcp) with curl and lists RPC tools that can reveal project paths, dev server URL, routes, errors, and log file locations. Those are legitimate developer debugging steps but — if an agent were given network access to localhost or filesystem access — they would allow it to query local dev servers and learn local paths and runtime data. The files also contain code samples that read local files (e.g., readFile for custom fonts) which are examples, not code the skill automatically runs.

Install Mechanism

No install specification and no code to write to disk — lowest-risk posture. This is instruction-only; the skill will not fetch or execute third‑party binaries during install.

Credentials

The skill declares no required environment variables, credentials, or config paths. However, the documentation includes examples that access local resources (dev server endpoints, local font files, .next logs). Those examples do not require you to provide secrets, but if the agent is allowed to make network requests to localhost or read files, it could obtain local project metadata and logs — so the requested surface remains proportionate to the stated purpose but operational permissions granted to the agent change the risk.

Persistence & Privilege

No 'always: true', no install-time writes, and nothing in the files attempts to modify other skills or global agent config. The skill is not requesting persistent privileges beyond normal agent invocation.

Assessment

This skill is a documentation-only Next.js best-practices bundle and is coherent with its description. It does not request credentials or install software. Two practical cautions: (1) the debug-tricks.md section shows how to call a local dev endpoint (/_next/mcp) which can return project paths, routes, logs and other development metadata — only allow the agent to make network requests to localhost if you trust it and its environment; (2) several examples show reading local files (fonts, assets) — those are sample snippets, but if you grant the agent filesystem access it could read files referenced by those examples. If you are concerned, keep the skill but restrict the agent's ability to access localhost/network or the host filesystem, or disable autonomous invocation for this skill. If you want, review any uses of the MCP endpoint and log/file paths in your environment before enabling agent network/file permissions.

Next.js Best Practices

Apply these rules when writing or reviewing Next.js code.

File Conventions

See file-conventions.md for:

• Project structure and special files
• Route segments (dynamic, catch-all, groups)
• Parallel and intercepting routes
• Middleware rename in v16 (middleware → proxy)

RSC Boundaries

Detect invalid React Server Component patterns.

See rsc-boundaries.md for:

• Async client component detection (invalid)
• Non-serializable props detection
• Server Action exceptions

Async Patterns

Next.js 15+ async API changes.

See async-patterns.md for:

• Async params and searchParams
• Async cookies() and headers()
• Migration codemod

Runtime Selection

See runtime-selection.md for:

• Default to Node.js runtime
• When Edge runtime is appropriate

Directives

See directives.md for:

• 'use client', 'use server' (React)
• 'use cache' (Next.js)

Functions

See functions.md for:

• Navigation hooks: useRouter, usePathname, useSearchParams, useParams
• Server functions: cookies, headers, draftMode, after
• Generate functions: generateStaticParams, generateMetadata

Error Handling

See error-handling.md for:

• error.tsx, global-error.tsx, not-found.tsx
• redirect, permanentRedirect, notFound
• forbidden, unauthorized (auth errors)
• unstable_rethrow for catch blocks

Data Patterns

See data-patterns.md for:

• Server Components vs Server Actions vs Route Handlers
• Avoiding data waterfalls (Promise.all, Suspense, preload)
• Client component data fetching

Route Handlers

See route-handlers.md for:

• route.ts basics
• GET handler conflicts with page.tsx
• Environment behavior (no React DOM)
• When to use vs Server Actions

Metadata & OG Images

See metadata.md for:

• Static and dynamic metadata
• generateMetadata function
• OG image generation with next/og
• File-based metadata conventions

Image Optimization

See image.md for:

• Always use next/image over <img>
• Remote images configuration
• Responsive sizes attribute
• Blur placeholders
• Priority loading for LCP

Font Optimization

See font.md for:

• next/font setup
• Google Fonts, local fonts
• Tailwind CSS integration
• Preloading subsets

Bundling

See bundling.md for:

• Server-incompatible packages
• CSS imports (not link tags)
• Polyfills (already included)
• ESM/CommonJS issues
• Bundle analysis

Scripts

See scripts.md for:

• next/script vs native script tags
• Inline scripts need id
• Loading strategies
• Google Analytics with @next/third-parties

Hydration Errors

See hydration-error.md for:

• Common causes (browser APIs, dates, invalid HTML)
• Debugging with error overlay
• Fixes for each cause

Suspense Boundaries

See suspense-boundaries.md for:

• CSR bailout with useSearchParams and usePathname
• Which hooks require Suspense boundaries

Parallel & Intercepting Routes

See parallel-routes.md for:

• Modal patterns with @slot and (.) interceptors
• default.tsx for fallbacks
• Closing modals correctly with router.back()

Self-Hosting

See self-hosting.md for:

• output: 'standalone' for Docker
• Cache handlers for multi-instance ISR
• What works vs needs extra setup

Debug Tricks

See debug-tricks.md for:

• MCP endpoint for AI-assisted debugging
• Rebuild specific routes with --debug-build-paths