Labsco
getsentry logo

next-best-practices

✓ Official★ 12

by sentry · part of getsentry/webvitals.com

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

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#analytics#ai-image#devops#git#monitoring
🧰 Not standalone. This skill ships with getsentry/webvitals.com and only works together with that tool — install the tool first, then add this skill.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

by sentry

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization,… npx skills add https://github.com/getsentry/webvitals.com --skill next-best-practices Download ZIPGitHub12

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