Frontend Development

Next.js App Router with TypeScript. Server-first architecture. Covers everything from adding a page to building complex interactive features — including vague tasks where you need to figure out the right approach from context.

Related Skills:

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

MCP: Use kavak-platform/platform_docs_search for Kavak internal docs and kavak-platform/search_resource for workload info.

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)

Keep Client Components small. Most of the 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. Only use TanStack Query for real-time polling or complex optimistic updates.

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 };
}

• Server Actions → internal mutations, form submissions
• Route Handlers → public APIs, webhooks, large uploads, streaming

Design Quality

When building UI, avoid generic-looking interfaces. Every interface should feel intentional:

• Typography — pick fonts that match the context. Avoid defaulting to Inter/Roboto/Arial for everything
• Color — commit to a cohesive palette with CSS variables. Dominant colors with sharp accents beat timid, evenly-distributed palettes
• Spacing — generous negative space or controlled density, not cramped defaults
• Motion — meaningful animations for state transitions, not gratuitous effects. Use CSS transitions first, Motion library for complex sequences

Match complexity to the design vision. A dashboard needs clarity and information density. A marketing page needs bold visual impact. A form needs clean usability.

Critical Rules

// ❌ Large 'use client' at top of tree — marks entire subtree as client
// ❌ Expose secrets in client: process.env.SECRET_KEY
// ❌ Old MUI Grid syntax: <Grid xs={12} md={6}>

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

Styling Component

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

Performance Issue

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

References

Next.js DevTools MCP (Next.js 16+)

When working on a Next.js 16+ project, use these MCP tools for runtime diagnostics and documentation. They provide better information than reading files or guessing — always prefer them when available.

Workflow: Before implementing changes, call nextjs_index to understand current routes and state. Before looking up Next.js APIs, call nextjs_docs with the correct path from the docs index. Use nextjs_call for runtime diagnostics (errors, build status) instead of reading logs manually.

Technology Stack