⚛️ React + Next.js Engineering Handbook

The deepest open-source React & Next.js engineering resource on GitHub.
Built for engineers who want to understand how and why, not just what.

🧭 What This Handbook Is

This is not a tutorial.
This is not a "getting started" guide.
This is not surface-level documentation.

This is a deep engineering handbook — 125 documents across 27 parts, built around:

🔬 React internals and runtime behavior (Fiber, reconciliation, concurrent rendering)
⚙️ Next.js architecture (App Router, RSC, streaming, four-layer caching)
🧠 How browsers actually render your UI
🚀 Production performance engineering (profiling, memoization, virtualization)
🏗️ Scalable frontend architecture (monorepo, micro-frontends, design systems)
🔒 Security engineering (XSS/CSP, CSRF, supply chain, security headers)
🔍 Real-world debugging workflows (React DevTools, Node.js inspector, memory leaks)
📐 Anti-patterns, testing, and 6 production-grade real-world projects

If you have ever asked:

"Why does my component re-render so often?"
"What actually happens after I call setState?"
"How does Next.js generate HTML on the server?"
"What is React Fiber and why does it matter?"
"How does hydration work and why does it break?"
"What are Next.js's four caching layers and how do they interact?"
"How do I scale a React app to 10 million users?"

...then this handbook was written for you.

🎯 Who This Is For

Audience	What You Will Get
Intermediate frontend developers	Deep understanding of React internals beyond docs
Senior React engineers	Architecture patterns, scaling strategies, performance systems
Next.js engineers	Full App Router internals, RSC, streaming, caching
Self-taught developers	Structured university-level progression
Senior/Staff interview candidates	Every deep-dive topic interviewers actually ask
Production engineers	Real-world debugging, profiling, architecture decisions

📚 Table of Contents

Part I — React Core Internals

Part II — React Rendering Internals

Part III — React Fiber Architecture

Part IV — Reconciliation

Part V — Hooks Internals

Part VI — Re-rendering System

Part VII — Concurrent React

Part VIII — React Compiler

Part IX — Next.js Core

Part X — React Server Components

Part XI — Next.js Rendering Systems

Part XII — Next.js Caching Systems

Part XIII — Next.js Advanced Internals

Covered in Part IX docs 45–47 above (Turbopack, Server Actions, Parallel Routes)

Part XIV — Browser Rendering Internals

67 · Browser Rendering Pipeline

Part XV — Performance Engineering

Part XVI — State Management Deep Dive

Part XVII — Build Systems

Part XVIII — Networking Engineering

Part XIX — Architecture Patterns

Part XX — Design Systems

Part XXI — Security

Part XXII — Testing

Part XXIII — Debugging

Part XXIV — Anti-Patterns

Part XXV — Interview Preparation

Part XXVI — Real-World Projects

Part XXVII — Roadmap & Exercises

Learning Roadmap, Synthesis Exercises & What to Build Next

🗺️ Architecture Overview

graph TD
    A[Your React Code] --> B[React Runtime]
    B --> C[Fiber Reconciler]
    C --> D{Render Phase\npure computation}
    D --> E[Build Work-in-Progress Tree]
    E --> F[Reconcile: Diff Trees]
    F --> G{Commit Phase\nuninterruptible}
    G --> H[DOM Mutations]
    G --> I[useLayoutEffect]
    G --> J[useEffect async]
    H --> K[Browser]
    K --> L[Style Recalculation]
    L --> M[Layout]
    M --> N[Paint]
    N --> O[Composite → Screen]

    style A fill:#61dafb,color:#000
    style B fill:#764abc,color:#fff
    style C fill:#764abc,color:#fff
    style D fill:#27ae60,color:#fff
    style G fill:#e8491d,color:#fff
    style O fill:#27ae60,color:#fff

⚡ Quick Navigation by Problem

"My component re-renders too often"
→ What Causes Re-renders → Memoization Engineering → Performance Anti-Patterns

"My Next.js page shows stale data"
→ Cache Invalidation Strategies → Debugging Next.js → Data Cache

"I don't understand hydration errors"
→ Hydration Strategies → Debugging React → Debugging Next.js

"I need to choose a rendering strategy"
→ Rendering Strategies Comparison → Next.js Caching Systems → P1 E-Commerce ADRs

"My application is slow"
→ Performance Debugging → React Profiler → Bundle Optimization

"I need to architect a large React application"
→ Feature-Based Architecture → State Management Deep Dive → Monorepo Engineering

"Preparing for a senior React interview"
→ React Internals Questions → Next.js Questions → Frontend System Design

"I want to understand Next.js App Router deeply"
→ App Router Architecture → React Server Components → Next.js Caching Systems

📐 How to Use This Handbook

Path 1: The Systematic Engineer

Read every part in order. Build deep, interconnected mental models. Takes 3–6 months at a comfortable pace. Start at Part I and follow the numbering. Use the Learning Roadmap for structured weekly plans.

Path 2: The Problem Solver

