UI Development

Generate production-ready Next.js projects from natural language, with shadcn/ui components, API integration, type safety, and modern tooling.

Quick Start (TL;DR)

Fast path for simple projects:

1. Create Next.js app → 2. Install shadcn/ui → 3. Build UI → 4. Start with PM2 → 5. Screenshot review → 6. Done

Live preview: Projects run on PM2 (port 3002), accessible at http://localhost:3002 or via nginx proxy if configured.

Default workflow: All projects use PM2 for dev server management (prevents port conflicts, ensures single instance).

Requirements & Optional Features

Required Dependencies

• Node.js 18+ and npm/yarn/pnpm
• Git (for project initialization)

Optional Features (user can decline)

1. Auto-Revision with Visual Review (requires Chromium)

• What it does: Takes screenshots during development to visually review designs and auto-fix issues
• Installation: sudo apt-get install chromium-browser (Debian/Ubuntu)
• Privileges: Read/write access to project files, execute chromium in headless mode
• If declined: Manual review only (you describe, user verifies)

2. Live Preview Server (requires Nginx)

• What it does: Serves project on external port for live preview during development (useful for mobile testing or remote access)
• Installation: sudo apt-get install nginx
• How it works: PM2 runs dev server on port 3002, nginx proxies it to chosen external port
• Nginx config template:

# /etc/nginx/sites-available/<project-name>
  server {
    listen <external-port>;  # e.g., 3001, 8081, etc.
    server_name _;
    
    location / {
      proxy_pass http://localhost:3002;  # PM2 dev server
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection 'upgrade';
      proxy_set_header Host $host;
      proxy_cache_bypass $http_upgrade;
    }
  }

• Enable: sudo ln -s /etc/nginx/sites-available/ /etc/nginx/sites-enabled/ && sudo systemctl reload nginx
• If declined: Access directly via http://localhost:3002 (PM2 port)

Before starting, ask user if they want to enable optional features.

Common Project Types

Quick reference for typical requests:

• Dashboard/Admin Panel → Use (dashboard) route group, shadcn data tables, charts
• Landing Page → Single app/page.tsx, hero section, features grid, testimonials
• Todo/Task App → shadcn checkbox, input, button; local state or API
• Blog/CMS → Dynamic routes app/blog/[slug]/page.tsx, markdown support
• E-commerce → Product catalog, cart state (Zustand), checkout flow
• SaaS App → Auth ((auth) group), protected routes, subscription logic
• Portfolio → Projects grid, contact form, image gallery
• Form-heavy App → React Hook Form + Zod validation, shadcn form components

Ask user: What type of project are you building? (helps determine structure and components)

Tech Stack

Core:

• Next.js 14+ (App Router)
• TypeScript
• Tailwind CSS v3
• shadcn/ui (recommended UI component library)
• ESLint + Prettier

API Integration (default):

• axios (HTTP client)
• @tanstack/react-query (data fetching, caching, state management)

Optional (based on needs):

• Zustand (client-side state management)
• Zod (runtime validation)
• next-auth (authentication)
• Prisma (database ORM)

Project Structure

Industry-standard Next.js 14+ App Router structure with feature-based organization:

