Rumatadocs
SupportOpen Rumata
Browse documentation

Frontends on Rumata

Open MarkdownOpen JSON

How to activate a frontend, connect it to managed backends and workflows, follow source rules, and publish it.

7 min readUpdated Nov 1, 2026

Step-by-step guidance.

Before you start

  • A running development machine.
  • For an API-backed app, a backend registered as in Backends.

Activate the frontend

Without a registered frontend, call `rumata.enableFrontend` (public MCP: `enable_frontend`) before writing UI files, and use the directory it returns. It prepares the starter, preview and Studio without interrupting chat. Repeated calls keep your files.

Never ask the user to configure Settings, create folders, start a server or refresh. Keep frontend source in the configured frontend folder, and backend source in its sibling backend folder.

Connect a managed backend

  1. Copy the exact `getBackendService.frontendBinding` into `rumata.backends.json` under a `VITE_*` key.
  2. Use the `rumataBackends()` Vite plugin. It selects the preview or deployed URL, and the bridge adds preview authentication.
  3. Call the `VITE_*` URL from the frontend. A separate typed client under `src/api/` is a maintainability convention; routing works from any app module.
ts
const base = import.meta.env.VITE_API_URL;
const url = `${base.replace(/\/$/, '')}/${endpoint.replace(/^\//, '')}`;
const response = await fetch(url, {
  ...init,
  headers: {
    ...(init.body !== undefined ? { 'content-type': 'application/json' } : {}),
    ...init.headers,
  },
});
  • A binding is a base path without a trailing slash. Preview may use a same-origin relative path; production uses an absolute URL.
  • Do not use `new URL(endpoint, base)`. A relative base throws, and a missing trailing slash drops the service ID even in production.
  • Send `content-type: application/json` only with a JSON body, including on DELETE. A bodyless request with that header fails the backend JSON parser before reaching the route.
  • No preview restart or hardcoded origin is needed.

Call a workflow

Only workflow calls use `src/api/workflows/` and the seeded `apiClient`, with logical routes. Never prepend `factoryId`. The workflow client does not route to managed backends.

Source rules

  • Keep frontend rendering and server logic in separate modules. Independently deployed clients and APIs need explicit service bindings; one process serving both can suit an existing server-rendered app.
  • Reflect backend schemas in typed clients, and keep server credentials out of browser code.
  • Keep each source file below 400 lines, including styles and data modules. Count unchanged starter files too. Split oversized files or remove unused code after checking consumers; never compress lines to comply. Exclude dependencies, generated output and lockfiles.
  • Inspect the active entry point and routes. Unused starter files do not prove a feature is absent.

Publish the website

Publish the registered frontend through its deployment flow after required services and workflows are ready and the user has approved the release. Frontend delivery can include server-rendered behavior; keep its runtime boundary distinct from a separately managed API. See Deployment.