frontend-development

| Task | Pattern |

| ------------- | -------------------------------------------------- |

| New page | Server Component by default |

| Data fetching | Server Component async fetch |

| Mutations | Server Actions + Zod + revalidatePath |

| Styling | MUI sx prop, inline if <100 lines |

| State | Server = fetch, Client = useState only when needed |

1. Server by Default: Components are Server Components unless they need useState/useEffect/events
2. Server Actions for Mutations: Replace API routes for internal app logic
3. Opt-in Caching: Use 'use cache' directive for explicit caching
4. Minimal Client JS: Keep 'use client' components small and leaf-level
5. Type Everything: Strict TypeScript, Zod for runtime validation

> Performance: For bundle optimization, waterfalls, memoization, see vercel-react-best-practices

```

Need useState/useEffect/onClick? → 'use client'

Need browser APIs (localStorage)? → 'use client'

Just rendering data? → Server Component (default)

```

Rule: Keep Client Components small. Most of tree stays server-rendered.

```typescript

// app/users/page.tsx - Server Component (default)

export default async function UsersPage() {

const users = await db.user.findMany(); // Runs on server

return ;

}

```

No TanStack Query needed - Server Components handle data fetching natively.

```typescript

// app/actions.ts

'use server';

import { z } from 'zod';

import { revalidatePath } from 'next/cache';

const schema = z.object({ title: z.string().min(1) });

export async function createPost(formData: FormData) {

const parsed = schema.safeParse({ title: formData.get('title') });

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

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

revalidatePath('/posts');

return { success: true };

}

```

When to use Server Actions vs API Routes:

• Server Actions → Internal mutations, form submissions
• Route Handlers → Public APIs, webhooks, large uploads, streaming

Never

```typescript

// ❌ Large 'use client' at top of tree

'use client'; // Marks entire subtree as client

// ❌ Expose secrets to client

const apiKey = process.env.SECRET_KEY; // In client component

// ❌ Old MUI Grid syntax

```

Always

```typescript

// ✅ Small leaf-level client components

// ✅ Validate Server Action inputs with Zod

// ✅ MUI Grid size prop

```

```

app/

├── layout.tsx # Root layout (Server)

├── page.tsx # Home page

├── loading.tsx # Loading UI (Suspense fallback)

├── error.tsx # Error boundary ('use client')

├── not-found.tsx # 404 page

├── users/

│ ├── page.tsx # /users

│ ├── [id]/

│ │ └── page.tsx # /users/:id

│ └── actions.ts # Server Actions

└── api/

└── webhook/

└── route.ts # Route Handler (public API)

```

New Feature

1. Create app/{route}/page.tsx (Server Component)
2. Add loading.tsx for Suspense boundary
3. Create Server Actions in actions.ts
4. Add Client Components only where needed

Performance Issue

→ Run vercel-react-best-practices skill for optimization rules

Styling Component

1. Use MUI sx prop with SxProps
2. Inline styles if <100 lines, separate .styles.ts if >100
3. Grid: size={{ xs: 12, md: 6 }}

| Reference | When to Use |

| ---------------------------------- | ---------------------------------------- |

| references/nextjs.md | App Router, RSC, Server Actions, caching |

| references/component-patterns.md | React.FC, hooks order, dialogs, forms |

| references/styling.md | MUI sx prop, Grid, theming |

| references/typescript.md | Types, generics, Zod validation |

| references/project-structure.md | features/ vs components/, organization |

Performance/Optimization → vercel-react-best-practices skill

| Layer | Technology |

| ------------- | ------------------------------- |

| Framework | Next.js (App Router, latest) |

| Type Safety | TypeScript (strict) + Zod |

| Data Fetching | Server Components (async) |

| Mutations | Server Actions + revalidatePath |

| Client State | useState (minimal) |

| Styling | MUI (latest) |

| Forms | Server Actions + useActionState |

Note: TanStack Query only if you need real-time polling or complex optimistic updates. See references/data-fetching.md.