How do I install the Web Next Best Practices skill?

Run npx skillmds@latest add majiayu000/web-next-best-practices in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Web Next Best Practices safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Web Next Best Practices?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Web Next Best Practices free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Web Next Best Practices?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Web Next Best Practices by majiayu000

Name: Web Next Best Practices
Rating: 4.2 (5 reviews)
Author: majiayu000

Web Next Best Practices

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling. Use this skill when writing or reviewing Next.js code to ensure it follows established best practices for performance, maintainability, and correctness. Refer to the linked reference docs for detailed rules and examples in each area.

majiayu000 Updated Sep 9, 2026 567 repo stars

File contents

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

---name: web-next-best-practicesdescription: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling. Use this skill when writing or reviewing Next.js code to ensure it follows established best practices for performance, maintainability, and correctness. Refer to the linked reference docs for detailed rules and examples in each area.--- # Next.js Best Practices Apply these rules when writing or reviewing Next.js code. ## File Conventions See [file-conventions.md](./references/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](./references/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](./references/async-patterns.md) for: - Async `params` and `searchParams` - Async `cookies()` and `headers()` - Migration codemod ## Runtime Selection See [runtime-selection.md](./references/runtime-selection.md) for: - Default to Node.js runtime - When Edge runtime is appropriate ## Directives See [directives.md](./references/directives.md) for: - `'use client'`, `'use server'` (React) - `'use cache'` (Next.js) ## Functions See [functions.md](./references/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](./references/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](./references/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](./references/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](./references/metadata.md) for: - Static and dynamic metadata - `generateMetadata` function - OG image generation with `next/og` - File-based metadata conventions ## Image Optimization See [image.md](./references/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](./references/font.md) for: - `next/font` setup - Google Fonts, local fonts - Tailwind CSS integration - Preloading subsets ## Bundling See [bundling.md](./references/bundling.md) for: - Server-incompatible packages - CSS imports (not link tags) - Polyfills (already included) - ESM/CommonJS issues - Bundle analysis ## Scripts See [scripts.md](./references/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](./references/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](./references/suspense-boundaries.md) for: - CSR bailout with `useSearchParams` and `usePathname` - Which hooks require Suspense boundaries ## Parallel & Intercepting Routes See [parallel-routes.md](./references/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](./references/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](./references/debug-tricks.md) for: - MCP endpoint for AI-assisted debugging - Rebuild specific routes with `--debug-build-paths`

Frequently asked questions