// Server Component (default) - no 'use client' directive needed
async function ProductList() {
  const products = await db.products.findMany() // direct DB access
  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>
}

// Client Component - only when interactivity is required
'use client'
function AddToCartButton({ productId }: { productId: string }) {
  const [added, setAdded] = useState(false)
  return <button onClick={() => setAdded(true)}>{added ? 'Added' : 'Add'}</button>
}

// Correct: Server Component renders most of the tree
export default async function ProductPage({ params }: { params: { id: string } }) {
  const product = await getProduct(params.id)
  return (
    <div>
      <h1>{product.name}</h1>          {/* stays on server */}
      <p>{product.description}</p>     {/* stays on server */}
      <AddToCartButton productId={product.id} /> {/* only this is client */}
    </div>
  )
}

// Bad: 600ms sequential wait
const user = await getUser(id)
const posts = await getPosts(id)      // waits for user unnecessarily
const stats = await getStats(id)      // waits for posts unnecessarily

// Good: ~200ms parallel fetch
const [user, posts, stats] = await Promise.all([
  getUser(id),
  getPosts(id),
  getStats(id),
])

// Bad: fetches userData even when skipping
async function handleRequest(userId: string, skipProcessing: boolean) {
  const userData = await fetchUserData(userId)
  if (skipProcessing) return { skipped: true }
  return processUserData(userData)
}

// Good: fetch only when needed
async function handleRequest(userId: string, skipProcessing: boolean) {
  if (skipProcessing) return { skipped: true }
  const userData = await fetchUserData(userId)
  return processUserData(userData)
}

// Both components call getUser — only one network request is made
async function Header() {
  const user = await getUser()
  return <nav>{user.name}</nav>
}

async function ProfilePage() {
  const user = await getUser()        // deduplicated automatically
  return <Header />, <main>{user.bio}</main>
}

import { cache } from 'react'
import 'server-only'

export const getUser = cache(async (id: string) => {
  return db.users.findUnique({ where: { id } })
})

export default async function Dashboard() {
  return (
    <>
      <StaticHeader />
      <Suspense fallback={<Skeleton />}>
        <SlowAnalyticsWidget />     {/* streams in when ready */}
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <SlowActivityFeed />        {/* independent stream */}
      </Suspense>
    </>
  )
}

import Item, { preload } from '@/components/Item'

export default async function Page({ params }: { params: { id: string } }) {
  preload(params.id)                         // starts immediately
  const isAvailable = await checkIsAvailable()
  return isAvailable ? <Item id={params.id} /> : null
}

// Bad: JSON.parse runs on every render
const [config, setConfig] = useState(JSON.parse(localStorage.getItem('config') ?? '{}'))

// Good: callback runs once at mount
const [config, setConfig] = useState(() => JSON.parse(localStorage.getItem('config') ?? '{}'))

import dynamic from 'next/dynamic'

const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <Skeleton />,
  ssr: false,              // client-only libraries (e.g., chart.js)
})

// Bad: imports entire lodash
import { debounce } from 'lodash'

// Good: imports only debounce
import debounce from 'lodash/debounce'

import 'server-only'   // throws at build time if imported from a Client Component

// Bad: scans messages 8 separate times
const unread = messages.filter(m => !m.read)
const pinned = messages.filter(m => m.pinned)
const recent = messages.filter(m => isRecent(m))

// Good: single pass
const { unread, pinned, recent } = messages.reduce(
  (acc, m) => {
    if (!m.read) acc.unread.push(m)
    if (m.pinned) acc.pinned.push(m)
    if (isRecent(m)) acc.recent.push(m)
    return acc
  },
  { unread: [], pinned: [], recent: [] }
)

// app/actions.ts
'use server'
import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  await db.posts.create({ data: { title } })
  revalidatePath('/posts')
}

// app/posts/new/page.tsx
import { createPost } from '../actions'

export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  )
}

// next.config.js
module.exports = { experimental: { taint: true } }

// utils/user.ts
import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'

export async function getUser(id: string) {
  const user = await db.users.findUnique({ where: { id } })
  experimental_taintObjectReference('Do not pass full user to client', user)
  experimental_taintUniqueValue('Do not pass token to client', user, user.apiToken)
  return user
}

app/
  (marketing)/         # route group — no URL segment
    page.tsx
  dashboard/
    layout.tsx
    page.tsx
    _components/       # co-located, not a route
      Sidebar.tsx
components/            # shared UI
  ui/
    Button.tsx
lib/                   # utilities, data-fetching helpers
  db.ts
  auth.ts