frontend-nextjs

name	frontend-nextjs
description	Next.js App Router + TypeScript + Tailwind + shadcn/ui setup, folder layout, and patterns (component size, mobile-first, Zustand when needed). Use for web app/service projects using Next.js — not for Python-only stacks. Trigger: .tsx/.ts, next.config, new web UI.

Frontend — Next.js + Tailwind + shadcn/ui

Web app/service only. Do not apply to Python-only projects. Verify stack matches PROJECT_RULES.md. Record architecture decisions in docs/ai-dev/.

Initial Setup

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir
cd my-app
npx shadcn@latest init
npx shadcn@latest add button card input dialog toast

Directory Structure

src/
├── app/
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Home page
│   ├── globals.css         # Tailwind + custom styles
│   └── {feature}/
│       └── page.tsx        # Feature pages
├── components/
│   ├── ui/                 # shadcn/ui (auto-generated)
│   └── {feature}/          # Feature-specific components
├── lib/
│   └── utils.ts            # Utilities (cn function, etc.)
└── types/
    └── index.ts            # Shared types

Key Patterns

• One component = max 150 lines. Split if exceeded
• Check shadcn/ui first, build custom only if needed
• Props: define with TypeScript interfaces
• State: useState first, Zustand if complex
• HTTP requests: use built-in fetch only. Do NOT install Axios

Tailwind Patterns

// Responsive
<div className="px-4 md:px-8 lg:px-16">
  <h1 className="text-2xl md:text-4xl font-bold">Title</h1>
</div>

// Dark mode
<div className="bg-white dark:bg-gray-900">

// Card grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {items.map(item => <Card key={item.id}>...</Card>)}
</div>

ESLint

Next.js includes ESLint by default. After each feature:

npx eslint .

Fix all errors before committing. Never use // eslint-disable without a documented reason.

Building Pages

1. Create src/app/{path}/page.tsx
2. Install needed shadcn/ui components
3. Build in order: layout -> components -> data connection
4. Mobile first, expand with md: lg: prefixes
5. ESLint pass (npx eslint . — zero errors)