Construye una app Next.js full-stack en un día con Claude Code como copiloto

Qué vamos a construir

Una aplicación de gestión de tareas (to-do app, pero la versión real): Next.js 15, Supabase como base de datos y autenticación, y deploy en Vercel. Parece simple, pero incluye todo lo que una app real necesita: auth, CRUD, validación, manejo de errores y UI responsive.

El objetivo no es solo el resultado — es aprender el workflow de trabajar con Claude Code en un proyecto real de principio a fin.

Prerrequisitos

Claude Code instalado y autenticado
Node.js 18+ instalado
Cuenta gratuita en Supabase (supabase.com)
Cuenta gratuita en Vercel (vercel.com)
Git instalado

Fase 1 — Arrancar el proyecto (10 minutos)

Crea el proyecto Next.js:

npx create-next-app@latest mi-taskapp --typescript --tailwind --app --src-dir
cd mi-taskapp
claude

Ahora dale el contexto inicial a Claude Code:

Estoy construyendo una app de gestión de tareas con Next.js 15 App Router,
TypeScript y Tailwind CSS v4. Voy a usar Supabase para la base de datos
y autenticación. El objetivo es tener algo funcional en producción hoy.

Primero, crea el archivo CLAUDE.md con las convenciones básicas del proyecto.

Fase 2 — Configurar Supabase (15 minutos)

Ve a supabase.com, crea un proyecto nuevo y copia las variables de entorno. Luego:

Configura Supabase en este proyecto:
1. Instala @supabase/supabase-js y @supabase/ssr
2. Crea el cliente de Supabase para Server Components y Client Components
3. Configura el middleware para manejar la sesión de auth
4. Crea el archivo .env.local.example con las variables necesarias

Las variables de Supabase son:
NEXT_PUBLIC_SUPABASE_URL=tu_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=tu_key

Fase 3 — Base de datos y tipos (20 minutos)

Diseña el schema de base de datos para una app de tareas:
- Tabla: tasks (id, user_id, title, description, completed, priority, created_at, updated_at)
- priority debe ser: 'low' | 'medium' | 'high'
- Incluye Row Level Security para que los usuarios solo vean sus tareas

Genera:
1. El SQL para crear las tablas (lo ejecutaré en Supabase)
2. Los tipos TypeScript correspondientes en src/lib/types.ts
3. Las funciones de acceso a datos en src/lib/tasks.ts

Fase 4 — Autenticación (20 minutos)

Implementa el flujo completo de autenticación con Supabase:
1. Página de login en /login con email + password
2. Página de registro en /register
3. Callback de auth en /auth/callback (requerido por Supabase)
4. Protección de rutas: redirigir a /login si no hay sesión
5. Botón de logout en el header

Usa Server Actions para el login y registro, no Client Components.
El diseño debe ser limpio y funcional con Tailwind.

Fase 5 — CRUD de tareas (30 minutos)

Implementa la página principal de la app en /dashboard:

1. Lista de tareas del usuario autenticado (ordenadas por created_at DESC)
2. Formulario para crear nueva tarea (título, descripción opcional, prioridad)
3. Marcar tarea como completada con un checkbox
4. Eliminar tarea con confirmación
5. Filtrar por: todas | pendientes | completadas | alta prioridad

Usa Server Actions para todas las mutaciones.
Las tareas completadas deben mostrarse con tachado y opacidad reducida.
Indicador visual de prioridad: 🔴 alta | 🟡 media | 🟢 baja

Fase 6 — Deploy en Vercel (10 minutos)

Prepara el proyecto para deploy en Vercel:
1. Asegúrate de que npm run build pasa sin errores
2. Crea el archivo .gitignore correcto si no existe
3. Dime exactamente qué variables de entorno tengo que configurar en Vercel
4. ¿Hay alguna configuración especial en next.config.ts necesaria?

Luego ve a vercel.com, importa el repositorio y añade las variables de entorno. Vercel detectará Next.js automáticamente.

Lo que aprendiste trabajando así

El workflow que acabas de usar — dar instrucciones con objetivo y contexto, dejar que Claude Code explore, verificar que los tests pasan — es el mismo que funciona para proyectos de cualquier tamaño. La app de tareas es simple, pero las técnicas escalan.

El siguiente tutorial lleva este workflow al trabajo en equipo: branches, code review automatizado y PRs.