Saltar para o conteúdo
KendorDocs

Como executar um frontend e uma API em conjunto num só desafio de código

Para autores de desafios ·

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:

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

Como os serviços arrancam

  1. As bases de dados arrancam primeiro.
  2. O install de topo corre uma vez na raiz do workspace, se existir.
  3. Cada serviço executa os seus próprios comandos install em workDir e depois o seu comando dev.

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:

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

Portas

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:

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()],
});

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.

Este artigo foi útil?