next-best-practices
Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
- License 许可
- MIT
- 最近更新
- 2026-07-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- next-best-practices
- description
- Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
- user-invocable
- false
02 资源文件 19
- 参考文档async-patterns.md1.6 KB
- 参考文档bundling.md4.4 KB
- 参考文档data-patterns.md6.5 KB
- 参考文档debug-tricks.md2.9 KB
- 参考文档directives.md1.4 KB
- 参考文档error-handling.md4.6 KB
- 参考文档file-conventions.md3.4 KB
- 参考文档font.md5.1 KB
- 参考文档functions.md4.3 KB
- 参考文档hydration-error.md1.8 KB
- 参考文档image.md3.8 KB
- 参考文档metadata.md7.0 KB
- 参考文档parallel-routes.md7.0 KB
- 参考文档route-handlers.md3.2 KB
- 参考文档rsc-boundaries.md4.2 KB
- 参考文档runtime-selection.md985 B
- 参考文档scripts.md3.2 KB
- 参考文档self-hosting.md8.1 KB
- 参考文档suspense-boundaries.md1.3 KB
03 SKILL.md 正文
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
paramsandsearchParams - Async
cookies()andheaders() - 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.tsxredirect,permanentRedirect,notFoundforbidden,unauthorized(auth errors)unstable_rethrowfor 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.tsbasics- 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
generateMetadatafunction- OG image generation with
next/og - File-based metadata conventions
Image Optimization
See image.md for:
- Always use
next/imageover<img> - Remote images configuration
- Responsive
sizesattribute - Blur placeholders
- Priority loading for LCP
Font Optimization
See font.md for:
next/fontsetup- 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/scriptvs 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
useSearchParamsandusePathname - Which hooks require Suspense boundaries
Parallel & Intercepting Routes
See parallel-routes.md for:
- Modal patterns with
@slotand(.)interceptors default.tsxfor 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
04 同仓库更多 Skills
to-prompt-opus
Use when preparing or rewriting prompts for Claude Opus 4.8, Anthropic API agents, XML-structured prompts, long-context document work, coding agents, research synthesis, frontend/design tasks, or model-specific prompt optimization. Do not use for GPT/OpenAI prompts or raw context packaging without Opus-specific tuning.
to-prompt-gpt
Use when preparing or rewriting prompts for GPT-5.5, OpenAI API agents, Responses workflows, coding agents, research synthesis, support assistants, or model-specific prompt optimization. Do not use for Claude/Opus prompts or raw context packaging without GPT-specific tuning.
plan-refactor-qa
Plans and runs qa-report before executing Compozy refactor tasks. Use when the user provides a refactor or issue slug and wants Codex to inspect the matching .compozy/tasks directory, related PRD/TechSpec/ADR/task artifacts, affected code, and existing tests, then invoke $qa-report with a repository-grounded prompt. Do not use to run tests, execute qa-execution, implement code, or perform post-refactor verification.
multi-tool-branch-review
Orchestrates a multi-tool branch review of the current git branch against a base branch. By default it runs two independent thermo-nuclear maintainability audits, one on Codex GPT-5.5 xhigh and one on Claude Opus xhigh, then consolidates the findings into a single remediation plan via writing-plans. If the user explicitly asks for native reviews, it can add the Claude native review pass, the Codex native review pass, or both. Use when the user wants a deep cross-model review of a branch or PR before merge, or asks to review this branch with multiple tools or models. Encodes known infra failure modes and their fixes (missing Claude ACP adapter, Codex MCP auth hangs, false-positive report files, long jobs orphaned inside subagents). Do not use for reviewing a single uncommitted snippet, for non-git work, for running only one reviewer, or when the user only wants a quick lint or test run.
create-pr-with-template
Create a GitHub Pull Request with gh CLI and prefer repository PR templates automatically. Use this whenever the user asks to open/create a PR, especially when template compliance is needed. If multiple templates exist, ask the user which template to use.
ui-craft
Provides guardrails for user-facing UI work: usability heuristics, accessibility floors, design-system discipline, component states, microcopy, motion, dark mode, responsive behavior, and human-AI UX. Use when designing, generating, reviewing, or refactoring visible product surfaces such as components, pages, dashboards, forms, dialogs, loading/empty/error states, or AI interfaces. Do not use for backend-only work, infrastructure, CLI/TUI design, or pure documentation editing.