Saltar a contenido

Frontend en local

Guía práctica para levantar el frontend de Camarero IA (Next.js + React) en tu máquina, apuntarlo al backend local y regenerar los tipos de la API.

El frontend vive en frontend/. Es una app Next.js 16 con React 19, gestor de estado Zustand y UI sobre Radix UI + Tailwind CSS 4.

Esta NO es la versión de Next.js que conoces

frontend/package.json fija next en ^16.2.9, una versión con breaking changes respecto a versiones anteriores: APIs, convenciones y estructura de ficheros pueden diferir. Antes de escribir o modificar código, lee la guía correspondiente en node_modules/next/dist/docs/ y atiende a los avisos de deprecación. Ver frontend/AGENTS.md.

Requisitos previos

  • Node.js: entorno probado con v20.x (LTS).
  • El backend corriendo en local en http://localhost:8000. Ver Backend en local.

1. Instalar dependencias

Desde la carpeta frontend/:

cd frontend
npm install

2. Configurar variables de entorno

Copia el fichero de ejemplo y ajusta los valores:

cp .env.example .env

Variables relevantes (frontend/.env.example):

Variable Valor por defecto (local) Para qué sirve
NEXT_PUBLIC_API_URL http://localhost:8000/api/v1 URL base del backend que consume el frontend.
NEXT_PUBLIC_APP_URL http://localhost:3000 URL pública de la app (metadata y OG images).

Cómo se resuelve la URL de la API

La lógica está en frontend/lib/config/api.ts (getApiBaseUrl()). El orden de resolución es:

  1. Si existe NEXT_PUBLIC_API_URL (variable de build), se usa esa.
  2. En navegador, si el hostname contiene camarero-demo.n0idea.app, apunta a https://api.camarero-demo.n0idea.app/api/v1.
  3. En navegador, en otros despliegues, usa el mismo origen: ${window.location.origin}/api/v1.
  4. Por defecto (desarrollo): http://localhost:8000/api/v1.

En local basta con el valor por defecto

Si tu backend está en http://localhost:8000, no necesitas tocar NEXT_PUBLIC_API_URL: el fallback ya apunta ahí. Define la variable solo si tu backend escucha en otro host/puerto.

El prefijo /api/v1 va incluido

NEXT_PUBLIC_API_URL debe incluir el sufijo /api/v1. No pongas solo el host.

3. Levantar el servidor de desarrollo

npm run dev

El script dev de frontend/package.json es:

NODE_OPTIONS=--max-old-space-size=3072 next dev

Por qué --max-old-space-size=3072

El script eleva el límite de heap de Node a 3072 MB para que el dev server no se quede sin memoria durante la compilación. Si arrancas Next.js de otra forma, replica esa variable de entorno.

La app queda disponible en http://localhost:3000.

4. Codegen de tipos de la API

Los tipos TypeScript de la API se generan a partir del snapshot OpenAPI del backend con openapi-typescript. No se editan a mano.

npm run codegen

El script codegen de frontend/package.json es:

openapi-typescript ${OPENAPI_SNAPSHOT:-../backend/tests/contract/openapi_snapshot.json} -o lib/api/generated/openapi.d.ts

Esto:

  • Lee el snapshot OpenAPI del backend (por defecto backend/tests/contract/openapi_snapshot.json, relativo a frontend/).
  • Escribe los tipos en frontend/lib/api/generated/openapi.d.ts.

Puedes apuntar a otro snapshot sobreescribiendo la variable OPENAPI_SNAPSHOT:

OPENAPI_SNAPSHOT=/ruta/a/otro/openapi.json npm run codegen

Cuándo regenerar los tipos

Ejecuta npm run codegen cada vez que el contrato del backend cambie (nuevo endpoint o campo). El contrato OpenAPI/SSE admite adiciones aditivas siempre que backend y frontend viajen en el mismo cambio: si tocas el contrato, regeneras el snapshot y cableas aquí el consumo. Ver backend/AGENTS.md (sección de contrato).

Otros scripts útiles

Definidos en frontend/package.json:

Comando Qué hace
npm run dev Servidor de desarrollo (con el límite de heap ampliado).
npm run build Build de producción (next build).
npm run start Sirve el build de producción (next start).
npm run lint Linter (eslint).
npm run test Tests unitarios (vitest run).
npm run codegen Regenera los tipos de la API desde el snapshot OpenAPI.

Páginas relacionadas