Thinking Guides for Next.js Full-Stack Projects

Purpose: Systematic thinking guides to catch issues before they become bugs.

Core Philosophy: 30 minutes of thinking saves 3 hours of debugging.

Why Thinking Guides?

Most bugs and tech debt come from "didn't think of that", not from lack of skill:

Didn't think about what happens at layer boundaries -> cross-layer bugs
Didn't think about code patterns repeating -> duplicated code everywhere
Didn't think about edge cases -> runtime errors
Didn't think about future maintainers -> unreadable code

These guides help you ask the right questions before coding.

Available Thinking Guides

Guide	Purpose	When to Use
Cross-Layer Thinking	Think through data flow across layers	Before implementing features that span 3+ layers
Pre-Implementation Checklist	Verify readiness before coding	Before starting any feature implementation

Quick Reference: When to Use Which Guide

Cross-Layer Issues

Use Cross-Layer Thinking Guide when:

Feature touches 3+ layers (Server Component, Client Component, oRPC, Database)
Data format changes between layers
Multiple consumers need the same data
You're not sure where to put some logic
Integrates with external services or third-party APIs

Before Writing Code

Use Pre-Implementation Checklist when:

About to add a constant or config value
About to implement new logic
About to define a type or Zod schema
About to create a component or hook
About to add an oRPC procedure
Feels like you've seen similar code before

The Pre-Modification Rule (CRITICAL)

Before changing ANY value, ALWAYS search first!

# Search for the value you're about to change
rg "value_to_change" --type ts

# Check how many files define this value
rg "CONFIG_NAME" --type ts -c

This single habit prevents most "forgot to update X" bugs.

Next.js-Specific Layers

In Next.js full-stack projects with oRPC and Drizzle, these are the typical layers:

Server Components (RSC - data fetching, static rendering)
        |
        v
Client Components ('use client' - interactivity, React Query)
        |
        v
API Routes / oRPC Router (type-safe RPC, middleware, validation)
        |
        v
Service / Business Logic (shared utilities, domain rules)
        |
        v
Database Layer (Drizzle ORM, PostgreSQL, migrations)

Each boundary is a potential source of bugs due to:

Serialization - Only serializable data crosses the RSC/Client boundary (no functions, no Date objects, no Maps)
Type mismatches - Zod schemas on oRPC may not match what the frontend expects
Auth context - Session availability differs between Server Components, API routes, and middleware
Rendering mode - Server Components vs Client Components have different capabilities and constraints
Async timing - React Query caching, stale data, and race conditions

Core Principles

Search Before Write - Always search for existing patterns before creating new ones
Think Before Code - 5 minutes of checklist saves 50 minutes of debugging
Document Assumptions - Make implicit assumptions explicit
Verify All Layers - Changes often need updates in multiple places
Learn From Bugs - Add lessons to these guides after fixing non-trivial bugs

Contributing

Found a new "didn't think of that" moment? Add it:

If it's a general thinking pattern -> Add to existing guide or create new one
If it caused a bug -> Add to "Lessons Learned" section in the relevant guide
If it's project-specific -> Create a separate project-specific guide

Language: All documentation should be written in English.

4.2 KiB Raw Blame History