<project-name>/
├── app/                                # Next.js 14 App Router
│   ├── (auth)/                         # Route group (auth pages)
│   │   ├── login/
│   │   │   └── page.tsx
│   │   ├── register/
│   │   │   └── page.tsx
│   │   └── layout.tsx                  # Auth-specific layout
│   ├── (dashboard)/                    # Route group (protected pages)
│   │   ├── dashboard/
│   │   │   ├── page.tsx
│   │   │   └── loading.tsx
│   │   ├── profile/
│   │   │   └── page.tsx
│   │   ├── settings/
│   │   │   └── page.tsx
│   │   └── layout.tsx                  # Dashboard layout with sidebar
│   ├── api/                            # API routes
│   │   ├── auth/
│   │   │   └── [...nextauth]/route.ts
│   │   └── users/
│   │       └── route.ts
│   ├── layout.tsx                      # Root layout
│   ├── page.tsx                        # Home page
│   ├── loading.tsx                     # Root loading UI
│   ├── error.tsx                       # Root error boundary
│   ├── not-found.tsx                   # 404 page
│   └── providers.tsx                   # Client providers (React Query, etc.)
│
├── components/
│   ├── ui/                             # shadcn/ui components (auto-generated)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── input.tsx
│   │   ├── form.tsx
│   │   └── ...
│   ├── layout/                         # Layout components
│   │   ├── header.tsx
│   │   ├── footer.tsx
│   │   ├── sidebar.tsx
│   │   └── mobile-nav.tsx
│   ├── features/                       # Feature-specific components
│   │   ├── auth/
│   │   │   ├── login-form.tsx
│   │   │   └── register-form.tsx
│   │   ├── dashboard/
│   │   │   ├── stats-card.tsx
│   │   │   └── recent-activity.tsx
│   │   └── profile/
│   │       ├── profile-header.tsx
│   │       └── edit-profile-form.tsx
│   └── shared/                         # Shared/common components
│       ├── data-table.tsx
│       ├── search-bar.tsx
│       └── pagination.tsx
│
├── lib/                                # Utility functions & configurations
│   ├── api.ts                          # Axios instance + interceptors
│   ├── react-query.ts                  # React Query client config
│   ├── utils.ts                        # Utility functions (cn, formatters)
│   ├── validations.ts                  # Zod schemas
│   ├── constants.ts                    # App constants
│   └── auth.ts                         # Auth utilities (if using next-auth)
│
├── hooks/                              # Custom React hooks
│   ├── use-auth.ts                     # Authentication hook
│   ├── use-user.ts                     # User data hook (React Query)
│   ├── use-posts.ts                    # Posts data hook (React Query)
│   ├── use-media-query.ts              # Responsive design hook
│   └── use-toast.ts                    # Toast notifications (shadcn)
│
├── types/                              # TypeScript type definitions
│   ├── index.ts                        # Common types
│   ├── api.ts                          # API response types
│   ├── user.ts                         # User-related types
│   └── database.ts                     # Database types (Prisma generated)
│
├── actions/                            # Server Actions (Next.js 14+)
│   ├── auth.ts                         # Auth actions
│   ├── user.ts                         # User actions
│   └── posts.ts                        # Posts actions
│
├── config/                             # Configuration files
│   ├── site.ts                         # Site metadata (name, description, etc.)
│   └── navigation.ts                   # Navigation menu config
│
├── prisma/                             # Prisma ORM (if using database)
│   ├── schema.prisma                   # Database schema
│   └── migrations/                     # Database migrations
│
├── public/                             # Static assets
│   ├── images/
│   ├── icons/
│   └── fonts/
│
├── styles/                             # Global styles
│   └── globals.css                     # Tailwind imports + custom styles
│
├── .env.local                          # Environment variables (gitignored)
├── .env.example                        # Environment variables template
├── .eslintrc.json                      # ESLint config
├── .prettierrc                         # Prettier config
├── components.json                     # shadcn/ui config
├── next.config.js                      # Next.js config
├── tailwind.config.ts                  # Tailwind config
├── tsconfig.json                       # TypeScript config
├── package.json                        # Dependencies
└── README.md                           # Project documentation

Directory Purpose

app/ - Next.js 14 App Router pages and layouts. Use route groups (name) for logical grouping without affecting URLs.

components/ - All React components, organized by type:

• ui/ - shadcn/ui components (copy-paste, customizable)
• layout/ - Shared layout components (header, footer, sidebar)
• features/ - Feature-specific components (scoped to one feature)
• shared/ - Reusable components used across features

lib/ - Utility functions, configurations, and third-party library setups.

hooks/ - Custom React hooks, especially React Query hooks for API calls.

types/ - TypeScript type definitions and interfaces.

actions/ - Server Actions for form handling and server-side operations (Next.js 14+).

config/ - App configuration (site metadata, navigation menus, constants).

prisma/ - Database schema and migrations (if using Prisma).

public/ - Static files served at root URL.

styles/ - Global CSS (Tailwind imports + custom styles).

Workflow

Keep user informed at every step — this is a live build log.

⚠️ Important: All projects use PM2 for dev server management (port 3002 by default). This ensures:

• Only one instance runs at a time (no port conflicts)
• Easy process management (list/logs/restart/stop)
• Persistent dev server across terminal sessions
• Better error logging and debugging

Step 1: Project Setup

Ask:

• Project name
• Description/purpose
• Optional features (chromium review, nginx preview)

Create Next.js project:

