🚀 Next.js + Claude Code - Frontend Setup

Setup completo de Next.js 16 + Supabase + Claude Code listo para producción. Arquitectura Feature-First optimizada para desarrollo asistido por IA.

🎯 ¿Qué es esto?

Un template production-ready para aplicaciones frontend modernas con:

• ✅ Next.js 16 (App Router) + TypeScript
• ✅ Supabase (Database + Auth)
• ✅ Tailwind CSS + shadcn/ui
• ✅ Claude Code con comandos, agentes y skills
• ✅ Arquitectura Feature-First optimizada para IA
• ✅ Auto port detection (3000-3006)
• ✅ Testing, linting y type checking configurados

📦 Tech Stack

Runtime: Node.js + TypeScript
Framework: Next.js 16 (App Router)
Database: PostgreSQL/Supabase
Styling: Tailwind CSS
State: Zustand
Testing: Jest + React Testing Library
Validation: Zod
AI Tooling: Claude Code + MCPs

🏗️ Arquitectura Feature-First

src/
├── app/                      # Next.js App Router
│   ├── (auth)/              # Rutas auth (grupo)
│   ├── (main)/              # Rutas principales
│   ├── layout.tsx
│   └── page.tsx
│
├── features/                 # 🎯 Organizadas por funcionalidad
│   ├── auth/
│   │   ├── components/      # LoginForm, SignupForm
│   │   ├── hooks/           # useAuth, useSession
│   │   ├── services/        # authService.ts
│   │   ├── types/           # User, Session
│   │   └── store/           # authStore.ts
│   │
│   ├── dashboard/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types/
│   │
│   └── [tu-feature]/
│
└── shared/                   # Código reutilizable
    ├── components/          # Button, Card, Input
    ├── hooks/               # useDebounce, useLocalStorage
    ├── stores/              # appStore.ts
    ├── types/               # api.ts, domain.ts
    ├── utils/               # helpers
    ├── lib/                 # supabase.ts, axios.ts
    └── constants/

¿Por qué Feature-First? Cada feature tiene TODO lo necesario en un solo lugar. Perfecto para que la IA entienda contexto completo sin navegar múltiples carpetas.

🚀 Quick Start

1. Instalar Dependencias

npm install
# o
pnpm install

2. Configurar Variables de Entorno

# Crear .env.local
cp .env.example .env.local

# Editar con tus credenciales de Supabase
NEXT_PUBLIC_SUPABASE_URL=tu_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=tu_anon_key

3. Configurar MCPs (Opcional)

Edita .mcp.json con tu project ref de Supabase:

{
  "mcpServers": {
    "supabase": {
      "args": ["--project-ref=TU_PROJECT_REF"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "TU_TOKEN"
      }
    }
  }
}

4. Iniciar Desarrollo

npm run dev
# Auto-detecta puerto disponible (3000-3006)

🛠️ Comandos Disponibles

Development

npm run dev          # Servidor desarrollo (auto-port 3000-3006)
npm run build        # Build para producción
npm run start        # Servidor producción

Quality Assurance

npm run test         # Tests con Jest
npm run test:watch   # Tests en modo watch
npm run lint         # ESLint
npm run lint:fix     # Fix automático
npm run typecheck    # TypeScript check

Skills Management

# Crear nuevo skill
python .claude/skills/skill-creator/scripts/init_skill.py my-skill

# Validar skill
python .claude/skills/skill-creator/scripts/quick_validate.py ./my-skill

# Empaquetar skill
python .claude/skills/skill-creator/scripts/package_skill.py ./my-skill

🤖 Claude Code Integration

Comandos Disponibles

Agentes Especializados

1. Codebase Analyst - Analiza arquitectura y patrones
2. Gestor Documentación - Mantiene docs actualizados

MCPs Configurados

• Chrome DevTools - Control de navegador para bucle agéntico visual
• Supabase - Integración directa con DB

🎨 Bucle Agéntico con Playwright

Este setup incluye integración con Playwright MCP para desarrollo visual:

1. Implementar componente
2. Capturar screenshot automático
3. Comparar vs requirements
4. Iterar hasta pixel-perfect

Lee .claude/prompts/bucle-agentico.md para más detalles.

📝 Crear tu Primera Feature

Opción 1: Manual

mkdir -p src/features/mi-feature/{components,hooks,services,types,store}

Opción 2: Con PRP

# En Claude Code, ejecuta:
/generar-prp

# Describe tu feature, el agente generará:
# - Estructura completa
# - Componentes base
# - Hooks necesarios
# - Types + validaciones
# - Tests

🔒 Supabase Setup

1. Crear Proyecto en Supabase

# Visita: https://supabase.com/dashboard
# Crea nuevo proyecto
# Copia URL y Anon Key

2. Configurar Cliente

El cliente ya está configurado en `src/shared/lib/

...