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. |
How a page talks to your backend
Section titled “How a page talks to your backend”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:
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.
Render at build time
Section titled “Render at build time”With --ssg, the build renders each page’s first HTML, so people see content before JavaScript runs:
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.
Start the page
Section titled “Start the page”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.
Follow the theme
Section titled “Follow the theme”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:
: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.
Preview locally
Section titled “Preview locally”npm run devIn 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.
Let users style pages
Section titled “Let users style pages”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
variableservice withplaintext: truethat every page in a workspace or project uses. Viewers’ browsers get it, so it must not contain private data.
Bind signals in settings pages
Section titled “Bind signals in settings pages”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 your pages
Section titled “Check your pages”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.