🚀 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

Comando	Descripción
`/explorador`	Explora codebase y arquitectura
`/ejecutar-prp`	Ejecuta PRPs (features complejas)
`/generar-prp`	Genera nuevo PRP
`/preparar-paralelo`	Prepara tareas paralelas
`/ejecutar-paralelo`	Ejecuta en paralelo

Agentes Especializados

Codebase Analyst - Analiza arquitectura y patrones
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/supabase.ts:

import { createClient } from '@supabase/supabase-js'

export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

3. Crear Migraciones

# Guardar migraciones en supabase/migrations/
# Ejemplo: supabase/migrations/001_create_users.sql

🧪 Testing Strategy

Unit Tests

// src/features/auth/hooks/useAuth.test.ts
import { renderHook } from '@testing-library/react'
import { useAuth } from './useAuth'

test('should authenticate user', async () => {
  const { result } = renderHook(() => useAuth())
  await result.current.login('[email protected]', 'password')
  expect(result.current.user).toBeDefined()
})

Run Tests

npm run test                    # Run all tests
npm run test:watch              # Watch mode
npm run test:coverage           # Coverage report

🎯 Best Practices

Component Structure

// ✅ GOOD: Clear props, typed, documented
interface ButtonProps {
  children: React.ReactNode
  variant?: 'primary' | 'secondary'
  onClick: () => void
}

export function Button({ children, variant = 'primary', onClick }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      className={`btn btn-${variant}`}
    >
      {children}
    </button>
  )
}

Feature Organization

// ✅ GOOD: Todo relacionado en un lugar
src/features/auth/
├── components/     # UI específicos de auth
├── hooks/          # Lógica de auth
├── services/       # API calls
├── types/          # Types de auth
└── store/          # Estado de auth

📚 Documentación

CLAUDE.md - System prompt completo (la fuente de verdad)
.claude/prompts/ - Metodologías y patrones
.claude/PRPs/templates/ - Templates para features
.claude/skills/ - Skills reutilizables

🚨 Troubleshooting

Puerto Ocupado (EADDRINUSE)

# El auto-port detection debería resolver esto
# Si persiste:
lsof -i :3000
kill -9 <PID>

# O usa el script directamente:
node scripts/dev-server.js

TypeScript Errors

npm run typecheck          # Verificar errores
rm -rf .next               # Limpiar cache
npm install                # Reinstalar deps

Tests Failing

npm run test -- --clearCache    # Limpiar cache de Jest
npm run test -- --verbose       # Ver detalles

🎯 Próximos Pasos

Lee CLAUDE.md - Principios y convenciones completas
Configura Supabase - Auth + Database
Crea tu primera feature - Usa /generar-prp
Implementa autenticación - Feature auth incluida
Deploy - Vercel/Netlify ready

🤝 Contribuir

Este template está diseñado para ser extendido. Algunas ideas:

[ ] Añadir más features base (notifications, settings)
[ ] Crear más skills específicos
[ ] Mejorar PRPs templates
[ ] Añadir más tests de ejemplo

📦 Deploy

Vercel (Recomendado)

npm install -g vercel
vercel

Configurar Variables de Entorno

En tu dashboard de Vercel, añade:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY

Next.js + Claude Code Setup v1.0 | Built with AI-first development in mind 🤖