vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
- License 许可
- MIT
- 最近更新
- 2026-09-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- license
- MIT
- metadata
- { "author": "vercel", "version": "1.0.0" }
- description
- React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
02 资源文件 74
- 参考文档AGENTS.md105.7 KB
- 参考文档README.md3.3 KB
- 参考文档rules/_sections.md1.5 KB
- 参考文档rules/_template.md631 B
- 参考文档rules/advanced-effect-event-deps.md1.8 KB
- 参考文档rules/advanced-event-handler-refs.md1.4 KB
- 参考文档rules/advanced-init-once.md958 B
- 参考文档rules/advanced-use-latest.md1.0 KB
- 参考文档rules/async-api-routes.md1.1 KB
- 参考文档rules/async-cheap-condition-before-await.md1.2 KB
- 参考文档rules/async-defer-await.md2.2 KB
- 参考文档rules/async-dependencies.md1.3 KB
- 参考文档rules/async-parallel.md654 B
- 参考文档rules/async-suspense-boundaries.md2.5 KB
- 参考文档rules/bundle-analyzable-paths.md2.3 KB
- 参考文档rules/bundle-barrel-imports.md2.7 KB
- 参考文档rules/bundle-conditional.md949 B
- 参考文档rules/bundle-defer-third-party.md920 B
- 参考文档rules/bundle-dynamic-imports.md791 B
- 参考文档rules/bundle-preload.md1.1 KB
- 参考文档rules/client-event-listeners.md1.9 KB
- 参考文档rules/client-localstorage-schema.md1.9 KB
- 参考文档rules/client-passive-event-listeners.md1.6 KB
- 参考文档rules/client-swr-dedup.md1.1 KB
- 参考文档rules/js-batch-dom-css.md3.2 KB
- 参考文档rules/js-cache-function-results.md1.9 KB
- 参考文档rules/js-cache-property-access.md532 B
- 参考文档rules/js-cache-storage.md1.6 KB
- 参考文档rules/js-combine-iterations.md753 B
- 参考文档rules/js-early-exit.md1.1 KB
- 参考文档rules/js-flatmap-filter.md1.4 KB
- 参考文档rules/js-hoist-regexp.md1.0 KB
- 参考文档rules/js-index-maps.md837 B
- 参考文档rules/js-length-check-first.md1.7 KB
- 参考文档rules/js-min-max-loop.md2.2 KB
- 参考文档rules/js-request-idle-callback.md2.6 KB
- 参考文档rules/js-set-map-lookups.md532 B
- 参考文档rules/js-tosorted-immutable.md1.7 KB
- 参考文档rules/rendering-activity.md564 B
- 参考文档rules/rendering-animate-svg-wrapper.md1.2 KB
- 参考文档rules/rendering-conditional-render.md980 B
- 参考文档rules/rendering-content-visibility.md815 B
- 参考文档rules/rendering-hoist-jsx.md1.0 KB
- 参考文档rules/rendering-hydration-no-flicker.md2.3 KB
- 参考文档rules/rendering-hydration-suppress-warning.md872 B
- 参考文档rules/rendering-resource-hints.md2.5 KB
- 参考文档rules/rendering-script-defer-async.md1.8 KB
- 参考文档rules/rendering-svg-precision.md588 B
- 参考文档rules/rendering-usetransition-loading.md2.0 KB
- 参考文档rules/rerender-defer-reads.md973 B
- 参考文档rules/rerender-dependencies.md824 B
- 参考文档rules/rerender-derived-state-no-effect.md1.2 KB
- 参考文档rules/rerender-derived-state.md728 B
- 参考文档rules/rerender-functional-setstate.md2.9 KB
- 参考文档rules/rerender-lazy-state-init.md2.0 KB
- 参考文档rules/rerender-memo-with-default-value.md1.1 KB
- 参考文档rules/rerender-memo.md1.1 KB
- 参考文档rules/rerender-move-effect-to-event.md1.2 KB
- 参考文档rules/rerender-no-inline-components.md2.1 KB
- 参考文档rules/rerender-simple-expression-in-memo.md1018 B
- 参考文档rules/rerender-split-combined-hooks.md1.8 KB
- 参考文档rules/rerender-transitions.md1.0 KB
- 参考文档rules/rerender-use-deferred-value.md1.8 KB
- 参考文档rules/rerender-use-ref-transient-values.md1.7 KB
- 参考文档rules/server-after-nonblocking.md2.0 KB
- 参考文档rules/server-auth-actions.md2.6 KB
- 参考文档rules/server-cache-lru.md1.3 KB
- 参考文档rules/server-cache-react.md2.2 KB
- 参考文档rules/server-dedup-props.md2.0 KB
- 参考文档rules/server-hoist-static-io.md4.3 KB
- 参考文档rules/server-no-shared-module-state.md1.7 KB
- 参考文档rules/server-parallel-fetching.md1.5 KB
- 参考文档rules/server-parallel-nested-fetching.md992 B
- 参考文档rules/server-serialization.md996 B
03 SKILL.md 正文
Vercel React Best Practices
Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Reviewing code for performance issues
- Refactoring existing React/Next.js code
- Optimizing bundle size or load times
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Eliminating Waterfalls | CRITICAL | async- |
| 2 | Bundle Size Optimization | CRITICAL | bundle- |
| 3 | Server-Side Performance | HIGH | server- |
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | client- |
| 5 | Re-render Optimization | MEDIUM | rerender- |
| 6 | Rendering Performance | MEDIUM | rendering- |
| 7 | JavaScript Performance | LOW-MEDIUM | js- |
| 8 | Advanced Patterns | LOW | advanced- |
Quick Reference
1. Eliminating Waterfalls (CRITICAL)
async-cheap-condition-before-await- Check cheap sync conditions before awaiting flags or remote valuesasync-defer-await- Move await into branches where actually usedasync-parallel- Use Promise.all() for independent operationsasync-dependencies- Use better-all for partial dependenciesasync-api-routes- Start promises early, await late in API routesasync-suspense-boundaries- Use Suspense to stream content
2. Bundle Size Optimization (CRITICAL)
bundle-barrel-imports- Import directly, avoid barrel filesbundle-analyzable-paths- Prefer statically analyzable import and file-system paths to avoid broad bundles and tracesbundle-dynamic-imports- Use next/dynamic for heavy componentsbundle-defer-third-party- Load analytics/logging after hydrationbundle-conditional- Load modules only when feature is activatedbundle-preload- Preload on hover/focus for perceived speed
3. Server-Side Performance (HIGH)
server-auth-actions- Authenticate server actions like API routesserver-cache-react- Use React.cache() for per-request deduplicationserver-cache-lru- Use LRU cache for cross-request cachingserver-dedup-props- Avoid duplicate serialization in RSC propsserver-hoist-static-io- Hoist static I/O (fonts, logos) to module levelserver-no-shared-module-state- Avoid module-level mutable request state in RSC/SSRserver-serialization- Minimize data passed to client componentsserver-parallel-fetching- Restructure components to parallelize fetchesserver-parallel-nested-fetching- Chain nested fetches per item in Promise.allserver-after-nonblocking- Use after() for non-blocking operations
4. Client-Side Data Fetching (MEDIUM-HIGH)
client-swr-dedup- Use SWR for automatic request deduplicationclient-event-listeners- Deduplicate global event listenersclient-passive-event-listeners- Use passive listeners for scrollclient-localstorage-schema- Version and minimize localStorage data
5. Re-render Optimization (MEDIUM)
rerender-defer-reads- Don't subscribe to state only used in callbacksrerender-memo- Extract expensive work into memoized componentsrerender-memo-with-default-value- Hoist default non-primitive propsrerender-dependencies- Use primitive dependencies in effectsrerender-derived-state- Subscribe to derived booleans, not raw valuesrerender-derived-state-no-effect- Derive state during render, not effectsrerender-functional-setstate- Use functional setState for stable callbacksrerender-lazy-state-init- Pass function to useState for expensive valuesrerender-simple-expression-in-memo- Avoid memo for simple primitivesrerender-split-combined-hooks- Split hooks with independent dependenciesrerender-move-effect-to-event- Put interaction logic in event handlersrerender-transitions- Use startTransition for non-urgent updatesrerender-use-deferred-value- Defer expensive renders to keep input responsivererender-use-ref-transient-values- Use refs for transient frequent valuesrerender-no-inline-components- Don't define components inside components
6. Rendering Performance (MEDIUM)
rendering-animate-svg-wrapper- Animate div wrapper, not SVG elementrendering-content-visibility- Use content-visibility for long listsrendering-hoist-jsx- Extract static JSX outside componentsrendering-svg-precision- Reduce SVG coordinate precisionrendering-hydration-no-flicker- Use inline script for client-only datarendering-hydration-suppress-warning- Suppress expected mismatchesrendering-activity- Use Activity component for show/hiderendering-conditional-render- Use ternary, not && for conditionalsrendering-usetransition-loading- Prefer useTransition for loading staterendering-resource-hints- Use React DOM resource hints for preloadingrendering-script-defer-async- Use defer or async on script tags
7. JavaScript Performance (LOW-MEDIUM)
js-batch-dom-css- Group CSS changes via classes or cssTextjs-index-maps- Build Map for repeated lookupsjs-cache-property-access- Cache object properties in loopsjs-cache-function-results- Cache function results in module-level Mapjs-cache-storage- Cache localStorage/sessionStorage readsjs-combine-iterations- Combine multiple filter/map into one loopjs-length-check-first- Check array length before expensive comparisonjs-early-exit- Return early from functionsjs-hoist-regexp- Hoist RegExp creation outside loopsjs-min-max-loop- Use loop for min/max instead of sortjs-set-map-lookups- Use Set/Map for O(1) lookupsjs-tosorted-immutable- Use toSorted() for immutabilityjs-flatmap-filter- Use flatMap to map and filter in one passjs-request-idle-callback- Defer non-critical work to browser idle time
8. Advanced Patterns (LOW)
advanced-effect-event-deps- Don't putuseEffectEventresults in effect depsadvanced-event-handler-refs- Store event handlers in refsadvanced-init-once- Initialize app once per app loadadvanced-use-latest- useLatest for stable callback refs
How to Use
Read individual rule files for detailed explanations and code examples:
rules/async-parallel.md
rules/bundle-barrel-imports.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
04 同仓库更多 Skills
runpodctl
Runpod CLI for managing GPU/CPU workloads from the terminal — pods, serverless endpoints, templates, network volumes, Hub deploys, models, SSH, and file transfer (send/receive). Use for terminal/CI/scripting, Hub browse/deploy, SSH setup, `doctor`, or when the Runpod MCP tools are not connected. For structured tool calls in an MCP-enabled session, prefer runpod-mcp.
runpod
Start here for any Runpod task — running GPU/CPU pods, deploying serverless endpoints, templates, network volumes, building images, or understanding how Runpod works. Routes to the right skill (runpod-mcp, runpodctl, flash, companion-clis, runpod-usage, runpod-templates, runpod-migrate) and indexes two dozen live-verified end-to-end examples (golden paths) — use it when the lane is unclear, and for any multi-step or provisioning task even when it is not.
runpod-usage
How Runpod works and how to work it — pods vs serverless, GPU/VRAM selection, storage, building a container, networking, plus the agentic pod development loop (provision → ssh-exec → set up → poll readiness) and on-pod install hygiene (uv/apt). Use to answer "how does X work", "which GPU", "how do I build a container", or "how do I stand up a workload on a pod". Guidance, not a tool — execute with runpodctl, runpod-mcp, or flash.
runpod-templates
Runpod's official prebuilt pod templates (ComfyUI, PyTorch, and others): what each image ships, which ports and paths it uses, how to pick one, how to pin a version, and what is missing on first boot. Use when a task says "run <X> on a pod" and an official template already covers it, instead of building an image — and when a user needs help with or wants to fix something about a Runpod template they are already running (won't boot, can't reach the UI, missing models, wrong CUDA line, broken ComfyUI workflow metadata on imported workflows): start here and route onward. Deploy with runpodctl or runpod-mcp; end-to-end walkthroughs live in the runpod router's golden paths.
runpod-migrate
Migrate a codebase from the Runpod GraphQL API or REST v1 to REST v2 — inventory which parts use which API version, rewrite the call sites, flag breaking changes, and verify. Use when someone asks to move to v2, asks what v2 would change, or asks which Runpod API their code is on. For managing infrastructure rather than migrating code, use runpod-mcp or runpodctl.
runpod-mcp
Manage Runpod infrastructure — pods, serverless endpoints, jobs, templates, network volumes, container-registry auth, GPU/CPU catalog, and billing — via the Runpod MCP server's structured tool calls. Use when the Runpod MCP tools (create-pod, list-endpoints, …) are connected in this session, or to connect them (hosted OAuth or local npx). Prefer this over runpodctl for plain infra CRUD when MCP is available; use runpodctl for the terminal, file transfer, or SSH setup.