Frontend Development

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

sx

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)

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

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

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

vercel-react-best-practices

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

references/nextjs.md

references/component-patterns.md

references/styling.md

references/typescript.md

references/project-structure.md

vercel-react-best-practices

Technology Stack

references/data-fetching.md