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 States

// app/​dashboard/​loading.tsx
export default function Loading() {
  return <div>Loading...</​div>;
}

Error Handling

// app/​dashboard/​error.tsx
'use client';

export default function Error({
  error,
  reset
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</​h2>
      <button onClick={reset}>Try again</​button>
    </​div>
  );
}

API Routes

// app/​api/​posts/​route.ts
import { NextResponse } from 'next/​server';

export async function GET(request: Request) {
  const posts = await getPosts();
  return NextResponse.json(posts);
}

export async function POST(request: Request) {
  const body = await request.json();
  const post = await createPost(body);
  return NextResponse.json(post, { status: 201 });
}

---

Anti-Patterns

❌ Using 'use client' on every component ❌ Not using Server Components for data fetching ❌ Inline styles instead of Tailwind ❌ Not using shadcn/​ui components ❌ useState for server data (use Server Components) ❌ Direct database queries in Client Components ❌ Missing loading/​error states ❌ Not using TypeScript properly

---

Customization Instructions

For Your Tech Stack

Not using Next.js? Adapt the patterns:

• Vue/​Nuxt → Similar SSR patterns
• Vite + React → Remove Server Components, use TanStack Query
• Angular → Similar concepts, different syntax
• Svelte/​SvelteKit → SvelteKit has similar features

For Your UI Library

Not using shadcn/​ui? Replace with:

• Material-UI → Import from @mui/​material
• Chakra UI → Import from @chakra-ui/​react
• Ant Design → Import from antd
• Custom components → Build your own

For Your Patterns

Keep the principles:

• Component composition
• Type safety
• Performance optimization
• Accessibility
• SEO considerations

---

Related Skills

• backend-dev-guidelines - Supabase Edge Functions patterns
• memory-management - Track UI/​UX decisions
• skill-developer - Meta-skill for creating skills

---

Skill Status: SCAFFOLD ✅ Line Count: < 500 ✅ Progressive Disclosure: Instructional patterns + generate on-demand ✅