Next.js + TypeScript

Server vs Client Components

The App Router defaults to Server Components. Every component is a Server Component unless it explicitly opts in to the client.

Decision Rule

Does the component need any of the following?
  - useState / useReducer
  - useEffect / lifecycle methods
  - Browser APIs (window, document, localStorage)
  - Event listeners (onClick, onChange, onSubmit)
  - Third-party libraries that require the DOM

  YES → Client Component (`"use client"` directive)
  NO  → Server Component (default, no directive needed)

Keep the "use client" boundary as far down the component tree as possible. Wrap only the interactive leaf node, not the entire page.

Server Component (default)

// app/users/page.tsx — no directive needed
import { db } from '@/lib/db';

export default async function UsersPage() {
  // Direct database access — no API round-trip needed
  const users = await db.user.findMany({ orderBy: { createdAt: 'desc' } });

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.email}</li>
      ))}
    </ul>
  );
}

Client Component

// components/ui/counter.tsx
'use client';

import { useState } from 'react';

interface Props {
  initialCount?: number;
}

export function Counter({ initialCount = 0 }: Props) {
  const [count, setCount] = useState(initialCount);
  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>;
}

Composing Server and Client

// app/dashboard/page.tsx — Server Component
import { Counter } from '@/components/ui/counter';  // Client
import { getUser } from '@/lib/queries';            // Server-only function

export default async function DashboardPage() {
  const user = await getUser();  // runs on the server

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <Counter initialCount={user.loginCount} />  {/* client island */}
    </div>
  );
}

Passing server data to client components as props is correct. The server renders the Server Component tree first, serializes the props, and sends them to the client.

Data Fetching

Server Component Fetching (recommended for initial data)

// app/posts/[id]/page.tsx
interface Props {
  params: Promise<{ id: string }>;
}

export default async function PostPage({ params }: Props) {
  const { id } = await params;
  const post = await fetch(`https://api.example.com/posts/${id}`, {
    next: { revalidate: 3600 },  // ISR: revalidate every hour
  }).then(r => r.json());

  if (!post) notFound();

  return <article>{post.title}</article>;
}

Cache strategies:

Server Actions (mutations)

Server Actions run on the server. Use them for form submissions and mutations. Never use them for reads.

// app/posts/create/actions.ts
'use server';

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
import { z } from 'zod';
import { db } from '@/lib/db';

const CreatePostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(1),
});

export async function createPost(formData: FormData) {
  const parsed = CreatePostSchema.safeParse({
    title: formData.get('title'),
    content: formData.get('content'),
  });

  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors };
  }

  await db.post.create({ data: parsed.data });

  revalidatePath('/posts');
  redirect('/posts');
}

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

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

Rules for Server Actions:

• Always validate input with Zod — do not trust FormData values
• Return error objects for validation failures; use redirect() for success
• Call revalidatePath() or revalidateTag() after mutations that affect cached data
• Never put secrets or auth logic in Client Components — keep it in actions

TanStack Query (client-side data)

Use TanStack Query for data that must stay fresh on the client: real-time feeds, user-specific data after mutations, optimistic updates.

// components/posts/post-list.tsx
'use client';

import { useQuery } from '@tanstack/react-query';

interface Post {
  id: string;
  title: string;
}

export function PostList() {
  const { data, isLoading, error } = useQuery<Post[]>({
    queryKey: ['posts'],
    queryFn: () => fetch('/api/posts').then(r => r.json()),
    staleTime: 60_000,   // treat data as fresh for 60 seconds
  });

  if (isLoading) return <p>Loading...</p>;
  if (error) return <p>Failed to load posts.</p>;

  return (
    <ul>
      {data?.map(post => <li key={post.id}>{post.title}</li>)}
    </ul>
  );
}

Do not use TanStack Query for data that a Server Component can fetch directly. The extra client-side fetch is unnecessary when the data can be fetched at render time on the server.

Route Handlers

Use route handlers for: webhooks, third-party OAuth callbacks, or endpoints consumed by non-Next.js clients.

// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { db } from '@/lib/db';

const CreatePostBody = z.object({
  title: z.string().min(1),
  content: z.string().min(1),
});

export async function GET() {
  const posts = await db.post.findMany({ orderBy: { createdAt: 'desc' } });
  return NextResponse.json(posts);
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  const parsed = CreatePostBody.safeParse(body);

  if (!parsed.success) {
    return NextResponse.json(
      { error: parsed.error.flatten() },
      { status: 400 }
    );
  }

  const post = await db.post.create({ data: parsed.data });
  return NextResponse.json(post, { status: 201 });
}

Metadata API

// app/posts/[id]/page.tsx
import type { Metadata } from 'next';

interface Props {
  params: Promise<{ id: string }>;
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { id } = await params;
  const post = await fetch(`/api/posts/${id}`).then(r => r.json());

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      images: [{ url: post.coverImage }],
    },
  };
}

Never hardcode metadata in <head> tags — use the Metadata API. It handles deduplication, inheritance, and streaming correctly.

Streaming with Suspense

// app/dashboard/page.tsx
import { Suspense } from 'react';
import { UserStats } from './user-stats';   // slow data fetch
import { RecentActivity } from './recent'; // fast data fetch

export default function DashboardPage() {
  return (
    <div>
      <RecentActivity />   {/* renders immediately */}
      <Suspense fallback={<p>Loading stats...</p>}>
        <UserStats />      {/* streams in when ready */}
      </Suspense>
    </div>
  );
}

Wrap independently slow data sources in their own <Suspense> boundaries. Do not wrap the entire page — that defeats streaming.

TypeScript Conventions

// Use type imports for type-only imports
import type { User } from '@prisma/client';

// Prefer interfaces for object shapes that may be extended
interface UserCardProps {
  user: Pick<User, 'id' | 'name' | 'email'>;
  onSelect?: (id: string) => void;
}

// Use type aliases for unions and computed types
type Status = 'active' | 'inactive' | 'pending';
type UserWithPosts = User & { posts: Post[] };

Rules:

• Never use any — use unknown and narrow with type guards
• Use satisfies to validate objects against a type without widening
• Co-locate type definitions with the component or function that uses them; export only what other modules need
• Use next/navigation hooks (useRouter, usePathname) not next/router — the latter is Pages Router only

Project Structure

app/
  (auth)/                — route group, no URL segment
    login/page.tsx
    register/page.tsx
  (dashboard)/
    dashboard/page.tsx
    posts/
      [id]/page.tsx
      create/
        page.tsx
        actions.ts
  api/
    posts/route.ts
  layout.tsx             — root layout
  not-found.tsx

components/
  ui/                    — generic, reusable components
  posts/                 — domain-specific components

lib/
  db.ts                  — database client
  auth.ts                — auth configuration
  queries.ts             — reusable server-side query functions