nextjs-architect

Next.js App Router Architecture

Help users make sound architectural decisions in Next.js App Router projects using Tailwind CSS for styling.

Server vs Client Components

The most important architectural decision in modern Next.js is understanding the server/client boundary.

Default to Server Components

Every component is a Server Component unless it opts in with "use client". Keep components on the server when they:

• Fetch data (database queries, API calls)
• Access backend resources directly
• Keep sensitive logic (tokens, API keys) off the client
• Render large dependencies that don't need interactivity

Use Client Components when you need

• Event handlers (onClick, onChange, onSubmit)
• State (useState, useReducer)
• Effects (useEffect, useLayoutEffect)
• Browser APIs (window, document, localStorage)
• Custom hooks that depend on state or effects

The boundary pattern

Push "use client" as far down the tree as possible. Instead of making an entire page a client component because one button needs state, extract just the interactive part:

app/
  dashboard/
    page.tsx          ← Server Component (fetches data)
    components/
      stats-grid.tsx  ← Server Component (renders data)
      filter-bar.tsx  ← Client Component (has state)

Example — composing server and client:

// app/dashboard/page.tsx (Server Component)
import { FilterBar } from './components/filter-bar'
import { StatsGrid } from './components/stats-grid'

export default async function DashboardPage() {
  const stats = await getStats()
  return (
    <div className="p-6">
      <FilterBar />
      <StatsGrid data={stats} />
    </div>
  )
}

// app/dashboard/components/filter-bar.tsx
"use client"
import { useState } from 'react'

export function FilterBar() {
  const [filter, setFilter] = useState('all')
  return (
    <div className="flex gap-2 mb-4">
      {['all', 'active', 'archived'].map(f => (
        <button
          key={f}
          onClick={() => setFilter(f)}
          className={`px-3 py-1 rounded ${filter === f ? 'bg-blue-600 text-white' : 'bg-gray-100'}`}
        >
          {f}
        </button>
      ))}
    </div>
  )
}