React & Next.js Best Practices
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
This guide outlines the performance optimization and architectural standards for React and Next.js applications within the project. It focuses on maximizing efficiency through prioritized rule categories, ranging from critical async waterfall elimination to incremental JavaScript performance improvements. These practices are designed to ensure scalable, predictable, and production-grade frontend development by leveraging modern features like Server Components, Suspense-first data fetching, and strict TypeScript discipline.
The primary objective is to provide a structured framework for developers to write high-performance code, optimize bundle sizes, and manage state effectively. The guidelines are maintained to facilitate both human development and automated refactoring by AI agents. Sources: bundled-skills/react-best-practices/SKILL.md:1-10, bundled-skills/frontend-dev-guidelines/SKILL.md:10-20
Core Architectural Doctrine
The project adheres to a set of non-negotiable architectural principles to maintain consistency and performance. These include a "Suspense-first" approach to data fetching and a strict separation of concerns using feature-based organization.
Component Design Principles
Components are categorized based on their responsibility and state management needs. Developers must prioritize Server Components for data fetching and only use Client Components when interactivity is required.
| Component Type | Purpose | State Management |
|---|---|---|
| Server | Default; Data fetching, static content, layouts | None |
| Client | Interactivity, event handlers, browser APIs | useState, useEffect |
| Presentational | UI display only | Props only |
| Container | Business logic and heavy state management | Heavy state |
Sources: bundled-skills/react-patterns/SKILL.md:10-20, bundled-skills/nextjs-best-practices/SKILL.md:10-25
Suspense and Data Fetching Flow
The application uses a Suspense-first model, where useSuspenseQuery is the primary hook for data fetching. This eliminates the need for manual isLoading conditionals within components.
The diagram shows the standard flow for data-dependent components using Suspense boundaries to handle loading states automatically.
Sources: bundled-skills/frontend-dev-guidelines/SKILL.md:45-55, bundled-skills/react-best-practices/SKILL.md:50-55
Performance Optimization Categories
The project prioritizes performance optimizations across eight categories. Each category is assigned an impact level to guide development focus.
| Priority | Category | Impact | Description |
|---|---|---|---|
| 1 | Eliminating Waterfalls | CRITICAL | Parallelizing independent async operations. |
| 2 | Bundle Size Optimization | CRITICAL | Reducing JS payload via dynamic imports and direct imports. |
| 3 | Server-Side Performance | HIGH | Using React cache and minimizing serialization. |
| 4 | Client-Side Fetching | MEDIUM-HIGH | Deduplicating requests with SWR or React Query. |
| 5 | Re-render Optimization | MEDIUM | Memoization and stable state updates. |
Sources: bundled-skills/react-best-practices/SKILL.md:25-45, bundled-skills/react-best-practices/metadata.json
Eliminating Waterfalls (Critical)
Waterfalls occur when asynchronous operations are awaited sequentially rather than in parallel.
- Parallel Fetching: Use
Promise.all()for independent data requirements. - Deferred Await: Move
awaitstatements into specific branches where the data is actually consumed to avoid blocking the entire component render. - Suspense Boundaries: Use boundaries to stream independent content sections as they become ready.
Sources: bundled-skills/react-best-practices/SKILL.md:50-60
Bundle Size Management
To minimize the initial JavaScript payload, the following rules apply:
- Avoid Barrel Files: Import directly from the source file to prevent unnecessary code execution and bundle bloat.
- Dynamic Imports: Use
next/dynamicfor heavy components that are not immediately visible (e.g., modals, complex editors). - Third-Party Deferral: Load analytics or logging scripts after hydration.
Sources: bundled-skills/react-best-practices/SKILL.md:65-75
State Management and Hooks
State should be kept as close to where it is used as possible. For shared state, the selection of the tool depends on the complexity and scope.
Selection logic for state placement and management libraries based on scope and complexity.
Sources: bundled-skills/react-patterns/SKILL.md:45-60
Hook Patterns
- Extraction: Logic should be extracted into custom hooks (starting with
use) if it is repeated or involves complex side effects (e.g.,useLocalStorage,useDebounce). - Functional SetState: Always use the functional form of
setStatewhen the new state depends on the previous state to ensure stability in callbacks. - Lazy Initialization: Pass a function to
useStatefor values that require expensive calculations.
Sources: bundled-skills/react-patterns/SKILL.md:30-40, bundled-skills/react-best-practices/SKILL.md:100-110
JavaScript Performance (Low-Medium Impact)
Micro-optimizations that collectively improve the execution speed of the application:
- Early Exit: Return early from functions to reduce nesting and cognitive load.
- Key Lookups: Use
MaporSetfor O(1) repeated lookups instead of array iterations. - Hoisting: Extract
RegExpcreation and static JSX outside of component render functions to avoid re-allocation. - Batch DOM Changes: Group CSS changes using classes or
cssTextto minimize reflows.
Sources: bundled-skills/react-best-practices/SKILL.md:125-145, bundled-skills/frontend-dev-guidelines/SKILL.md:140-150
Conclusion
Adhering to these React and Next.js best practices ensures the delivery of high-performance web applications. By prioritizing the elimination of async waterfalls and bundle size bloat, while maintaining strict architectural boundaries using Server Components and Suspense, the codebase remains scalable and maintainable. Developers should treat these guidelines as the baseline for all frontend contributions. Sources: bundled-skills/react-best-practices/SKILL.md:15-20, bundled-skills/frontend-dev-guidelines/SKILL.md:180-190