← index

DEVELOPMENT

docs/DEVELOPMENT.md

Desarrollo local

Cómo trabajar en Metabolics.app en tu máquina.

Pre-requisitos

  • macOS (probado en Apple Silicon M1/M2/M3)
  • Node 20.19+ (usar nvm o fnm)
  • pnpm 10 (npm install -g pnpm o vía Corepack)
  • Docker Desktop corriendo (lo necesita Supabase CLI)
  • Supabase CLI (brew install supabase/tap/supabase)
  • Drizzle Kit ya viene en devDependencies

Setup inicial

# 1. Clonar e instalar deps
git clone <repo>
cd metabolics-app
pnpm install

# 2. Arrancar Supabase local
pnpm supabase:start
# Esto tarda ~1-2 min la primera vez (baja imágenes Docker)

# 3. Copiar envs
cp .env.example .env

# 4. Copiar las keys de Supabase al .env
pnpm supabase:status
# Copia los valores a .env:
#   PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
#   PUBLIC_SUPABASE_ANON_KEY=<del output>
#   SUPABASE_SERVICE_ROLE_KEY=<del output>
#   DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

# 5. Crear las tablas
pnpm db:push

# 6. (Opcional) Cargar seed data
pnpm supabase:reset
# O aplicar solo el seed:
psql "$(pnpm supabase status --output env | grep DB_URL | cut -d= -f2-)" -f supabase/seed.sql

# 7. Arrancar dev server
pnpm dev
# http://127.0.0.1:5173

URLs locales

Servicio URL Notas
App http://127.0.0.1:5173 SvelteKit dev server
Supabase API http://127.0.0.1:54321 REST + Auth
Supabase Studio http://127.0.0.1:54323 GUI de BD + Auth
Supabase DB 127.0.0.1:54322 Postgres connection
Inbucket (email) http://127.0.0.1:54324 Ver emails de prueba
Drizzle Studio http://localhost:4983 GUI de BD vía Drizzle

Workflow diario

# Trabajar en el schema de BD
# 1. Editar src/lib/server/db/schema.ts
# 2. Aplicar cambios:
pnpm db:push
# 3. Cuando esté OK, generar migration file:
pnpm db:generate
# 4. Commitear

# Trabajar en código
pnpm dev
# Hot reload automático

# Validar antes de commit
pnpm check      # typecheck
pnpm format     # prettier

Debugging

Server logs

pnpm dev muestra logs del server en el terminal. Para filtrar:

pnpm dev 2>&1 | grep -E 'error|warn'

Drizzle Studio

pnpm db:studio
# Abre GUI en http://localhost:4983
# Útil para verificar datos después de tests

Supabase Studio

http://127.0.0.1:54323 (cuando pnpm supabase:start está corriendo)

Permite:

  • Ver tablas y datos
  • Inspeccionar usuarios en Auth
  • Probar queries SQL
  • Ver logs de Postgres

Logs de Supabase

# Logs de Postgres
docker logs supabase_db_metabolics-local

# Logs de Auth
docker logs supabase_auth_metabolics-local

(o usar pnpm supabase:start en otra terminal y leer los logs que imprime)

Reset completo

Si la BD queda en mal estado:

pnpm supabase:stop --no-backup
rm -rf supabase/.branches
pnpm supabase:start
pnpm db:push
pnpm supabase:reset  # opcional, aplica seed

Testing manual (no hay tests automatizados todavía)

Flujo del nutricionista

  1. Crear cuenta en /auth/signup con role=nutritionist
  2. Verificar que redirige a /dashboard
  3. Verificar en Supabase Studio → auth.users y tabla profiles que las filas se crearon
  4. Verificar en nutritionist_profiles y subscriptions que las filas de extensión se crearon

Flujo del paciente

  1. Signup con role=patient → redirige a /home
  2. Intentar acceder a /dashboard → debe redirigir a /auth/forbidden o /auth/login

Auth guard

# Sin sesión, intentar /dashboard
curl -i http://127.0.0.1:5173/dashboard
# Debe responder 303 a /auth/login?next=/dashboard

Estructura de branches (sugerida, no formal)

main              # producción (lo que está deployado)
├── feat/<name>   # features nuevas
├── fix/<name>    # bugfixes
└── chore/<name>  # tareas mecánicas

Conventional commits: NO configurado todavía (decisión del usuario). Si en algún momento se quiere agregar, usar commitlint + husky (ver Roadmap post-MVP abajo).

Agregar shadcn-svelte components

pnpm dlx shadcn-svelte@latest add dialog
# Crea src/lib/components/ui/dialog.svelte
# Actualiza src/lib/components/ui/index.ts (agregar a mano)

Componentes comunes a agregar pronto: dialog, dropdown-menu, select, textarea, toast, tabs, table.

Agregar tablas al schema

  1. Editar src/lib/server/db/schema.ts
  2. Si la tabla necesita enums, agregarlos arriba
  3. Si tiene FK a otras tablas, usar la función (): AnyPgColumn => profiles.id para referencias circulares
  4. Agregar relations
  5. Exportar el tipo typeof newTable.$inferSelect
  6. pnpm db:push para aplicar
  7. Cuando esté OK, pnpm db:generate para commitear la migration

Troubleshooting

"Cannot connect to the Docker daemon"

Docker Desktop no está corriendo. Abrir Docker.app.

"Port 54321 already in use"

Hay otro Supabase local corriendo. pnpm supabase:stop o identificar el proceso.

"ECONNREFUSED 127.0.0.1:54322"

Supabase no arrancó bien. pnpm supabase:status para ver el estado. Si los containers están caídos, pnpm supabase:stop && pnpm supabase:start.

"Module not found: Can't resolve '$lib/...'"

TypeScript no regeneró el .svelte-kit/tsconfig.json. Correr pnpm dev una vez o pnpm dlx svelte-kit sync.

Cambios al schema no se reflejan

  1. pnpm db:push (aplica cambios)
  2. Si sigue sin reflejar, pnpm supabase:stop && pnpm supabase:start && pnpm db:push

Form no valida con Zod

sveltekit-superforms requiere que el defaultValues esté en el +page.svelte y que el +page.server.ts retorne superValidate(form, schema). Ver el patrón en auth/login/+page.svelte y auth/login/+page.server.ts.

Roadmap post-MVP (cuando se decida)

  • Tests: Vitest para unit, Playwright para e2e
  • CI/CD: GitHub Actions con typecheck + lint + build en cada PR
  • Git hooks: husky + lint-staged + commitlint (conventional commits)
  • Service worker / PWA manifest
  • Realtime: Supabase channels para chat
  • Background jobs: BullMQ + Redis para emails, generación de PDFs