npx create-next-app@latest <project-name> \
  --typescript \
  --tailwind \
  --app \
  --no-src-dir \
  --import-alias "@/*"

→ Message user: "Next.js project initialized ✓"

Step 2: Create Directory Structure

Create all necessary directories following industry best practices:

cd <project-name>

# Create app route groups
mkdir -p app/\(auth\)/login app/\(auth\)/register
mkdir -p app/\(dashboard\)/dashboard app/\(dashboard\)/profile app/\(dashboard\)/settings
mkdir -p app/api/auth app/api/users

# Create component directories
mkdir -p components/ui components/layout components/features components/shared
mkdir -p components/features/auth components/features/dashboard components/features/profile

# Create utility directories
mkdir -p lib hooks types actions config

# Create static asset directories
mkdir -p public/images public/icons public/fonts

# Create styles directory
mkdir styles

# Create Prisma directory (if using database)
# mkdir -p prisma

Create essential config files:

config/site.ts - Site metadata

export const siteConfig = {
  name: '<Project Name>',
  description: '<Project Description>',
  url: process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000',
  links: {
    github: 'https://github.com/...',
  },
};

config/navigation.ts - Navigation menu

export const mainNav = [
  { title: 'Home', href: '/' },
  { title: 'Dashboard', href: '/dashboard' },
  { title: 'Profile', href: '/profile' },
];

export const dashboardNav = [
  { title: 'Overview', href: '/dashboard' },
  { title: 'Profile', href: '/profile' },
  { title: 'Settings', href: '/settings' },
];

.env.example - Environment variables template

NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api
DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=...
NEXTAUTH_URL=http://localhost:3000

→ Message user: "Directory structure created ✓"

Step 3: Install Dependencies

Core dependencies:

cd <project-name>
npm install axios @tanstack/react-query
npm install -D @types/node

shadcn/ui setup (recommended):

npx shadcn-ui@latest init

This will prompt for configuration. Recommended answers:

• Style: Default
• Base color: Slate
• CSS variables: Yes

Install essential shadcn components:

npx shadcn-ui@latest add button card input label select textarea
npx shadcn-ui@latest add dropdown-menu dialog sheet tabs
npx shadcn-ui@latest add table form avatar badge separator toast

Install form dependencies (for shadcn/ui forms):

npm install react-hook-form @hookform/resolvers zod

Optional (ask user based on needs):

npm install zustand  # State management
npm install next-auth  # Authentication
npm install prisma @prisma/client  # Database ORM

→ Message user: "Dependencies + shadcn/ui installed ✓"

Step 4: Configure Base Files

lib/api.ts (axios instance)

import axios from 'axios';

export const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:3000/api',
  timeout: 10000,
  headers: { 'Content-Type': 'application/json' }
});

// Request interceptor (add auth tokens, etc.)
api.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('token');
    if (token) config.headers.Authorization = `Bearer ${token}`;
    return config;
  },
  (error) => Promise.reject(error)
);

// Response interceptor (handle errors globally)
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Handle unauthorized
    }
    return Promise.reject(error);
  }
);

lib/react-query.ts (query client)

import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute
      refetchOnWindowFocus: false,
      retry: 1,
    },
  },
});

app/providers.tsx (wrap app with providers)

'use client';

import { QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { queryClient } from '@/lib/react-query';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

Update app/layout.tsx to use Providers.

→ Message user: "Base configuration complete ✓"

Step 5: Generate Features

Ask what features/pages to build. For each feature:

1. Create route (app//page.tsx)
2. Create components (components/features//)
3. Create API hooks (hooks/use.ts) using react-query
4. Create types (types/.ts)
5. Optionally create API routes (app/api//route.ts)

Example: User Profile Feature

// types/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

// hooks/useUser.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { api } from '@/lib/api';
import type { User } from '@/types/user';

export const useUser = (id: string) => {
  return useQuery({
    queryKey: ['user', id],
    queryFn: async () => {
      const { data } = await api.get<User>(`/users/${id}`);
      return data;
    },
  });
};

export const useUpdateUser = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (user: Partial<User>) => {
      const { data } = await api.patch<User>(`/users/${user.id}`, user);
      return data;
    },
    onSuccess: (data) => {
      queryClient.invalidateQueries({ queryKey: ['user', data.id] });
    },
  });
};

// app/profile/[id]/page.tsx
'use client';

import { useUser, useUpdateUser } from '@/hooks/useUser';

export default function ProfilePage({ params }: { params: { id: string } }) {
  const { data: user, isLoading, error } = useUser(params.id);
  const updateUser = useUpdateUser();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>{user?.name}</h1>
      <p>{user?.email}</p>
    </div>
  );
}

