Skip to content

Browser pages

A vertex can have two pages:

  • an executor page, with the Browser capability, that people use while the vertex runs, such as a form or a checkout,
  • a settings page, with the Configurator capability, where users configure the vertex.

Adapt shows both in an iframe. They live in the vertex’s ui/ folder:

File Purpose
executor.html, configurator.html The page’s HTML.
*.main.ts or .tsx The browser entry point.
*.ssg.ts or .tsx Optional. Renders the first HTML at build time.
*.App.tsx React only. The page’s component.
api.ts, api.mock.ts The client for your backend, and its mock for development.
styles.css The page’s styles.

The page’s HTML is public. Your API is not. Adapt gives each page a browser token in the URL fragment, and the page sends it with each API request:

ui/api.ts (excerpt)
import { getToken } from "@mochabug/adapt-sdk/browser";
const response = await fetch(new URL("/api/page", window.location.origin), {
headers: { Authorization: `Bearer ${getToken()}` },
});

Your backend checks the token before the route runs. See Protect your API.

Keep protected data, credentials, and tokens out of the HTML. Load protected data after the page starts, through your API.

With --ssg, the build renders each page’s first HTML, so people see content before JavaScript runs:

ui/executor.ssg.tsx
import { renderToString } from "react-dom/server";
import App from "./executor.App";
export default function render(): string {
return renderToString(<App />);
}

This code runs in Node.js at build time, so it cannot use window or any protected data. If the page needs data from your API, render a loading state.

Call init once in the entry point:

import { init } from "@mochabug/adapt-sdk/browser";
init({ resize: true });

With resize: true, Adapt sizes the iframe to your content. For a layout that fills the viewport, such as height: 100vh, use resize: false.

Adapt sets the iframe’s color scheme, and can switch it without a reload. Your page follows it with plain CSS, as in the scaffold’s styles.css:

ui/styles.css (excerpt)
:root {
color-scheme: light;
--background: light-dark(#ffffff, #181818);
--foreground: light-dark(#111111, #eeeeee);
}
@media (prefers-color-scheme: dark) {
:root {
color-scheme: dark;
}
}

Use light-dark() for every color, and do not pick the theme in JavaScript. Charts and other code that draws its own colors must listen for theme changes.

Terminal window
npm run dev

In development, api.ts loads api.mock.ts, so the pages work without Adapt. Keep the mock true to your real API. Builds never include it.

People want pages that match their brand. Two patterns work well:

  • Style settings: colors for both themes, a font, and a corner radius in the settings page. Validate each value, and put the style in the page’s HTML, so the first paint is right.
  • Shared CSS: an optional variable service with plaintext: true that every page in a workspace or project uses. Viewers’ browsers get it, so it must not contain private data.

To let users bind inputs to signals from earlier steps, use the SDK’s SignalSelector from @mochabug/adapt-sdk/react, with its styles.css. In the backend, list the available signals with listIncomingSignals.

Write for people who are not developers: explain what each field needs, and hide schemas and IDs behind optional details.

Check each page in Chromium, Firefox, and WebKit:

  • in both themes, also when the theme is different from the browser’s preference,
  • with JavaScript off,
  • at narrow and wide sizes,
  • after a theme change: the page keeps what people typed.

Use the development server for these checks, and the emulator to check the pages in the real Adapt iframe.