Vai al contenuto
KendorDocs

Come eseguire un frontend e un'API insieme in un'unica sfida di codice

Per chi crea le sfide ·

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:

kendor.yaml
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: api

Come partono i servizi

  1. Partono prima i database.
  2. L'install di primo livello viene eseguito una volta nella radice del workspace, se presente.
  3. Ogni servizio esegue i propri comandi install nel suo workDir, poi il suo comando dev.

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:

kendor.yaml
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: web

Porte

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:

web/vite.config.js
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.

Questo articolo ti è stato utile?