→ Message user after each feature: "Profile page complete ✓"

Step 6: Build UI with shadcn/ui Components

Use shadcn/ui components (already installed) for consistent, accessible UI. Apply Design Principles (see below).

Example: Profile page with shadcn/ui

import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';

export default function ProfilePage({ params }: { params: { id: string } }) {
  const { data: user, isLoading } = useUser(params.id);

  if (isLoading) return <Card className="w-full max-w-2xl mx-auto"><CardContent>Loading...</CardContent></Card>;

  return (
    <Card className="w-full max-w-2xl mx-auto">
      <CardHeader>
        <div className="flex items-center gap-4">
          <Avatar className="h-20 w-20">
            <AvatarImage src={user?.avatar} />
            <AvatarFallback>{user?.name[0]}</AvatarFallback>
          </Avatar>
          <div>
            <CardTitle>{user?.name}</CardTitle>
            <p className="text-sm text-muted-foreground">{user?.email}</p>
          </div>
        </div>
      </CardHeader>
      <CardContent>
        <Button>Edit Profile</Button>
      </CardContent>
    </Card>
  );
}

When to add more components:

• Forms → npx shadcn-ui@latest add form input label
• Data tables → npx shadcn-ui@latest add table
• Navigation → npx shadcn-ui@latest add navigation-menu
• Feedback → npx shadcn-ui@latest add toast alert

→ Message user: "UI built with shadcn/ui ✓"

Step 7: Visual Review (if chromium enabled)

Important: Use PM2 to manage the dev server (ensures only 1 instance runs, prevents port conflicts).

Start dev server with PM2:

# Stop any existing instance of this project
pm2 delete <project-name> 2>/dev/null || true

# Start with PM2 (port 3002 for nginx proxy)
PORT=3002 pm2 start npm --name "<project-name>" --cwd "$(pwd)" -- run dev

# Give PM2 a moment to start
sleep 2

Wait for server to be fully ready (critical - avoid white screen screenshots):

# Wait for "Ready in" message in PM2 logs (usually 5-15 seconds)
timeout=30
elapsed=0
while [ $elapsed -lt $timeout ]; do
  if pm2 logs <project-name> --nostream --lines 50 2>/dev/null | grep -q "Ready in"; then
    echo "Server ready!"
    sleep 3  # Extra buffer for module loading
    break
  fi
  sleep 1
  elapsed=$((elapsed + 1))
done

# Verify server is responding
if ! curl -s http://localhost:3002 > /dev/null; then
  echo "Warning: Server not responding on port 3002"
  pm2 logs <project-name> --nostream --lines 20
fi

Take screenshots (requires chromium):

bash scripts/screenshot.sh "http://localhost:3002" /tmp/review-desktop.png 1400 900
bash scripts/screenshot.sh "http://localhost:3002" /tmp/review-mobile.png 390 844

Review Checklist (analyze with image tool):

• ✅ Desktop (1400px): Content centered, proper spacing
• ✅ Mobile (390px):
• No horizontal overflow (content fits within screen)
• Text readable (not too small)
• Padding appropriate (p-4 not p-24)
• Touch targets large enough (min 44x44px)
• No content cutting off edges

If issues found: Fix responsive classes, re-run screenshots.

Common fixes:

• Large padding → p-4 md:p-8 lg:p-12
• Large text → text-2xl md:text-4xl
• Wide content → Add max-w-full or px-4

→ Message user: "Review complete, sending preview..."

Step 8: Environment Setup

Create .env.local:

NEXT_PUBLIC_API_BASE_URL=https://api.example.com
DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=...

Create .env.example (template for user).

→ Message user: "Environment template created ✓"

Step 9: Scripts & Documentation

Update package.json scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit"
  }
}

Create README.md with:

• Setup instructions
• Environment variables needed
• Development commands
• API integration guide

→ Message user: "Documentation complete ✓"

Step 10: Export & Deploy Guidance

Stop PM2 dev server (if running):

