Come eseguire un frontend e un'API insieme in un'unica sfida di codice
Definisci ogni parte come servizio in kendor.yaml con la sua cartella, i suoi comandi e la sua porta, scegli il servizio di anteprima e instrada percorsi come /api verso l'API.
Una sfida può eseguire più processi affiancati, come un frontend React e un'API. Dai a ciascuno una
voce sotto services in kendor.yaml con la sua cartella (workDir), i suoi comandi e la sua porta,
indica in preview.service quello che mostra l'anteprima e aggiungi routing in modo che le richieste
a /api raggiungano l'API mentre tutto il resto raggiunge il frontend. Ogni servizio gira nella
stessa sandbox.
Un esempio completo
Un repository con un frontend Vite in web/ e un'API Express in 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: apiCome partono i servizi
- Partono prima i database.
- L'
installdi primo livello viene eseguito una volta nella radice del workspace, se presente. - Ogni servizio esegue i propri comandi
installnel suoworkDir, poi il suo comandodev.
Ogni servizio ha una propria finestra di processo, con il nome del servizio, e compare nella vista Processi, dove il candidato può fermarlo, avviarlo e riavviarlo.
workDir
workDir è la cartella in cui vengono eseguiti i comandi di installazione, di sviluppo e di test di
un servizio, relativa alla radice del workspace. Omettilo per un servizio nella radice. Non può
iniziare con / né contenere ...
Installare una volta o per servizio
Per pacchetti separati, metti npm ci (o pip install, composer install) nell'install di ogni
servizio. Per un monorepo con un solo lockfile nella radice, come un workspace pnpm, usa invece
l'install di primo livello, così le dipendenze vengono installate una sola volta:
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: webPorte
Dai un dev.port a ogni servizio che serve HTTP. Kendor imposta PORT su quel valore e HOST su
0.0.0.0 per il comando dev di quel servizio, quindi --port $PORT mantiene i due allineati. Due
servizi non possono usare la stessa porta.
L'anteprima e il routing
preview.service è il servizio che il riquadro di anteprima del candidato apre. È obbligatorio non
appena c'è più di un servizio.
routing associa i prefissi di percorso sull'indirizzo dell'anteprima ai servizi. Vince il prefisso
corrispondente più lungo, quindi con le route qui sopra /api/products va ad api e ogni altro
percorso va a web. Il percorso non viene riscritto: l'API riceve /api/products, quindi monta le
sue route sotto /api. Poiché frontend e API condividono un unico indirizzo, il browser fa richieste
same-origin e non c'è alcun CORS da configurare.
Finché un servizio instradato sta ancora partendo, ad esempio mentre l'API esegue le sue migrazioni, l'anteprima mostra una breve pagina di attesa invece di caricare un frontend le cui prime chiamate all'API fallirebbero.
Qualsiasi servizio con una porta può anche essere aperto al proprio indirizzo dalla vista Processi.
Passare l'URL di un servizio a un altro
Il browser raggiunge la sandbox tramite il suo indirizzo di anteprima, non tramite localhost. Kendor
reindirizza per te la maggior parte delle chiamate del browser a http://localhost:<port> (vedi
localhost nell'anteprima), ma il modo affidabile è un
riferimento in dev.env.vars:
| Riferimento | Si risolve in |
|---|---|
routing.api.url |
L'indirizzo dell'anteprima più la route dell'API, ad esempio https://<preview-address>/api |
routing.web.url |
L'indirizzo dell'anteprima stesso, poiché web è instradato su /. L'API qui sopra lo usa come APP_URL, per i link che costruisce verso il frontend. |
databases.postgres.url |
L'URL di connessione PostgreSQL |
lit:<text> |
Testo fisso |
Kendor risolve questi riferimenti prima che parta qualsiasi servizio, quindi l'ordine in cui i servizi si avviano non conta. Un riferimento a un servizio che non esiste non supera la validazione quando salvi.
Per le chiamate da server a server dentro la sandbox, http://localhost:3000 funziona comunque.
publicEnvPrefix
publicEnvPrefix registra quali variabili sono destinate al codice del browser, come VITE_ per Vite.
Kendor lo memorizza ma oggi non ne tiene conto; Vite stesso espone al bundle solo le variabili VITE_.
Frontend Vite
Vite blocca le richieste per i nomi host che non conosce, tra cui l'indirizzo di anteprima della
sandbox. Il plugin @kendordev/vite risolve il problema e punta l'hot reload all'indirizzo giusto.
Agisce solo dentro una sandbox Kendor, quindi si può committare senza problemi.
Quando carichi uno zip o importi un repository con un vite.config nella radice, Kendor aggiunge il
plugin per te. Per un'app Vite in una sottocartella, come web/ qui sopra, aggiungilo tu:
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import kendor from '@kendordev/vite';
export default defineConfig({
plugins: [react(), kendor()],
});Installalo con npm install -D @kendordev/vite e committa il lockfile aggiornato.
Test su più servizi
La scheda Test esegue per impostazione predefinita il test.command del servizio di anteprima.
Quando i test si trovano in un altro servizio, come api qui sopra, imposta kendor.gradeService su
quel servizio. Per eseguire i test di più servizi, elencali in kendor.gradeServices; ciascuno viene
eseguito nel proprio workDir e i risultati compaiono come service › test.