app-router

Next.js App Router & React Standards

Next.js App Router Patterns

Server Components (Default)

Server components are the default in Next.js App Router. Only use client components when interactivity is needed.

// ✅ DEFAULT: Server Component (no 'use client')
export default function Page() {
  // Server-side rendering by default
  return <div>Server Component</div>;
}

Client Components (Explicit)

Only mark components as client components when they need interactivity.

// ✅ EXPLICIT: Only when needed
'use client';

import { useState } from 'react';

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

File Structure (App Router)

src/app/
├── layout.tsx           # Root layout
├── page.tsx            # Home page
├── loading.tsx         # Loading UI
├── error.tsx           # Error boundary
├── not-found.tsx       # 404 page
├── dashboard/
│   ├── layout.tsx      # Nested layout
│   ├── page.tsx        # Dashboard page
│   └── users/
│       └── page.tsx    # Users page
└── api/
    └── users/
        └── route.ts    # API endpoint

Component Standards

Functional Components with TypeScript

All React components must have proper TypeScript interfaces and explicit return types.

// ✅ REQUIRED: Props interface + explicit return type
interface UserCardProps {
  user: User;
  onSelect?: (user: User) => void;
  className?: string;
}

export function UserCard({ 
  user, 
  onSelect, 
  className 
}: UserCardProps): JSX.Element {
  return (
    <div 
      className={`border-gray-200 shadow-sm ${className}`}
      onClick={() => onSelect?.(user)}
    >
      <h3 className="text-gray-900">{user.name}</h3>
      <p className="text-gray-700">{user.email}</p>
    </div>
  );
}

Data Testid Requirements (MANDATORY)

Add data-testid to all interactive elements, dynamic state containers, and structural landmarks when building components. This is a build-time requirement, not a testing afterthought.