pm2 delete <project-name> 2>/dev/null || true
pm2 save  # Persist PM2 process list

Zip the project:

cd .. && zip -r /tmp/<project-name>.zip <project-name>/

Send via message tool with filePath.

Provide deployment options:

• Vercel (recommended): npx vercel
• Netlify: npm run build && netlify deploy
• Docker: Provide Dockerfile
• Self-hosted: Provide systemd service + nginx config

→ Message user: "Project ready! 🚀"

Testing & Live Preview

Quick Test (during development)

1. PM2 dev server (always running after Step 7):

# Check status
pm2 list

# View logs
pm2 logs <project-name>

# Access locally
curl http://localhost:3002

2. Live preview URLs:

• Local access: http://localhost:3002
• Nginx proxy (if configured): http://:
• Mobile testing: Use nginx proxy or ngrok/tunneling service

3. Screenshot review (if chromium enabled):

# Desktop (1400x900)
bash scripts/screenshot.sh "http://localhost:3002" /tmp/desktop.png 1400 900

# Mobile (390x844)
bash scripts/screenshot.sh "http://localhost:3002" /tmp/mobile.png 390 844

End-to-End Testing Workflow

Full test sequence:

# 1. Check PM2 status
pm2 list | grep <project-name>

# 2. Verify dev server responding
curl -I http://localhost:3002

# 3. Take screenshots for visual verification
bash scripts/screenshot.sh "http://localhost:3002" /tmp/test-desktop.png 1400 900
bash scripts/screenshot.sh "http://localhost:3002" /tmp/test-mobile.png 390 844

# 4. Check logs for errors
pm2 logs <project-name> --lines 50 | grep -i error

# 5. Test API endpoints (if using API routes)
curl http://localhost:3002/api/health  # Example health check

# 6. Production build test
npm run build && npm run start  # Test production build

# 7. Type check
npm run type-check

Common Testing Scenarios

Scenario 1: Test responsive design

# Mobile, tablet, desktop
for width in 390 768 1400; do
  bash scripts/screenshot.sh "http://localhost:3002" /tmp/screen-${width}.png $width 900
done

Scenario 2: Test specific page/route

# Take screenshot of specific route
bash scripts/screenshot.sh "http://localhost:3002/dashboard" /tmp/dashboard.png 1400 900

Scenario 3: Test after making changes

# PM2 auto-reloads on file changes, verify in logs
pm2 logs <project-name> --lines 20

# Wait for "compiled successfully" then take new screenshot
bash scripts/screenshot.sh "http://localhost:3002" /tmp/updated.png 1400 900

Sharing Preview with User

Option 1: Screenshots

• Send desktop + mobile screenshots via message tool
• User provides feedback, you iterate

Option 2: Nginx proxy + external access

• Set up nginx config (see Optional Features)
• Share URL: http://:
• User can test live in browser

Option 3: Export & deploy

• Zip project and send to user
• User deploys to Vercel/Netlify
• Test on production URL

API Integration Patterns

Pattern 1: REST API (default)

Use axios + react-query:

// hooks/usePosts.ts
import { useQuery, useMutation } from '@tanstack/react-query';
import { api } from '@/lib/api';

export const usePosts = () => {
  return useQuery({
    queryKey: ['posts'],
    queryFn: async () => {
      const { data } = await api.get('/posts');
      return data;
    },
  });
};

export const useCreatePost = () => {
  return useMutation({
    mutationFn: async (post: { title: string; body: string }) => {
      const { data } = await api.post('/posts', post);
      return data;
    },
  });
};

Pattern 2: GraphQL (optional)

Install:

npm install @apollo/client graphql

Setup Apollo Client, use useQuery and useMutation from Apollo.

Pattern 3: tRPC (optional)

For Next.js API routes with type safety:

npm install @trpc/server @trpc/client @trpc/react-query @trpc/next

Pattern 4: Server Actions (Next.js 14+)

For form handling without API routes:

// app/actions.ts
'use server';

export async function createPost(formData: FormData) {
  const title = formData.get('title');
  // ...
}

Always ask user which pattern they prefer for their use case.

Design Principles

Apply these consistently. These are quality standards.

Layout & Spacing

• Consistent Tailwind spacing scale (4, 6, 8, 12, 16, 20, 24)
• Max content width: max-w-5xl or max-w-6xl
• Vertical rhythm: py-16 for sections, py-8 for subsections
• Mobile: minimum px-4 padding

