Nextjs App Router

Data Fetching

Fetch data directly in Server Components using async/await. Do not use useEffect for data fetching in server-rendered pages.

// app/users/page.tsx
async function getUsers() {
  const res = await fetch('https://api.example.com/users', {
    next: { revalidate: 60 }, // ISR: revalidate every 60 seconds
  });
  if (!res.ok) throw new Error('Failed to fetch users');
  return res.json() as Promise<User[]>;
}

export default async function UsersPage() {
  const users = await getUsers();
  return <UserList users={users} />;
}

• Use cache: 'force-cache' (default) for static data.
• Use cache: 'no-store' for real-time data that must be fresh on every request.
• Use next: { revalidate: N } for time-based ISR.
• Use revalidatePath() or revalidateTag() in Server Actions for on-demand revalidation.
• For database queries, use unstable_cache or React's cache() to deduplicate within a request.

Routing and Layouts

• layout.tsx wraps child routes and preserves state across navigation. Use for shared UI (nav, sidebar).
• page.tsx is the unique content for a route segment.
• loading.tsx provides instant loading UI using React Suspense.
• error.tsx (must be 'use client') catches errors in a route segment.
• not-found.tsx handles 404s. Trigger with notFound() from next/navigation.

app/
  layout.tsx          # Root layout (html, body, global providers)
  page.tsx            # Home page
  dashboard/
    layout.tsx        # Dashboard layout (sidebar)
    page.tsx          # /dashboard
    settings/
      page.tsx        # /dashboard/settings
  (auth)/
    login/page.tsx    # /login (grouped without affecting URL)
    register/page.tsx # /register

• Use route groups (groupName) to organize without affecting the URL.
• Use [slug] for dynamic segments and [...slug] for catch-all segments.
• Use @modal parallel routes for modal patterns that preserve URL state.

Server Actions

Use Server Actions for form submissions and data mutations. Define them with 'use server' at the top of the function or file.

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

import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  await db.post.create({ data: { title, content } });
  revalidatePath('/posts');
}

• Validate all inputs in Server Actions. Never trust client data.
• Use useFormStatus for pending states and useFormState for returned errors.
• Server Actions can be called from Client Components via form action or direct invocation.
• Return serializable data only (no class instances, functions, or Dates).

Metadata and SEO

Use the metadata export or generateMetadata for dynamic metadata.

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const post = await getPost(params.slug);
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: { images: [post.coverImage] },
  };
}

• Define a root metadata in app/layout.tsx with defaults (title template, description).
• Use title: { template: '%s | MySite', default: 'MySite' } for consistent page titles.

Streaming and Suspense

Use loading.tsx or manual <Suspense> boundaries to stream content progressively.

import { Suspense } from 'react';

export default function Page() {
  return (
    <>
      <h1>Dashboard</h1>
      <Suspense fallback={<ChartSkeleton />}>
        <SlowChart />
      </Suspense>
      <Suspense fallback={<TableSkeleton />}>
        <SlowDataTable />
      </Suspense>
    </>
  );
}

Middleware

Use middleware.ts at the project root for authentication checks, redirects, and header manipulation. Keep middleware fast -- do not run heavy logic or database queries.

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('session');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
}

export const config = { matcher: ['/dashboard/:path*'] };

Common Pitfalls

• Do not import server-only code in Client Components. Use the server-only package to enforce boundaries.
• Do not pass non-serializable props (functions, class instances) from Server to Client Components.
• Do not use useRouter from next/router -- use next/navigation in the App Router.
• Avoid excessive 'use client' boundaries. Each one creates a new client bundle entry point.