Como executar um frontend e uma API em conjunto num só desafio de código
Define cada parte como um serviço no kendor.yaml com a sua pasta, comandos e porta, escolhe o serviço de pré-visualização e encaminha caminhos como /api para a API.
Um desafio pode executar vários processos em paralelo, como um frontend React e uma API. Dá a cada
um uma entrada em services no kendor.yaml com a sua pasta (workDir), comandos e porta, indica
qual a que a pré-visualização mostra em preview.service, e adiciona routing para que os pedidos a /api cheguem à API
e todo o resto chegue ao frontend. Todos os serviços correm na mesma sandbox.
Um exemplo completo
Um repositório com um frontend Vite em web/ e uma API Express em api/, com 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: apiComo os serviços arrancam
- As bases de dados arrancam primeiro.
- O
installde topo corre uma vez na raiz do workspace, se existir. - Cada serviço executa os seus próprios comandos
installemworkDire depois o seu comandodev.
Cada serviço tem a sua própria janela de processo, com o nome do serviço, e aparece na vista Processos, onde o candidato pode parar, iniciar e reiniciar.
workDir
workDir é a pasta em que correm os comandos de instalação, dev e teste de um serviço, relativa à
raiz do workspace. Omite-o para um serviço na raiz. Não pode começar por / nem conter ...
Instalar uma vez ou por serviço
Para pacotes separados, põe npm ci (ou pip install, composer install) no install de cada
serviço. Para um monorepo com um único lockfile na raiz, como um workspace pnpm, usa antes o
install de topo, para que as dependências sejam instaladas uma só 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: webPortas
Dá um dev.port a todos os serviços que servem HTTP. O Kendor define PORT com esse valor e HOST como 0.0.0.0
para o comando dev desse serviço, por isso --port $PORT mantém os dois sincronizados. Dois serviços não podem usar a
mesma porta.
A pré-visualização e o routing
preview.service é o serviço que o painel de pré-visualização do candidato abre. É obrigatório assim que há
mais do que um serviço.
routing mapeia prefixos de caminho no endereço da pré-visualização para serviços. Ganha o prefixo correspondente mais longo,
por isso, com as rotas acima, /api/products vai para api e todos os outros caminhos vão para web. O caminho
não é reescrito: a API recebe /api/products, por isso monta as suas rotas em /api. Como o
frontend e a API partilham um só endereço, o browser faz pedidos da mesma origem e não há CORS
para configurar.
Enquanto algum serviço encaminhado ainda está a arrancar, por exemplo enquanto a API executa as suas migrações, a pré-visualização mostra uma breve página de espera em vez de carregar um frontend cujas primeiras chamadas à API falhariam.
Qualquer serviço com porta pode também ser aberto no seu próprio endereço a partir da vista Processos.
Passar o URL de um serviço a outro
O browser chega à sandbox pelo seu endereço de pré-visualização, não por localhost. O Kendor redireciona a maioria das
chamadas do browser para http://localhost:<port> por ti (vê
localhost na pré-visualização), mas a forma fiável é uma
referência em dev.env.vars:
| Referência | Resolve para |
|---|---|
routing.api.url |
O endereço da pré-visualização mais a rota da API, por exemplo https://<preview-address>/api |
routing.web.url |
O próprio endereço da pré-visualização, já que web está encaminhado em /. A API acima usa-o como APP_URL, para as ligações que constrói de volta para o frontend. |
databases.postgres.url |
O URL de ligação do PostgreSQL |
lit:<text> |
Texto fixo |
O Kendor resolve-as antes de qualquer serviço arrancar, por isso a ordem pela qual os serviços sobem não importa. Uma referência a um serviço que não existe falha a validação quando guardas.
Para chamadas entre servidores dentro da sandbox, http://localhost:3000 continua a funcionar.
publicEnvPrefix
publicEnvPrefix regista quais as variáveis destinadas ao código do browser, como VITE_ no Vite.
O Kendor guarda-o mas hoje não atua sobre ele; o próprio Vite só expõe as variáveis VITE_ ao
bundle.
Frontends Vite
O Vite bloqueia pedidos para nomes de anfitrião que não conhece, o que inclui o endereço de pré-visualização da sandbox.
O plugin @kendordev/vite resolve isso e aponta o hot reload para o endereço certo. Só atua
dentro de uma sandbox do Kendor, por isso é seguro fazer commit dele.
Quando carregas um zip ou importas um repositório com um vite.config na raiz, o Kendor adiciona o
plugin por ti. Para uma app Vite numa subpasta, como web/ acima, adiciona-o tu:
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import kendor from '@kendordev/vite';
export default defineConfig({
plugins: [react(), kendor()],
});Instala-o com npm install -D @kendordev/vite e faz commit do lockfile atualizado.
Testes entre serviços
O separador Testes executa por omissão o test.command do serviço de pré-visualização. Quando os testes estão
noutro serviço, como api acima, define kendor.gradeService com esse serviço. Para executar os testes de
vários serviços, lista-os em kendor.gradeServices; cada um corre no seu próprio workDir e os resultados
aparecem como service › test.