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
- 所属仓库
- compozy/compozy
- 最近更新
- 2026-11-15
- Stars
- ★ 2.9k
- Forks
- 187
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
security-review
Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security", "OWASP review", or review code for injection, XSS, authentication, authorization, cryptography issues. Provides systematic review with confidence-based reporting.
lesson-learned
Extract evidence-backed engineering lessons from recent changes or incidents. Use for requested reflection, lesson updates, or retiring an obsolete workflow rule.
compozy
Operate CompozyOS. Use when working with CompozyOS sessions, agents, native tools, skills, tasks, Loops, Goals, Terminal, desktops and windows, automation, extensions, or configuration. Don't use for unrelated projects.
remotion-upgrade
Upgrade Remotion, and related packages
remotion-studio
Preview a Remotion video
remotion-saas
Build an app with Remotion