The Senior Playbook: Architecture, Patterns & Caching

// 1. THE TRUNK (Server Component)
// app/product/[id]/page.tsx
import db from '@/lib/db';
import { ProductDescription } from './components/ProductDescription'; // Server Comp (Markdown)
import { ReviewsList } from './components/ReviewsList'; // Server Comp (DB Data)
import { AddToCart } from './components/AddToCart'; // 🍃 LEAF (Client)
import { ImageGallery } from './components/ImageGallery'; // 🍃 LEAF (Client)

export default async function ProductPage({
  params,
}: {
  params: { id: string };
}) {
  // Fetch logic stays on the server
  const product = await db.product.findUnique({ where: { id: params.id } });

  return (
    <main className='grid grid-cols-2 gap-8'>
      {/* 🍃 Leaf: Needs state for sliding images */}
      <ImageGallery images={product.images} />

      <div>
        {/* Trunk: Static HTML, SEO friendly */}
        <h1 className='text-3xl font-bold'>{product.name}</h1>

        {/* Trunk: Heavy Markdown parsing happens here, 0kb sent to client */}
        <ProductDescription text={product.description} />

        <div className='mt-4'>
          <span className='text-xl'>${product.price}</span>
          {/* 🍃 Leaf: Needs onClick handler */}
          <AddToCart productId={product.id} />
        </div>
      </div>

      {/* Trunk: Static List */}
      <ReviewsList productId={product.id} />
    </main>
  );
}

// 1. THE CONTAINER (Server Component)
// app/components/UserProfile.tsx
import db from '@/lib/db';
import { UserCard } from './UserCard'; // The Presenter

export async function UserProfile({ userId }: { userId: string }) {
  // 1. Perform Data Fetching (Securely on Server)
  const user = await db.user.findUnique({ where: { id: userId } });

  if (!user) return <div>User not found</div>;

  // 2. Perform Transformations (e.g., Date formatting)
  const formattedDate = new Intl.DateTimeFormat('en-US').format(user.createdAt);

  // 3. Pass *Serialized Data* to the Presenter
  return (
    <UserCard
      name={user.name}
      avatarUrl={user.avatar}
      bio={user.bio}
      joinedAt={formattedDate}
    />
  );
}

// 1. THE SEARCH INPUT (Client Component)
// app/search/SearchInput.tsx
'use client';
import { useRouter, useSearchParams } from 'next/navigation';

export function SearchInput() {
  const router = useRouter();
  const searchParams = useSearchParams();

  function handleSearch(term: string) {
    const params = new URLSearchParams(searchParams.toString());
    if (term) {
      params.set('q', term);
    } else {
      params.delete('q');
    }
    // Update URL without refreshing page
    router.replace(`?${params.toString()}`);
  }

  return (
    <input
      defaultValue={searchParams.get('q') ?? ''}
      onChange={(e) => handleSearch(e.target.value)}
      className='border p-2'
      placeholder='Search...'
    />
  );
}

// 2. THE PAGE (Server Component)
// app/search/page.tsx
import db from '@/lib/db';
import { SearchInput } from './SearchInput';

// Server Components receive 'searchParams' automatically!
export default async function SearchPage({
  searchParams,
}: {
  searchParams: { [key: string]: string | string[] | undefined };
}) {
  const query = typeof searchParams.q === 'string' ? searchParams.q : '';

  // The Server filters the data based on the URL
  const results = await db.items.findMany({
    where: {
      name: { contains: query },
    },
  });

  return (
    <div>
      <SearchInput />
      <ul>
        {results.map((item) => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}

// 1. THE WRAPPER (Client Component)
// components/MotionDiv.tsx
'use client';
import { motion } from 'framer-motion';

// We export only what we need, wrapped in 'use client'
export const MotionDiv = motion.div;

// 2. THE USAGE (Server Component)
// app/page.tsx
import { MotionDiv } from './components/MotionDiv';

export default function Page() {
  return (
    <div className='p-10'>
      {/* 
         We can pass Server Content (children) into the Client Wrapper
         without turning the children into client code.
      */}
      <MotionDiv initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
        <h1>Static Server Content</h1>
      </MotionDiv>
    </div>
  );
}

npm install server-only

// lib/data-access.ts
import 'server-only'; // ☠️ The Poison Pill
import db from './db';

export async function getSensitiveData(userId: string) {
  const secretKey = process.env.STRIPE_SECRET_KEY;
  return db.finance.findMany({
    where: { userId },
    headers: { Authorization: `Bearer ${secretKey}` },
  });
}

// app/dashboard/ClientChart.tsx
'use client';
import { getSensitiveData } from '@/lib/data-access'; // ❌ BUILD ERROR

// app/dashboard/layout.tsx (Server Component)
export default function DashboardLayout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
}) {
  return (
    <div className='dashboard-grid'>
      <nav>{children}</nav>
      <div className='stats-row'>
        {/* These load INDEPENDENTLY. If analytics is slow, team still shows. */}
        {analytics}
        {team}
      </div>
    </div>
  );
}

// 1. THE ISOLATED COMPONENT (Server Component)
// components/UserMenu.tsx
import { cookies } from 'next/headers';

export async function UserMenu() {
  // This read is isolated here
  const session = cookies().get('session');
  if (!session) return <a href='/login'>Login</a>;
  return <div>Welcome User</div>;
}

// 2. THE PAGE (Stays Static!)
// app/page.tsx
import { UserMenu } from './components/UserMenu';
import { Suspense } from 'react';

export default function LandingPage() {
  return (
    <div>
      <nav>
        <h1>My Static Brand</h1>
        {/* The page remains static/cached. Only this hole is dynamic. */}
        <Suspense fallback={<div>Loading...</div>}>
          <UserMenu />
        </Suspense>
      </nav>
      <main>
        <StaticHeroSection />
      </main>
    </div>
  );
}

// 1. THE FETCH (Cached with Tags)
// lib/api.ts
export async function getPosts() {
  const res = await fetch('https://api.cms.com/posts', {
    next: {
      tags: ['posts'], // 🏷️ Tag this cache entry
    },
  });
  return res.json();
}

// 2. THE SERVER ACTION (The Trigger)
// app/actions.ts
'use server';
import { revalidateTag } from 'next/cache';

export async function refreshBlog() {
  // 🧹 Purge the cache for anything tagged 'posts'
  revalidateTag('posts');
}

'use client' // Flaw 1?
import { useEffect } from 'react';
import { UserContext } from './context';
import Analytics from './analytics'; // Heavy lib

export default function Layout({ children }) {
  // Flaw 2?
  useEffect(() => {
     Analytics.init();
  }, []);

  return (
    <html>
      <body>
        <UserContext.Provider value={{...}}>
           {children}
        </UserContext.Provider>
      </body>
    </html>
  );
}