Typography

• Clear hierarchy (h1 → h2 → h3, max 3-4 sizes)
• Line length: max 65-75 characters (max-w-prose)
• Font weight contrast (bold headings, regular body)
• Text color hierarchy (slate-900 → slate-700 → slate-500)

Color & Contrast

• WCAG AA minimum (4.5:1 contrast)
• Limit palette (1 primary + 1 accent + neutrals)
• Consistent accent usage (CTAs, links, active states)

Responsive Design (Critical)

• Mobile-first (390px → 768px → 1024px) - Always design for 390px first
• Responsive padding - Use Tailwind responsive classes:
• Mobile: p-4 or px-4 py-6 (never p-24 on mobile!)
• Tablet: md:p-8 or md:px-6 md:py-8
• Desktop: lg:p-12 xl:p-24
• Example:
• Responsive text sizes - Scale down headings on mobile:
• Mobile: text-2xl → Desktop: md:text-4xl
• Mobile: text-lg → Desktop: md:text-2xl
• No horizontal overflow - Content must fit within 390px width
• Test: Check mobile screenshot for any content cutting off edges
• Use max-w-full on containers
• Break long words: break-words
• Touch targets - min 44x44px for buttons/links on mobile
• Stack on mobile - Grids collapse to single column: grid-cols-1 md:grid-cols-2 lg:grid-cols-3
• Hamburger menu - Required on mobile for navigation

Components (Use shadcn/ui)

• Icons: Use Lucide React (comes with shadcn/ui), never emoji
• Buttons: Use component with variants (default, destructive, outline, ghost)
• Forms: Use shadcn
  with react-hook-form integration
• Cards: Use component for content sections
• Dialogs/Modals: Use
  or components
