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

Optional Features (user can decline)

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

#### 2. Live Preview Server (requires Nginx)

  # /etc/nginx/sites-available/
  server {
    listen ;  # 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;
    }
  }
  

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

Common Project Types

Quick reference for typical requests:

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

Tech Stack

Core:

API Integration (default):

Optional (based on needs):

Project Structure

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

/
├── 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:

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:

Step 1: Project Setup

Create Next.js project:

npx create-next-app@latest  \
  --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 
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: '',
  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 
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:

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 (
    
      {children}
      
    
  );
}

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(/users/${id});
      return data;
    },
  });
};
export const useUpdateUser = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (user: Partial) => {
      const { data } = await api.patch(/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 
Loading...
;
  if (error) return 
Error: {error.message}
;
  return (
    

      
{user?.name}
      
{user?.email}
    
  );
}

→ 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 Loading...;
  return (
    
      
        

          
            
            {user?.name[0]}
          
          

            {user?.name}
            
{user?.email}
          
        
      
      
        Edit Profile
      
    
  );
}

When to add more components:

→ 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  2>/dev/null || true
Start with PM2 (port 3002 for nginx proxy)
PORT=3002 pm2 start npm --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  --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  --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):

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

Common fixes:

→ 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:

→ Message user: "Documentation complete ✓"

Step 10: Export & Deploy Guidance

Stop PM2 dev server (if running):

pm2 delete  2>/dev/null || true
pm2 save  # Persist PM2 process list

Zip the project:

cd .. && zip -r /tmp/.zip /

Send via message tool with filePath.

Provide deployment options:

→ 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 
Access locally
curl http://localhost:3002

2. Live preview URLs:

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

Option 2: Nginx proxy + external access

Option 3: Export & deploy

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

Typography

Color & Contrast

Responsive Design (Critical)

'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>({
    resolver: zodResolver(formSchema),
    defaultValues: { name: '', email: '' },
  });
  const mutation = useMutation({
    mutationFn: async (data: z.infer) => {
      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 (
    
       mutation.mutate(data))} className="space-y-4">
         (
            
              Name
              
                
              
              
            
          )}
        />
         (
            
              Email
              
                
              
              
            
          )}
        />
        
          {mutation.isPending ? 'Sending...' : 'Send Message'}
        
      
    
  );
}

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

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

# Check what's running
pm2 list
Stop the conflicting process
pm2 delete 
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 "" --cwd "$(pwd)" -- run dev

pm2 list

pm2 logs  --lines 50

pm2 restart 

pm2 stop 

pm2 delete 

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

# Start dev server
pm2 delete  2>/dev/null || true
PORT=3002 pm2 start npm --name "" --cwd "$(pwd)" -- run dev
Check status
pm2 list
pm2 logs 
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

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

# Check what's running
pm2 list
Stop the conflicting process
pm2 delete 
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 "" --cwd "$(pwd)" -- run dev

pm2 list

pm2 logs  --lines 50

pm2 restart 

pm2 stop 

pm2 delete 

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