Começar

Este guia coloca o runtime rodando localmente e serve um app minúsculo a partir de um worker. Você vai precisar do Bun 1.3+ instalado.

Rode o monorepo

1. Clone e instale:

   git clone https://github.com/djalmajr/buntime.git
   cd buntime
   bun install

2. Suba a stack de desenvolvimento completa — runtime, os plugins do núcleo e o painel do operador (cpanel) — a partir da raiz do repositório:

   bun dev

   Isso roda o runtime com --watch. Use bun --watch, nunca bun --hot: o modo hot quebra timers/cron e vaza bindings de porta.

3. Confirme que está no ar:

   curl http://localhost:8000/api/health

Dica

A UI do operador (cpanel) é servida na raiz assim que o plugin gateway é carregado — abra http://localhost:8000/ no navegador.

Publique seu primeiro worker

Um “worker app” é apenas um diretório com um entrypoint. O runtime o descobre a partir dos diretórios listados em RUNTIME_WORKER_DIRS (estilo PATH, separados por :).

1. Crie um diretório de app. O layout plano e versionado é o mais simples:

   • Directoryapps/

     • Directoryhello@1.0.0/

       • index.ts
       • manifest.yaml

2. Escreva o entrypoint. Um worker exporta um objeto default — um handler fetch é a forma mais simples:

   // apps/hello@1.0.0/index.ts
   export default {
     fetch(req: Request) {
       const url = new URL(req.url);
       return Response.json({ hello: "world", path: url.pathname });
     },
   };

3. (Opcional) Descreva como o worker roda. Sem manifest, os padrões se aplicam (descoberta efêmera, timeout de 30s):

   # apps/hello@1.0.0/manifest.yaml
   entrypoint: index.ts
   ttl: 0          # 0 = efêmero (criado por requisição); >0 mantém aquecido
   timeout: 30s
   maxRequests: 1000

4. Aponte o runtime para o diretório e inicie:

   RUNTIME_WORKER_DIRS=./apps bun --watch apps/runtime/src/index.ts

5. Chame seu app. Um worker sem escopo chamado hello é servido em /hello/:

   curl http://localhost:8000/hello/
   # {"hello":"world","path":"/"}

Escolha como o worker roda

O campo ttl define a personalidade do worker:

Efêmero (ttl: 0)

Criado a cada requisição e descartado em seguida. Maior latência por requisição, custo zero em idle. Melhor para handlers stateless, estilo lambda. A concorrência é limitada por RUNTIME_EPHEMERAL_CONCURRENCY (padrão 2); o excedente entra em fila até RUNTIME_EPHEMERAL_QUEUE_LIMIT (padrão 100), depois retorna 503.

Persistente (ttl > 0)

Mantido aquecido e reutilizado. O TTL é deslizante — reinicia a cada requisição, então o worker vive enquanto o tráfego continuar chegando (ou até maxRequests). Melhor para apps com estado, conexões de banco, SSE ou WebSocket.

Outras formas de entrypoint

O export default de um worker pode ser um handler fetch, um objeto routes, ou você pode entregar um index.html para uma SPA estática:

fetch

export default {
  fetch(req: Request) {
    return new Response("ok");
  },
};

routes

export default {
  routes: {
    "/": new Response("Home"),
    "/api/posts/:id": {
      GET: (req) => new Response(`Post ${req.params.id}`),
    },
  },
};

SPA (index.html)

Defina entrypoint: index.html no manifest. O runtime serve o arquivo de forma estática e injeta <base href> para que o roteamento client-side funcione sob o subpath do app. O index.ts não é executado nesse modo.

Para onde ir agora

• Entenda o que acabou de acontecer: o pool de workers e o pipeline de requisições do runtime.
• Adicione uma capacidade ao runtime: escreva um plugin.
• Ajuste o runtime para um ambiente: variáveis de ambiente.