Saltar al contenido principal

Entorno local

Lo que necesitas​

  • Node 20 o superior (el package.json raíz lo exige; los Dockerfile usan Node 20).
  • Acceso a un proyecto de Supabase, normalmente el de desarrollo.
  • Redis. Si no lo tienes instalado, levántalo con Docker.
  • Una clave de OpenAI si vas a tocar bots.

Primera vez​

# Dependencias de los tres paquetes
npm install
cd backend  && npm install  && cd ..
cd frontend && yarn install && cd ..
cd docs     && yarn install && cd ..

# Configuración
cp .env.example .env

El npm install de la raíz, además de las dependencias, apunta los hooks de git a .githooks/: a partir de ahí se valida el formato del mensaje antes de cada commit. Si te lo saltaste, se activa a mano con git config core.hooksPath .githooks.

Rellena el .env. Las variables imprescindibles para arrancar son las de Supabase, las de Redis y OPENAI_API_KEY si vas a probar bots. La lista completa, con la explicación de cada una, está en Variables de entorno.

Arrancar​

npm run dev          # backend en 3000 y frontend en 3001, en paralelo
npm run dev:backend  # solo backend
npm run dev:frontend # solo frontend

O todo con Docker, incluido Redis:

docker compose up -d

Para trabajar en la documentación:

cd docs
yarn start           # manual de usuario en 3840
yarn start:interno   # documentación técnica en 3841

Comprobaciones antes de subir​

npm run test                # backend (Jest) y frontend (Vitest)
cd frontend && yarn lint    # ESLint
cd docs && yarn gen         # regenerar artefactos de documentación
cd docs && yarn build       # los dos sitios, con enlaces rotos como error
cd docs && yarn coverage    # cobertura de documentación

Los tres últimos son exactamente lo que ejecuta el CI. Si pasan en local, pasan allí.

Cosas que confunden al principio​

El symlink de shared. El build del backend crea backend/node_modules/@xenpia/shared como enlace a dist/shared/src. Está en .gitignore. Si al arrancar te dice que no encuentra @xenpia/shared, ejecuta npm run build en el backend una vez.

Backend con npm, frontend con yarn. No es un capricho: son lockfiles distintos. Usa el gestor que corresponde a cada carpeta o romperás el lockfile del otro.

Los webhooks no llegan a tu máquina. Meta y Telegram necesitan una URL pública con HTTPS. Para probar canales en local hace falta un túnel, o usar el modo sandbox de canales compartidos. Ver Canales en pruebas.

El embedded signup de Meta exige HTTPS. Desde http://localhost no funciona, sin excepción.