Two-layer architecture

​

File layout

my-miniapp/
├── miniapp.json              # declares both entry points
├── build.ts                  # bundles both layers in one pass
└── src/
    ├── background/
    │   └── index.ts          # registerMiniapp(session => …)
    ├── ui/
    │   ├── index.html
    │   ├── main.tsx          # mounts <App/>, calls mentra.ready()
    │   └── App.tsx
    └── shared/
        └── channels.ts       # typed channel registry: both sides import it

{
  "entry": {
    "background": "background/index.js",
    "ui": "ui/index.html"
  }
}

​

The background layer

import { registerMiniapp } from "@mentra/miniapp/background";
import "../shared/channels";

registerMiniapp(async (session) => {
  // Subscribe to glasses events here. The runtime tears them down on disable.
  session.transcription.on((data) => {
    session.display.render([
      { type: "text", id: "caption", box: { x: 0, y: 0, w: 576, h: 288 }, text: data.text },
    ]);
  });
});

​

Startup: return your setup promise

• Return your setup. Return or await it; never discard it with void. Otherwise the UI can open before your handlers are registered, and its first requests fail with no handler registered.
• Register UI handlers before slow work. The splash stays up while the promise is pending. Register session.ui.handle / session.ui.onOpen first, and keep network calls out of the startup path.
• Failures still open the UI. If the handler throws or rejects, or takes longer than 10 seconds, the Mentra App opens the UI anyway.

registerMiniapp(async (session) => {
  const settings = await loadSettings(); // fast, local
  session.ui.handle("getHistory", () => history.list());
  session.ui.onOpen(() => session.ui.send("settings", settings));
  void refreshFromNetwork(session); // don't hold the UI for this
});

​

Background runtime APIs

​

The UI layer

import { createRoot } from "react-dom/client";
import { MentraProvider } from "@mentra/miniapp/ui";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <MentraProvider>
    <App />
  </MentraProvider>,
);

mentra.ready(); // flush any buffered messages from background

​

Talking between layers

import type { MentraTyped } from "@mentra/miniapp/ui";

export interface Channels {
  ping: { at: number };                        // UI → background
  pong: { at: number; roundtripMs: number };   // background → UI
}

declare global {
  var mentra: MentraTyped<Channels>;
}

mentra.send("ping", { at: Date.now() });            // fire-and-forget
mentra.on("pong", ({ roundtripMs }) => { /* … */ }); // subscribe
const res = await mentra.request("getNotes", {});    // request/response (RPC)

session.ui.onOpen(() => session.ui.send("pong", { at: Date.now(), roundtripMs: 0 }));
session.ui.on("ping", ({ at }) => { /* … */ });
session.ui.handle("getNotes", async () => ({ notes }));  // respond to mentra.request

​

Lifecycle

1. Install: the host unzips the bundle, validates the manifest, spawns the background JS context, and runs your registerMiniapp handler. Background is alive.
2. UI opens: the user taps your tile; the host spawns a WebView, injects the mentra shim, and loads ui/index.html. The WebView calls mentra.ready(). Once your background is ready (see Startup), the splash hides and session.ui.onOpen fires in the background.
3. UI closes: the user navigates away; the host destroys the WebView. The background context stays alive and session.ui.onClose fires.
4. Disable / uninstall: the host tears down your subscriptions and kills the background context.

​

Crash recovery

​

Next steps