frontend-dev-guidelines

📋 OPINIONATED SCAFFOLD: Modern Next.js + React 19 + shadcn/ui stack

Default Stack:

- Framework: Next.js 14+ (App Router)

- UI Library: React 19

- Components: shadcn/ui (Radix primitives)

- Styling: Tailwind CSS

- Forms: React Hook Form + Zod validation

- State: React Context + TanStack Query for server state

- Data Fetching: Server Components, Server Actions, TanStack Query

- Language: TypeScript

- Deployment: Vercel

Frontend Development Guidelines

Purpose

Modern frontend development with Next.js 14+ App Router, React 19, Server Components, and shadcn/ui. Focus on performance, type safety, and excellent UX with Supabase integration.

When to Use This Skill

• Creating pages with App Router
• Building Server/Client Components
• Implementing Server Actions
• Adding shadcn/ui components
• Styling with Tailwind CSS
• Data fetching with Supabase
• Forms with React Hook Form + Zod
• Performance optimization
• TypeScript patterns

Quick Start

New Page Checklist

• [ ] Create app/[route]/page.tsx
• [ ] Use Server Component by default (no 'use client')
• [ ] Fetch data directly in component
• [ ] Add loading.tsx for loading state
• [ ] Add error.tsx for error handling
• [ ] Export metadata for SEO
• [ ] Use Tailwind for styling

New Component Checklist

• [ ] Server Component or Client Component?
• [ ] Add 'use client' ONLY if using hooks/events
• [ ] Use shadcn/ui components
• [ ] Style with Tailwind classes
• [ ] TypeScript types for props
• [ ] Use cn() for conditional classes

Core Principles

1. Server Components by Default

// ✅ Server Component (default)
export default async function Page() {
  const data = await getData()  // Direct fetch, no hooks
  return <div>{data.title}</div>
}

// ❌ Don't add 'use client' unless needed
'use client'  // Only add if using hooks/events!

2. Client Components When Needed

// ✅ Client Component (interactivity)
'use client'

import { useState } from 'react'
import { Button } from '@/components/ui/button'

export function Counter() {
  const [count, setCount] = useState(0)
  return <Button onClick={() => setCount(count + 1)}>{count}</Button>
}

3. Server Actions for Mutations

// app/actions.ts
'use server'

import { revalidatePath } from 'next/cache'
import { createServerClient } from '@/lib/supabase/server'

export async function createPost(formData: FormData) {
  const supabase = createServerClient()

  const { data, error } = await supabase
    .from('posts')
    .insert({ title: formData.get('title') })

  if (error) throw error

  revalidatePath('/posts')
  return { success: true, data }
}

// In component:
<form action={createPost}>
  <input name="title" />
  <button type="submit">Create</button>
</form>

4. Use shadcn/ui Components

import { Button } from '@/components/ui/button'
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import { Input } from '@/components/ui/input'

export function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Title</CardTitle>
      </CardHeader>
      <CardContent>
        <Input placeholder="Type..." />
        <Button>Submit</Button>
      </CardContent>
    </Card>
  )
}

5. Tailwind CSS for Styling

import { cn } from '@/lib/utils'

export function Component({ className, variant }: Props) {
  return (
    <div className={cn(
      'rounded-lg bg-white p-4 shadow',
      variant === 'primary' && 'border-2 border-blue-500',
      className
    )}>
      Content
    </div>
  )
}

6. Forms with React Hook Form

'use client'

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
})

export function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema)
  })

  async function onSubmit(values: z.infer<typeof schema>) {
    // Handle submission
  }

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <input {...form.register('email')} />
      <input {...form.register('password')} type="password" />
      <button type="submit">Login</button>
    </form>
  )
}

7. Supabase Integration

// Server Component
import { createServerClient } from '@/lib/supabase/server'

export default async function Page() {
  const supabase = createServerClient()
  const { data } = await supabase.from('posts').select('*')

  return <div>{/* Render data */}</div>
}

// Client Component
'use client'

import { createClient } from '@/lib/supabase/client'

export function ClientComponent() {
  const supabase = createClient()
  // Use with hooks...
}

Directory Structure

app/
├── (auth)/              # Route group (auth pages)
│   ├── login/
│   │   └── page.tsx
│   └── register/
│       └── page.tsx
├── dashboard/
│   ├── page.tsx         # /dashboard
│   ├── loading.tsx      # Loading UI
│   ├── error.tsx        # Error UI
│   └── posts/
│       ├── page.tsx     # /dashboard/posts
│       └── [id]/
│           └── page.tsx # /dashboard/posts/[id]
├── api/
│   └── webhook/
│       └── route.ts     # API route
├── layout.tsx           # Root layout
└── page.tsx             # Home page

components/
├── ui/                  # shadcn/ui components
│   ├── button.tsx
│   ├── card.tsx
│   └── input.tsx
└── dashboard/           # Feature components
    ├── post-list.tsx
    └── post-card.tsx

lib/
├── supabase/
│   ├── client.ts        # Client-side
│   └── server.ts        # Server-side
└── utils.ts             # cn() utility

Example Resource Files

📝 Note: This is a scaffold skill with instructional examples. Generate additional resources as needed for your specific project following these patterns.

Patterns Covered

When you need guidance on a specific topic, ask Claude to generate examples:

• Server vs Client Components - When to use each, migration patterns
• Data fetching - Server Components, Server Actions, TanStack Query
• Forms - React Hook Form + Zod, Server Actions
• shadcn/ui usage - Component patterns, customization
• Tailwind patterns - Responsive design, dark mode, animations
• Performance - Code splitting, lazy loading, images
• TypeScript - Component props, generics, utility types
• Testing - Unit tests, integration tests, E2E

How to request: "Show me examples of [topic] with Next.js + shadcn/ui"

Common Imports

// Next.js
import { Metadata } from 'next';
import Link from 'next/link';
import Image from 'next/image';
import { redirect, notFound } from 'next/navigation';
import { revalidatePath, revalidateTag } from 'next/cache';

// React (Client Components)
('use client');
import {
  useState,
  useEffect,
  useCallback,
  useMemo,
  useTransition
} from 'react';

// shadcn/ui
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import {
  Card,
  CardHeader,
  CardTitle,
  CardContent,
  CardFooter
} from '@/components/ui/card';
import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl,
  FormMessage
} from '@/components/ui/form';

// Tailwind
import { cn } from '@/lib/utils';

// Supabase
import { createClient } from '@/lib/supabase/client';
import { createServerClient } from '@/lib/supabase/server';

// Forms
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

Quick Reference

Metadata (SEO)

export const metadata: Metadata = {
  title: 'Page Title',
  description: 'Page description'
};

// Dynamic metadata
export async function generateMetadata({ params }): Promise<Metadata> {
  return {
    title: `Post ${params.id}`
  };
}

Loading S