• Loading states: Use shadcn component for loading UI
• Error handling: Use component for error messages
• Data display: Use component for tabular data
  

  shadcn/ui benefits: Accessible, customizable, copy-paste friendly, works with Tailwind

  
  

  TypeScript Best Practices

  • Strict mode enabled
  • Explicit return types for functions
  • Interface over type for objects
  • Avoid any (use unknown if needed)
  • Use discriminated unions for variants
  
  

  Performance

  • Use Next.js Image component (next/image)
  • Lazy load below-the-fold content
  • Code splitting (dynamic imports)
  • Memoize expensive computations (useMemo, useCallback)
  
  

  Common Patterns

  
  

  Form Handling (with shadcn/ui)

  'use client';
  
  import { zodResolver } from '@hookform/resolvers/zod';
  import { useForm } from 'react-hook-form';
  import * as z from 'zod';
  import { useMutation } from '@tanstack/react-query';
  import { Button } from '@/components/ui/button';
  import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
  import { Input } from '@/components/ui/input';
  import { useToast } from '@/components/ui/use-toast';
  
  const formSchema = z.object({
    name: z.string().min(2, 'Name must be at least 2 characters'),
    email: z.string().email('Invalid email address'),
  });
  
  export default function ContactForm() {
    const { toast } = useToast();
    const form = useForm<z.infer<typeof formSchema>>({
      resolver: zodResolver(formSchema),
      defaultValues: { name: '', email: '' },
    });
  
    const mutation = useMutation({
      mutationFn: async (data: z.infer<typeof formSchema>) => {
        const res = await api.post('/contact', data);
        return res.data;
      },
      onSuccess: () => {
        toast({ title: 'Success', description: 'Message sent!' });
        form.reset();
      },
      onError: (error) => {
        toast({ title: 'Error', description: error.message, variant: 'destructive' });
      },
    });
  
    return (
      <Form {...form}>
        <form onSubmit={form.handleSubmit((data) => mutation.mutate(data))} className="space-y-4">
          <FormField
            control={form.control}
            name="name"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Name</FormLabel>
                <FormControl>
                  <Input placeholder="John Doe" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
          <FormField
            control={form.control}
            name="email"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Email</FormLabel>
                <FormControl>
                  <Input type="email" placeholder="john@example.com" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
          <Button type="submit" disabled={mutation.isPending}>
            {mutation.isPending ? 'Sending...' : 'Send Message'}
          </Button>
        </form>
      </Form>
    );
  }

  
  

  Note: Run npx shadcn-ui@latest add form toast and install npm install react-hook-form @hookform/resolvers zod for this pattern.

  
  

  Pagination

  const usePaginatedPosts = (page: number) => {
    return useQuery({
      queryKey: ['posts', page],
      queryFn: async () => {
        const { data } = await api.get(`/posts?page=${page}`);
        return data;
      },
      keepPreviousData: true, // Smooth transitions
    });
  };

  
  

  Infinite Scroll

  import { useInfiniteQuery } from '@tanstack/react-query';
  
  const useInfinitePosts = () => {
    return useInfiniteQuery({
      queryKey: ['posts'],
      queryFn: async ({ pageParam = 1 }) => {
        const { data } = await api.get(`/posts?page=${pageParam}`);
        return data;
      },
      getNextPageParam: (lastPage, pages) => lastPage.nextPage,
    });
  };

  
  

  Common Mistakes to Avoid

  • ❌ Not wrapping app with QueryClientProvider
  • ❌ Using axios without interceptors (no error handling)
  • ❌ Forgetting loading/error states in components
  • ❌ Not invalidating queries after mutations
  • ❌ Using any instead of proper TypeScript types
  • ❌ Client components when server components would work
  • ❌ Not using Next.js Image component (performance loss)
  • ❌ Missing error boundaries
  • ❌ Hardcoding API URLs (use env vars)
  • ❌ No mobile testing (always check responsive at 390px width)
  • ❌ Large padding on mobile (p-24 = 96px causes overflow on 390px screens)
  • ❌ Not using responsive Tailwind classes (use p-4 md:p-8 lg:p-12)
  • ❌ Horizontal overflow on mobile (content wider than 390px)
  • ❌ Building custom components when shadcn/ui has them (Button, Card, Dialog, etc.)
  • ❌ Using emoji for icons (use Lucide React icons from shadcn/ui)
  • ❌ Not installing @hookform/resolvers and zod before using shadcn forms
  • ❌ Forgetting to add component when using toast notifications
  • ❌ Taking screenshots before dev server is fully ready (causes white screens)
  • ❌ Not waiting for module loading (causes "Module not found" errors in screenshots)
  
  

  Troubleshooting

  
  

  White Screen Screenshots

  Problem: Screenshots show blank white page

  Cause: Dev server not fully initialized before screenshot

  Solution:

  • Wait for "Ready in" message in dev server logs
  • Add 3-5 second buffer after "Ready" message
  • Verify localhost:3000 loads in browser before taking screenshot
  
  

  Module Not Found Errors

  Problem: React error "Module not found: Can't resolve @tanstack/react-query"

  Cause: Dev server started before all packages loaded

  Solution:

  • Restart dev server: pkill -f "next dev" && npm run dev
  • Verify packages in node_modules: ls node_modules/@tanstack/
  • Wait 10-15 seconds after npm install before starting dev server
  
  

  Dev Server Won't Start

  Problem: Port already in use (EADDRINUSE error)

  Solution (PM2 method):

  # Check what's running
  pm2 list
  
  # Stop the conflicting process
  pm2 delete <project-name>
  
  # Or check port directly
  lsof -ti:3002
  
  # Kill process on port (if not PM2-managed)
  kill -9 $(lsof -ti:3002)
  
  # Restart with PM2
  PORT=3002 pm2 start npm --name "<project-name>" --cwd "$(pwd)" -- run dev

  
  

  PM2 Process Management

  List all PM2 processes:

  pm2 list

  
  

  Check logs:

  pm2 logs <project-name> --lines 50

  
  

  Restart a process:

  pm2 restart <project-name>

  
  

  Stop a process:

  pm2 stop <project-name>

  
  

  Delete a process:

  pm2 delete <project-name>

  
  

  Ensure only one instance runs:

  # Always delete before starting
  pm2 delete <project-name> 2>/dev/null || true
  PORT=3002 pm2 start npm --name "<project-name>" --cwd "$(pwd)" -- run dev

  
  

  Common PM2 scenarios:

  
  
  1. Project won't start → Check logs: pm2 logs
  2. Process keeps restarting → Module missing or port conflict, check logs
  3. Changes not reflecting → PM2 auto-reloads, verify in logs: pm2 logs | grep compiled
  4. Multiple instances running → Delete all: pm2 delete all && pm2 list
  5. Check resource usage → pm2 monit (real-time monitoring)
  6. Save PM2 process list → pm2 save (persists across reboots)
  
  

  Iteration & Updates

  
  

  When user requests changes:

  1. Identify affected files
  2. Make changes
  3. PM2 auto-reloads (no manual restart needed for file changes)
  4. Run type check: npm run type-check
  5. Verify in logs: pm2 logs --lines 20
  6. If chromium enabled: take new screenshot
  7. Report changes to user
  
  

  Always explain what changed and why.

  
  

  ---

  
  

  Quick Reference Cheat Sheet

  
  

  Essential Commands

  # Start dev server
  pm2 delete <project-name> 2>/dev/null || true
  PORT=3002 pm2 start npm --name "<project-name>" --cwd "$(pwd)" -- run dev
  
  # Check status
  pm2 list
  pm2 logs <project-name>
  
  # Take screenshots
  bash scripts/screenshot.sh "http://localhost:3002" /tmp/desktop.png 1400 900
  bash scripts/screenshot.sh "http://localhost:3002" /tmp/mobile.png 390 844
  
  # Test production build
  npm run build && npm run start
  
  # Type check
  npm run type-check

  
  

  File Locations

  • Components: components/ui/ (shadcn), components/features/ (custom)
  • Pages: app/*/page.tsx
  • API routes: app/api/*/route.ts
  • Styles: app/globals.css, tailwind.config.ts
  • Config: next.config.ts, .env.local
  
  

  Common shadcn Components

  npx shadcn-ui@latest add button input form card table dialog toast

  
  

  Live Preview URLs

  • Local: http://localhost:3002
  • Nginx proxy: http://:
  • Mobile testing: Use nginx proxy or ngrok
  
  

  Troubleshooting

  1. Port conflict → pm2 delete then restart
  2. White screen → Wait for "Ready in" message (check logs)
  3. Module errors → npm install then restart PM2
  4. Type errors → npm run type-check
  5. Layout breaks → Check responsive classes (p-4 md:p-8 lg:p-12)
  
  
  🤖

  AI Usage Analysis

  Generated Mar 1, 2026

  Web developersStartup foundersSmall business ownersintermediate

  💡 Application Scenarios

  SaaS Platform DashboardSoftware as a Service (SaaS)

  Develop a Next.js dashboard for a SaaS platform with user management, subscription tracking, and analytics. Uses shadcn/ui components for data tables and charts, integrates with a backend API for real-time data, and includes protected routes for authenticated users.

  E-commerce Product CatalogRetail and E-commerce

  Build a responsive e-commerce frontend with product listings, shopping cart functionality, and checkout flow. Implements Zustand for client-side state management, integrates with payment APIs, and uses shadcn/ui for form validation and UI consistency.

  Portfolio Website with BlogCreative and Professional Services

  Create a portfolio site with a blog section using dynamic routes for blog posts, markdown support for content, and a contact form. Leverages Tailwind CSS for styling, shadcn/ui for components, and integrates with a headless CMS for content management.

  Internal Admin Panel for LogisticsLogistics and Supply Chain

  Design an admin panel for logistics management with features like shipment tracking, inventory management, and reporting. Uses Next.js API routes for backend integration, react-query for data fetching, and shadcn/ui for a clean, functional interface.

  Healthcare Appointment Booking SystemHealthcare

  Develop a web app for booking medical appointments, with patient registration, doctor schedules, and notifications. Integrates with authentication APIs, uses Zod for form validation, and ensures responsive design for mobile access.

  💼 Business Models

  Subscription-Based SaaSRecurring monthly/annual fees

  Generate recurring revenue through monthly or annual subscriptions for access to the web application. Includes tiered pricing plans with features like advanced analytics, priority support, and custom integrations.

  E-commerce MarketplaceCommission fees and premium subscriptions

  Earn revenue by taking a commission on sales or charging listing fees for products on the platform. Can include premium features for sellers, such as promoted listings or enhanced storefronts.

  Freemium Model with UpsellsUpfront payments for premium features

  Offer a basic version of the application for free to attract users, then monetize through paid upgrades for advanced features, additional storage, or removal of ads. Targets both individual users and small businesses.

  💬 Integration Tip

  Use shadcn/ui components for consistent UI and axios with react-query for efficient API integration; consider enabling optional features like auto-revision for visual feedback during development.