template-project
Base para proyectos personales: Next.js (App Router) + TypeScript estricto + Tailwind + Supabase SSR + n8n, lista para desplegar en Vercel. Pensada para usarse como GitHub Template (Paso 1.2 de la Hoja de Ruta 2026).
Arranque rápido
npm install
cp .env.example .env.local # completa los valores
npm run dev # http://localhost:3000
Comprueba la configuración en http://localhost:3000/api/health (solo muestra booleanos, nunca valores).
Estructura y responsabilidades
src/
app/ rutas (App Router) y route handlers
api/health/ estado de configuración
api/webhooks/n8n/ webhook ENTRANTE desde n8n (autenticado por secreto)
actions/ Server Actions: capa delgada, devuelven ApiResult
services/ lógica de negocio + cliente SALIENTE a n8n
repositories/ acceso a datos (solo Supabase)
lib/
api/response.ts contrato JSON estándar { ok, data | error } y AppError
supabase/ clientes server / browser / middleware
env.ts validación de variables con zod (perezosa)
types/database.ts tipos de la BD (regenerar con `npm run db:types`)
supabase/migrations/ SQL versionado (RLS activado)
n8n/workflows/ workflows exportados (JSON)
Flujo: Server Action / Route Handler → service → repository → Supabase, y service → n8n.service → webhook n8n. Las capas no se saltan niveles.
Supabase
- Crea el proyecto y copia URL + clave publishable a
.env.local.
- Aplica
supabase/migrations/0001_init.sql (CLI: supabase db push, o el SQL Editor).
- Regenera tipos:
npm run db:types.
La seguridad descansa en RLS (activado en el ejemplo). No uses la service_role en código que llegue al cliente; este template ni siquiera la incluye.
n8n
# define N8N_WEBHOOK_SECRET en tu entorno (openssl rand -hex 32), luego:
npm run n8n:up # http://localhost:5678
Importa n8n/workflows/template-ping.json. Los webhooks usan la cabecera x-webhook-secret en ambos sentidos. El workflow de ejemplo no está probado contra una instancia real; ajústalo si tu versión de n8n difiere.
Usar como GitHub Template
Repo en GitHub → Settings → General → Template repository. Luego Use this template para cada proyecto nuevo, y reemplaza template-project en package.json y layout.tsx.
Despliegue en Vercel
Importa el repo y define las mismas variables de .env.example (Production y Preview). N8N_WEBHOOK_BASE_URL debe apuntar a una instancia n8n accesible desde Internet.
Scripts
| Script | Qué hace |
|---|
npm run dev | servidor de desarrollo |
npm run check | typecheck + lint |
npm run build | build de producción |
npm run db:types | tipos desde Supabase local |
npm run n8n:up / n8n:down | n8n local en Docker |
