Cómo ejecutar un frontend y una API juntos en un mismo reto de código
Define cada parte como un servicio en kendor.yaml con su propia carpeta, comandos y puerto, elige el servicio de la vista previa y enruta rutas como /api a la API.
Un reto puede ejecutar varios procesos a la vez, como un frontend de React y una API. Dale a cada
uno una entrada en services dentro de kendor.yaml con su carpeta (workDir), sus comandos y su
puerto, indica en preview.service cuál muestra la vista previa y añade routing para que las
peticiones a /api lleguen a la API mientras todo lo demás llega al frontend. Todos los servicios
se ejecutan en el mismo sandbox.
Un ejemplo completo
Un repositorio con un frontend de Vite en web/ y una API de Express en api/, con PostgreSQL:
version: 1
runtime:
type: node
version: "22"
databases:
- type: postgres
version: "18"
init: api/db/seed.sql
services:
api:
workDir: api
install:
commands:
- npm ci
dev:
command: node --watch src/server.js
port: 3000
env:
vars:
APP_URL: routing.web.url
test:
command: node --test
web:
workDir: web
install:
commands:
- npm ci
dev:
command: npm run dev -- --port $PORT
port: 5173
env:
vars:
VITE_API_URL: routing.api.url
publicEnvPrefix: VITE_
preview:
service: web
routing:
- path: /api
service: api
- path: /
service: web
kendor:
gradeService: apiCómo arrancan los servicios
- Primero arrancan las bases de datos.
- El
installde nivel superior se ejecuta una vez en la raíz del workspace, si lo hay. - Cada servicio ejecuta sus propios comandos
installen suworkDiry luego su comandodev.
Cada servicio recibe su propia ventana de proceso, con el nombre del servicio, y aparece en la vista Procesos, donde el candidato puede detenerlo, iniciarlo y reiniciarlo.
workDir
workDir es la carpeta en la que se ejecutan los comandos de instalación, desarrollo y tests de un
servicio, relativa a la raíz del workspace. Omítelo para un servicio en la raíz. No puede empezar
por / ni contener ...
Instalar una vez o por servicio
Para paquetes independientes, pon npm ci (o pip install, composer install) en el install de
cada servicio. Para un monorepo con un único lockfile en la raíz, como un workspace de pnpm, usa en
su lugar el install de nivel superior, de modo que las dependencias se instalen una sola vez:
version: 1
runtime:
type: node
version: "22"
install:
commands:
- pnpm install --frozen-lockfile
services:
api:
workDir: apps/api
dev:
command: pnpm dev
port: 3000
web:
workDir: apps/web
dev:
command: pnpm dev --port $PORT
port: 5173
preview:
service: web
routing:
- path: /api
service: api
- path: /
service: webPuertos
Dale un dev.port a cada servicio que sirva HTTP. Kendor define PORT con ese valor y HOST como
0.0.0.0 para el comando de desarrollo de ese servicio, de modo que --port $PORT mantiene ambos
sincronizados. Dos servicios no pueden usar el mismo puerto.
La vista previa y el enrutamiento
preview.service es el servicio que abre el panel de vista previa del candidato. Es obligatorio en
cuanto hay más de un servicio.
routing asigna prefijos de ruta de la dirección de la vista previa a servicios. Gana el prefijo
coincidente más largo, así que con las rutas anteriores, /api/products va a api y cualquier otra
ruta va a web. La ruta no se reescribe: la API recibe /api/products, así que monta sus rutas
bajo /api. Como el frontend y la API comparten una sola dirección, el navegador hace peticiones
del mismo origen y no hay que configurar CORS.
Mientras algún servicio enrutado sigue arrancando, por ejemplo mientras la API ejecuta sus migraciones, la vista previa muestra una breve página de espera en lugar de cargar un frontend cuyas primeras llamadas a la API fallarían.
Cualquier servicio con puerto también se puede abrir en su propia dirección desde la vista Procesos.
Pasa la URL de un servicio a otro
El navegador llega al sandbox a través de su dirección de vista previa, no de localhost. Kendor
redirige por ti la mayoría de las llamadas del navegador a http://localhost:<port> (consulta
localhost en la vista previa), pero la forma fiable es
una referencia en dev.env.vars:
| Referencia | Se resuelve en |
|---|---|
routing.api.url |
La dirección de la vista previa más la ruta de la API, por ejemplo https://<preview-address>/api |
routing.web.url |
La propia dirección de la vista previa, ya que web está enrutado en /. La API anterior la usa como APP_URL, para los enlaces que construye de vuelta al frontend. |
databases.postgres.url |
La URL de conexión de PostgreSQL |
lit:<text> |
Texto fijo |
Kendor resuelve esto antes de que arranque ningún servicio, así que el orden en que se levantan los servicios no importa. Una referencia a un servicio que no existe falla la validación al guardar.
Para las llamadas de servidor a servidor dentro del sandbox, http://localhost:3000 sigue
funcionando.
publicEnvPrefix
publicEnvPrefix registra qué variables están pensadas para el código del navegador, como VITE_
en Vite. Kendor lo guarda pero hoy no actúa en consecuencia; el propio Vite solo expone al bundle
las variables VITE_.
Frontends con Vite
Vite bloquea las peticiones a nombres de host que no conoce, lo que incluye la dirección de vista
previa del sandbox. El plugin @kendordev/vite lo soluciona y apunta la recarga en caliente a la
dirección correcta. Solo actúa dentro de un sandbox de Kendor, así que es seguro incluirlo en el
commit.
Cuando subes un zip o importas un repositorio con un vite.config en la raíz, Kendor añade el
plugin por ti. Para una aplicación de Vite en una subcarpeta, como web/ arriba, añádelo tú:
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import kendor from '@kendordev/vite';
export default defineConfig({
plugins: [react(), kendor()],
});Instálalo con npm install -D @kendordev/vite y haz commit del lockfile actualizado.
Tests entre servicios
La pestaña Tests ejecuta por defecto el test.command del servicio de la vista previa. Cuando
los tests están en otro servicio, como api arriba, define kendor.gradeService con ese servicio.
Para ejecutar los tests de varios servicios, enuméralos en kendor.gradeServices; cada uno se
ejecuta en su propio workDir y los resultados aparecen como service › test.