Jump to the section that solves your current engineering challenge. Use the Quick Navigation above. Cross-references within each document point you to related concepts.

Path 3: The Interview Candidate

Focus on Parts I–VIII (React internals), Parts IX–XII (Next.js core + caching), Part XV (performance), and Part XXV (interview prep). The system design section has worked examples at the depth expected at senior/staff level.

Path 4: The Architect

Focus on Part IX (Next.js), Part XVI (state management), Part XIX (architecture patterns), Part XXI (security), and Part XXVI (real-world projects). The ADRs in each project document are the most valuable architectural learning artifacts.

Path 5: The New Engineer

Start with the Learning Roadmap which has structured tracks by experience level (Junior → Mid, Mid → Senior, Senior → Staff) with weekly plans and capstone exercises.

🚦 Reading Conventions

Throughout this handbook you will see these markers:

🔬 Internals — Explains how something works inside React/Next.js source code

⚠️ Anti-Pattern — A dangerous or inefficient pattern to avoid

✅ Good Practice — A recommended, production-safe pattern

🧪 Exercise — A hands-on challenge to solidify understanding

📊 Profiling — A performance measurement example

🏭 Production Note — An insight from real production systems

💡 Mental Model — A conceptual framework to simplify understanding

🧱 Repository Structure

react-nextjs-engineering-handbook/
├── README.md                          ← You are here
├── CONTRIBUTING.md
└── docs/
    ├── react-core/                    ← Parts I: What React is
    ├── react-rendering/               ← Parts II & VI: Render/commit phases, re-rendering
    ├── react-fiber/                   ← Part III: Fiber architecture internals
    ├── reconciliation/                ← Part IV: Diffing, keys, DOM reuse
    ├── hooks-internals/               ← Part V: Every hook, deeply explained
    ├── concurrent-react/              ← Part VII: Transitions, Suspense, scheduling
    ├── react-compiler/                ← Part VIII: Compiler & future React
    ├── nextjs-core/                   ← Parts IX & XIII: App Router, middleware, Server Actions
    ├── server-components/             ← Part X: RSC, server/client boundary, streaming
    ├── nextjs-rendering/              ← Part XI: Hydration, SSG/SSR/ISR/CSR, Edge rendering
    ├── caching/                       ← Part XII: All 4 Next.js cache layers
    ├── browser-internals/             ← Part XIV: Browser rendering pipeline
    ├── performance/                   ← Part XV: Profiling, memoization, virtualization
    ├── state-management/              ← Part XVI: Context, Redux, Zustand, TanStack Query
    ├── build-systems/                 ← Part XVII: Webpack, Vite, SWC, Turbopack
    ├── networking/                    ← Part XVIII: HTTP, streaming, WebSocket, BFF
    ├── architecture/                  ← Part XIX: Feature arch, monorepo, micro-frontends
    ├── design-systems/                ← Part XX: Tokens, component API, accessibility
    ├── security/                      ← Part XXI: XSS/CSP, CSRF, dependency, headers
    ├── testing/                       ← Part XXII: Unit, integration, E2E, performance
    ├── debugging/                     ← Part XXIII: React, Next.js, error boundaries, perf
    ├── anti-patterns/                 ← Part XXIV: Common, state, performance anti-patterns
    ├── interview-prep/                ← Part XXV: React, Next.js, system design, behavioral
    ├── real-world-projects/           ← Part XXVI: 6 production project breakdowns
    └── roadmap/                       ← Part XXVII: Learning roadmap & synthesis exercises

125 documents · 27 parts · MIT License

🤝 Contributing

This handbook grows through community engineering expertise.
See CONTRIBUTING.md for guidelines.

All contributions must meet the quality bar:

Deep technical accuracy (explain why, not just what)
Mental model section in every document
Good/bad practice examples with explanation
Common misconceptions addressed
Cross-references to related handbook sections

📜 License

MIT — Free to use, share, and build upon.
If this helped you, please ⭐ the repository.

✍️ Acknowledgments

Built for engineers by engineers.
Inspired by the complexity of real production systems.
Committed to the belief that understanding internals makes better engineers.

Start here → What React Actually Is

or jump to your level →

Learning Roadmap & Exercises

Name		Name	Last commit message	Last commit date
anti-patterns		anti-patterns
architecture		architecture
build-systems		build-systems
caching		caching
concurrent-react		concurrent-react
debugging		debugging
design-systems		design-systems
hook-internals		hook-internals
interview-prep		interview-prep
networking		networking
nextjs-core		nextjs-core
nextjs-rendering		nextjs-rendering
performance		performance
react-compiler		react-compiler
react-core		react-core
react-fiber		react-fiber
react-rendering		react-rendering
real-world-projects		real-world-projects
reconciliation		reconciliation
roadmap		roadmap
security		security
server-component		server-component
state-management		state-management
testing		testing
CONTRIBUTING.md		CONTRIBUTING.md
README.MD		README.MD

Latest commit

History

Folders and files

Repository files navigation