Frontend Development

Next.js (latest) App Router with TypeScript. Server-first architecture.

Related Skills:

• kavak-documentation – USE FIRST for Kavak-specific patterns, GitLab CI, Docker templates
• vercel-react-best-practices – USE THIS for performance (bundle size, waterfalls, caching, re-renders, memoization)
• Check .claude/CLAUDE.md for project-specific conventions
• Check .cursor/rules/* for project-specific conventions

MCP:

• Use kavak-platform/plati_query tool to query Kavak internal documentation before implementing
• Use next-devtools MCP server if available for debugging, route inspection, and build analysis

Quick Start

Core Principles

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

Server vs Client Decision

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.

Data Fetching Pattern

// app/users/page.tsx - Server Component (default)
export default async function UsersPage() {
    const users = await db.user.findMany();  // Runs on server
    return <UserList users={users} />;
}

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

Server Actions Pattern

// 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

Critical Rules

Never

// ❌ 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
<Grid xs={12} md={6}>

Always

// ✅ Small leaf-level client components
// ✅ Validate Server Action inputs with Zod
// ✅ MUI Grid size prop
<Grid size={{ xs: 12, md: 6 }}>

File Conventions

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)

Common Workflows

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<Theme>
2. Inline styles if <100 lines, separate .styles.ts if >100
3. Grid: size={{ xs: 12, md: 6 }}

References

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

Technology Stack

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