Skip to main content

Shell API

View as Markdown

A complete guide for developers building micro-frontend applications for the RocketRide Cloud platform.


Table of Contents​

  1. Architecture Overview
  2. Getting Started
  3. The App Manifest
  4. The App Descriptor
  5. Shell Props: What Your App Receives
  6. Screen Zones
  7. Shell Hooks & APIs
  8. The Connection Manager (connectionManager)
  9. The Documents System
  10. The Virtual File System (IVirtualFileSystem)
  11. DocExplorer: File Tree Component
  12. DocTabs: Tab Bar Component
  13. DesktopView: The Shared Desktop Page
  14. Cross-App Component Loading
  15. Theming
  16. Build Configuration

Architecture Overview​

Shell-UI is a thin shell framework that hosts micro-frontend applications via Module Federation. The shell owns:

  • Four screen zones: Sidebar, Client Area, Debug Panel (ALT+D), Status Bar
  • Authentication: OAuth2 PKCE via Zitadel
  • Subscription gating: Checks server-side subscription state before loading paid apps
  • WebSocket connection: RocketRide client singleton
  • Workspace persistence: Per-app state in .workspace/ JSON files
  • Theme management: CSS custom properties (--rr-*)
  • Event bus: Typed message bus for cross-component communication

Apps are independent packages that export an AppDescriptor via Module Federation. The shell loads them lazily when the user activates the app.

┌──────────┬─────────────────────────┬────────────┐
│ │ │ │
│ Sidebar │ Client Area │ Debug │
│ │ │ (ALT+D) │
│ │ │ │
├──────────┴─────────────────────────┴────────────┤
│ ● Connected Ready │
└─────────────────────────────────────────────────┘

The shell mounts one component from your app:

  • app → Client Area (required). Your app composes its own layout inside (columns, sidebar, status bar) with <AppLayout>.

Getting Started​

You build a shell app in your own repository: npm install rocketride, export an AppDescriptor through Module Federation, and deploy the source to a RocketRide server, which builds and serves it.

Shortcut: the VS Code extension's App Builder scaffolds this whole shape from a template and adds a live preview, publish, and deploy loop — the steps below explain what it generates.

1. Create a new project​

mkdir my-app && cd my-app
npm init -y
npm install rocketride react react-dom
npm install -D @rsbuild/core @rsbuild/plugin-react @module-federation/rsbuild-plugin typescript

2. Project structure​

my-app/
├── package.json
├── rsbuild.config.ts
├── tsconfig.json
└── src/
├── index.ts # MF async boundary
├── AppDescriptor.ts # What the shell loads
└── MyApp.tsx # Client area component

3. Define the manifest in package.json​

{
"name": "my-app",
"version": "1.0.0",
"appManifest": {
"id": "mycompany.myApp",
"publisher": "My Company",
"name": "My App",
"description": "A short description for the app store",
"categories": ["tools"]
},
"dependencies": {
"rocketride": "^1.0.0",
"react": "^18.2.0",
"react-dom": "^18.2.0"
}
}

4. Create the AppDescriptor (src/AppDescriptor.ts)​

Import types from rocketride/app-sdk:

import type { AppDescriptor } from 'rocketride/app-sdk';
import MyApp from './MyApp';

const MY_APP: AppDescriptor = {
id: 'mycompany.myApp',
name: 'My App',
branding: { appName: 'My App' },
app: MyApp,
};

export default MY_APP;

5. Create the App component (src/MyApp.tsx)​

import React from 'react';
import type { ShellAppProps } from 'rocketride/app-sdk';

const MyApp: React.FC<ShellAppProps> = ({ isConnected, identity }) => {
return (
<div style={{ padding: 40, fontFamily: 'var(--rr-font-family)' }}>
<h1>Hello from My App!</h1>
<p>Connected: {isConnected ? 'Yes' : 'No'}</p>
<p>User: {identity?.displayName ?? 'Not logged in'}</p>
</div>
);
};

export default MyApp;

6. Async boundary (src/index.ts)​

import('./AppDescriptor');

7. rsbuild.config.ts​

import fs from 'node:fs';
import path from 'node:path';
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';

const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, 'package.json'), 'utf-8'));
const moduleId = (pkg.appManifest?.id ?? 'unknown').replace(/[^a-zA-Z0-9_$]/g, '_');

export default defineConfig(() => ({
plugins: [
pluginReact(),
pluginModuleFederation({
name: moduleId,
filename: 'remoteEntry.js',
exposes: { './AppDescriptor': './src/AppDescriptor.ts' },
dts: false,
shared: {
react: { singleton: true, eager: true, requiredVersion: '^18.2.0' },
'react-dom': { singleton: true, eager: true, requiredVersion: '^18.2.0' },
'rocketride/app-sdk': { singleton: true, requiredVersion: false },
},
}),
],
source: { entry: { index: './src/index.ts' } },
output: {
distPath: { root: './dist' },
assetPrefix: 'auto',
},
}));

8. Build and deploy​

npx rsbuild build

A local build only checks that the app compiles. Nothing serves ./dist/, and hosting it yourself does not make the app load: the shell only loads a version that the server built. To ship the app, deploy it from the Deploy tab of the App Builder, or with rocketride app deploy. That uploads your source, the server builds it into the next version, and publishing that version makes it available to its audience.


The App Manifest​

Declared in package.json under the appManifest key. This metadata is available at boot without loading the app bundle, used for the app store, authentication gating, and settings.

interface AppManifest {
/** Stable unique identifier (e.g. 'rocketride.myApp'). */
id: string;
/** Publisher name shown in the app store (e.g. 'My Company'). */
publisher?: string;
/** Display name shown in the app switcher. */
name: string;
/** Short description for the app store. */
description?: string;
/** Path to icon file (e.g. './src/icon.svg'). */
icon?: string;
/** Markdown readme for the app detail page. */
readme?: string;
/** Categories for filtering (e.g. ['tools', 'ai']). */
categories?: string[];
/** Shell editions the app serves ('saas' | 'oss' | 'vscode'). Absent: every shell. */
shells?: string[];
/** When false, the app runs without authentication. Default: true. */
authenticated?: boolean;
/** When false, the shell header (app name/icon in the sidebar) is hidden. Default: true. */
showHeader?: boolean;
/** When false, the status bar is hidden for this app. Default: true. */
showStatusBar?: boolean;
/** Settings contribution (VSCode `contributes.configuration` shape). Shown in the shell's Settings overlay. */
contributes?: { configuration?: AppConfiguration };
/** Internal: MF module identifier (derived from id). */
moduleId?: string;
/** App lifecycle status (e.g. 'auth', 'free', 'unsubscribed', 'subscribed', 'trialing', 'past_due', 'canceled'). */
appStatus?: string;
/** Whether the app is available on the desktop (non-cloud) platform. */
onDesktop?: boolean;
/** Platform apps only: public pages on the app origin (see Public pages). */
publicPages?: PublicPage[];
/** Platform apps only, honored from the app owning '/': the site's title, blurb, docs link, redirects, image, feeds and organization. */
site?: {
title?: string;
blurb?: string;
docsUrl?: string;
/** The snapshot, in the build output, served with a 404 on paths nothing serves: 'pages/404.html'. */
notFound?: string;
/** Old URLs answered with a 301 to one of your pages, query string kept. */
redirects?: { from: string; to: string }[];
/** The link-preview image of pages that declare none (same forms as a page's image). */
image?: string;
/** Atom feeds of the dated pages under a prefix: { path: '/blog/feed.xml', prefix: '/blog/', title: 'Blog' }. */
feeds?: { path: string; prefix: string; title: string }[];
/** The organization the site belongs to: its Organization JSON-LD, with the @id `${url}#organization`. */
organization?: { name: string; url: string; logo?: string; description?: string; sameAs?: string[] };
};
}

Public pages (platform apps)​

The server builds the app origin's public page map from the publicPages and site sections of published platform apps' manifests. A build can ship both sections in app-manifest.json at the root of its output, next to the page snapshots; the server reads that file in preference to the registered manifest. Both sections are optional and append-only: fields are never repurposed or removed, and the server ignores keys it does not know, so an older server accepts a newer manifest.

interface PublicPage {
/** One exact path: '/pricing'. */
path: string;
/** The page title (at most 300 characters). */
title: string;
/** The page description (at most 1000 characters). */
description?: string;
/** Default true. false marks the page unlisted: not meant to be advertised or indexed. */
listed?: boolean;
/** The document crawlers get, inside the app's build output, e.g. 'pages/pricing.html'. */
snapshot?: string;
/** Server data the page names: 'plans' (this app's plans), 'plans:<appId>' or 'app:<appId>'. */
data?: string[];
/** The link-preview image: an https URL, a root path, or a path in the build output ('og/pricing.png'). */
image?: string;
/** When the page was first published, 'YYYY-MM-DD' or an RFC 3339 date-time: makes it an article. */
published?: string;
/** When the page last changed, in the same forms; never earlier than published. */
modified?: string;
/** At most 5 authors, each a name (at most 300 characters) and an optional https URL. */
authors?: { name: string; url?: string }[];
}

Rules, enforced when a version is published to the public store rung (the publish fails with a message naming the field):

  • Only platform apps (ids in the rocketride developer namespace; on OSS that is every app, since every OSS app id is rocketride.<name>) may declare publicPages, and only a root app (RR_PUBLIC_ROOT_APPS, default rocketride.home) may declare pages. site goes with the / page: a platform app that declares site without declaring / is refused, and a third-party app's site is ignored, since it can never take effect.
  • path is absolute and lowercase, with no query, fragment, trailing slash, empty or dot segment. Each segment uses only a-z, 0-9, -, ., _ and ~, so /café and /caf%C3%A9 are refused. Wildcard pages are not supported.
  • Paths under a root route the engine serves itself (/api, /apps, /auth, /mcp, /shell, /status, /task, /.well-known and the rest of the engine's routes) or the three crawler files (/sitemap.xml, /robots.txt, /llms.txt) are rejected, as is a path a server route already serves, or one another published platform app already claims (first claim wins; unpublishing releases it).
  • Each data entry is plans, plans:<appId> or app:<appId>, and a page names each source (plans, app) at most once.
  • snapshot and site.notFound must be a relative .html path that exists in the built version, at most 2 MiB.
  • image and site.image are an https:// URL, a root path (/apps/..., never //) or a relative path inside the build output, with no empty or dot segment, at most 2048 characters.
  • published and modified are a real date (2026-11-09) or an RFC 3339 date-time with an offset (2026-11-09T10:00:00Z, at most ±23:59) that stays within years 1 to 9999 in UTC. A date alone means midnight UTC, and modified may not be earlier than published.
  • authors holds at most 5 entries, each with a non-empty name and, if given, an https:// url.
  • No text or URL field may hold a lone surrogate (U+D800 to U+DFFF, half of a UTF-16 pair, as a string cut through an emoji leaves), which UTF-8 cannot carry.
  • site.docsUrl must be an https:// URL, with <, >, ", ' and ` percent-encoded.
  • site.redirects (at most 100): each from is one exact path in the path grammar, except that a trailing slash is allowed (/master-saas-agreement/); it may not be reserved, and neither it nor its slash twin (/x and /x/) may be a server route or a page any published app serves; it appears once. List both forms of an old URL to redirect both. Each to is the exact path of one of the manifest's own pages.
  • site.feeds (at most 5): each path is one exact path in the path grammar ending in .xml; it may not be reserved, and neither it nor its slash twin may be a page any published app serves, a redirect's from or a server route; it appears once. prefix is a page path ending in / (/blog/, or / for every page), and title a non-empty string of at most 300 characters.
  • site.organization needs a non-empty name (at most 300 characters) and an https:// url; logo is an https:// URL, description at most 1000 characters, and sameAs a list of at most 20 https:// URLs.

Until a published platform app contributes a valid page, the page map holds the server's built-in page list instead. A published app whose storage cannot be read keeps the pages of its last readable build while the server runs; after a restart it has none until its storage can be read again. Kept pages still compete with other apps' claims under the same first-claim rule.

A server without RR_APP_URL is not the public site: its /robots.txt disallows all crawling and /sitemap.xml and /llms.txt answer 404, so search engines do not index its pages. Set RR_APP_URL to the public origin to make published pages indexable; a server that serves published pages without it logs a warning once.

The server answers GET and HEAD on each page with the shell's document (the route's prerendered capture when the shell build carries one, else index.html), its head carrying the page's title, description, a canonical URL on RR_APP_URL, and noindex for an unlisted page. Crawlers (search, AI and link-preview bots, by user agent) get the page's snapshot instead, read from the production version's build output, with the same head. A page without a snapshot, or whose snapshot cannot be read or rendered, serves crawlers the shell's document; so does a stored snapshot over 2 MiB, which the server never reads.

Every page's head, for people and crawlers alike (link-preview fetchers do not always say they are bots), also carries og:site_name (site.title), og:type and a Twitter card. A page with published is an article, with article:published_time and article:modified_time (modified, else published); any other page is a website. og:image is the page's image, else site.image, and asks for the large card (summary_large_image, else summary). A snapshot's own hand-written og:type, og:site_name, og:image, twitter:card, article:published_time and article:modified_time tags are removed (as are its title, description, canonical, robots, og:title, og:description and og:url), so the page's image and site.image are the only source of og:image. A snapshot's own twitter:image and twitter:image:alt are removed too, so X/Twitter falls back to that og:image. An https:// image is used as declared; a root path is made absolute with RR_APP_URL; a relative path is a file of the declaring app's build output, served from its production version (<RR_APP_URL>/apps/<appId>/v<N>/<path>). Without RR_APP_URL only an https:// image is used.

Crawlers also get a BlogPosting (JSON-LD) for each page with published: its headline (the title without a trailing | <site.title>), description, datePublished, dateModified, image, mainEntityOfPage (the canonical URL), each author as a Person, and the site's organization as publisher, also the author of a page without authors. That organization is a reference to the site.organization node by its @id when one is declared, else an organization named after site.title, on the RR_APP_URL origin. Crawlers get the site.organization node (an Organization with the declared fields and the @id <url>#organization) on / and on every page with published, so the reference resolves on the page itself; / also carries a WebSite node for the RR_APP_URL origin, published by that organization.

A snapshot is a template with exactly three kinds of tag, each on one line: {{name}} and {{a.b}} insert a value, HTML-escaped; {{#name}}...{{/name}} repeats its content for each item of a list, enters an object, and renders nothing for an absent, empty or false value. Sections nest at most 16 deep. There is no {{.}}: a list item that is not an object adds no names, so a tag inside its section reads the enclosing values ({{b}} inside {{#a}} over ["x"] renders the outer b). Any {{...}} or {{{...}}} on one line, with at most 128 characters and no other brace between the braces, is a tag, including inside <script> and <style>; only a {{ without such a closing }} stays as text. A tag of any other kind renders nothing, as does a tag naming a value the server does not provide. Escaping makes a value safe in HTML text and in quoted attributes that are not URLs; it does not make a value safe in a URL attribute (href, src), an event handler, style, <script> or an unquoted attribute, so only server-derived URLs such as {{assets}} belong there. {{assets}} is the URL of the version's build output, /apps/<appId>/v<N>, so a snapshot references its images as {{assets}}/seo-assets/logo.svg, served from the same version it was read from. The shell's own document is never treated as a template.

A page's data entries add server data to its snapshot, each under its source name whatever its argument:

  • plans and plans:<appId>: {{#plans}}...{{/plans}} iterates the plans of the declaring app or of the named app, each {id, name, price, currency, period, features[]}, with price a decimal string such as 29 or 29.50 (the server accepts a string, an integer or a decimal, never a float) and currency an upper-case code such as USD.
  • app:<appId>: {{#app}}...{{/app}} holds {name, description, url}. url is the app's subdomain URL; it is empty until subdomain routing ships, so put a link to it inside {{#url}}...{{/url}}, which renders only when it is set. Name and description are store text, safe only where escaping makes them safe.

A named app contributes only while anonymous store visitors can see it: its public listing is live, it requires no permissions, and its manifest does not say public: false. Otherwise plans is empty and app is absent. Crawlers also get JSON-LD built from the same data: a SoftwareApplication for app, and a Product with an Offer for each plan whose price is a plain decimal number (ASCII digits) and whose currency is a three-letter ISO 4217 code. A price change (invalidate('plans') from the billing layer) or a deployment change of an app a page names takes effect on the next crawl; other servers pick it up within five minutes. A crawler response that carries this data is sent public with a max-age of what remains of those five minutes, so no cache keeps it longer; one rendered while that data changed is sent private, no-cache. Other rendered snapshots are public, max-age=3600, and every page response carries Vary: User-Agent. When the data cannot be read, crawlers get the page without it.

/sitemap.xml and /llms.txt list the listed pages, and /llms.txt takes its heading, blurb and docs link from site; redirects never appear in either. Each sitemap entry's <lastmod> is the date of the page's modified, else published; a page with neither has no <lastmod>, since a deploy is not a content change. In /llms.txt, a page whose parent path (/blog for /blog/x) is a listed page is listed in that parent's section, headed by the parent's title without a trailing | <site.title>, with dated pages newest first and the rest by path; every other page is under ## Pages, by path.

A server with RR_INDEXNOW_KEY (8 to 128 letters, digits and -) and an https:// RR_APP_URL serves the key at /<key>.txt and, whenever the page map changes, submits to IndexNow, which shares them with Bing and the other participating search engines, the listed pages that are new or whose content changed (a field of the page, or its snapshot's bytes; a new version alone is no change) and the pages that were listed and are now gone or unlisted. Without both settings it serves no key file and submits nothing. The pages of an app missing from the page map altogether (unpublished, made non-public, or skipped for a moment because its storage could not be read) are not submitted as removed: a transient storage error must not look like a removal.

Each feed in site.feeds answers GET and HEAD on its path with an Atom 1.0 document (application/atom+xml): the listed pages strictly under its prefix that declare published, newest first, at most 50. An entry carries the page's canonical URL, its title without a trailing | <site.title>, published, updated (modified, else published; a date alone is midnight UTC), its description as the summary and its authors; the feed's own author is site.title. Like the sitemap, a feed answers 404 without RR_APP_URL. The prefix page and every page under it link to the feed from their head (<link rel="alternate" type="application/atom+xml">).

GET and HEAD on a redirect's from answer 301 with Location: <to>?<query>, and on /x/ answer 301 to /x when /x is a page (query kept). Any path that is neither a page, a redirect nor a server route answers 404. A browser or crawler (a GET or HEAD that accepts HTML) gets the server's not-found page with it, which links home and to sign-in; paths under /api, /task, /mcp and /.well-known, and API clients, get the plain 404. With site.notFound declared, a GET or HEAD on such a path (outside those prefixes) answers 404 with a page titled Page not found | <site.title>, noindex, no canonical URL and Cache-Control: private, no-cache: crawlers get the site.notFound snapshot, rendered like a page's ({{assets}} included), and people get the shell's index.html, so your app renders its own not-found view. Without site.notFound, the server's own not-found page serves instead.

Settings​

Apps can declare runtime settings (API keys, config values) that the shell manages. The declaration lives under appManifest.contributes.configuration — the exact contributes.configuration shape from the VSCode extension manifest specification, with setting keys dotted and prefixed with the app id:

{
"appManifest": {
"contributes": {
"configuration": {
"title": "My App",
"properties": {
"mycompany.myApp.apiKey": {
"type": "string",
"description": "Your API key for the external service",
"required": true
}
}
}
}
}
}

Each property is a SettingSchema (type, default, description, enum, required, ...). Display labels derive from the setting key, VSCode-style — there is no label field (apiKey renders as "Api Key").

Settings are:

  • Rendered in the shell's Settings overlay (grouped by app)
  • Persisted to .workspace/settings.json
  • Available to your app via useWorkspace().settings, access as settings['mycompany.myApp.apiKey'] (effective values: declared defaults overlaid with the user's overrides)

The shell contributes its own General section (keys under rocketride.general.*), which always appears first in the Settings overlay. Its keys are reserved — an app redeclaring one is ignored. rocketride.general.sidebar (default | vscode | cursor | rocketride, default default) picks the sidebar layout for every app: default defers to each app's declared sidebarMode, any other choice overrides it. vscode/cursor take effect only on apps that declare sidebarViews; apps with a classic sidebar node keep the classic column.


The App Descriptor​

The runtime descriptor your app exports. Loaded lazily when the user first activates your app.

interface AppDescriptor {
id: string; // Must match manifest id
name: string; // Display name
icon?: React.ReactNode; // Icon in app switcher
branding: ShellBrandingConfig; // Sidebar header branding

/** The app's ONE mount point — rendered raw in the client area. Required. */
app: React.ComponentType<ShellAppProps>;

/** How the app would like the shell sidebar to open when it activates. */
sidebar?: 'expanded' | 'collapsed';

/** Optional cross-app component catalog. Never mounted by the shell. */
components?: {
[key: string]: React.ComponentType<any>;
};

/** Dev-tool mounts — see "Dev Tools" below. Optional; hosted workbenches
mount these directly instead of booting the full `app`. */
devToolFrame?: React.ComponentType<DevToolProps>;
devToolSidebar?: React.ComponentType<DevToolProps>;

/** First-party apps only: the `app` value stamped on telemetry instead of
`id`. See "Telemetry" below. */
telemetryId?: string;
}
  • app is the single component the shell mounts in the client area; the app composes its own layout inside (columns, sidebar, status bar) with <AppLayout>. It is required even for apps that are primarily dev tools — a tool with no meaningful full-screen form still declares a minimal mount
  • sidebar lets an app ask for the shell sidebar collapsed on activation; absent means no opinion
  • components entries (e.g. Canvas, Toolbar, DataGrid) are never mounted by the shell but are loadable by other apps via useAppComponent()
  • devToolFrame / devToolSidebar are the dev-tool mount points (see Dev Tools)

ShellBrandingConfig​

interface ShellBrandingConfig {
appName: string; // Sidebar header text
logo?: React.ReactNode; // Expanded sidebar logo
logoCollapsed?: React.ReactNode; // Collapsed sidebar logo
iconDark?: React.ReactNode; // Icon for dark palette (light-colored)
iconLight?: React.ReactNode; // Icon for light palette (dark-colored)
icon?: React.ReactNode; // Generic fallback icon
welcomeLogo?: React.ReactNode; // Welcome/loading screen logo
welcomeTitle?: string; // Welcome screen title
welcomeSubtitle?: string; // Welcome screen subtitle
}

Icon resolution order: the shell picks the best icon for the sidebar header:

  1. iconDark / iconLight (matched to the active palette mode)
  2. icon (generic branding icon)
  3. Manifest icon URL (from package.json)
  4. 2-letter monogram fallback

Pre-built theme-aware SVGs are available in shared/assets/rocketride/:

  • rocketride-dark.svg: light body (#E0DDF0) for dark backgrounds
  • rocketride-light.svg: dark body (#1E1A34) for light backgrounds
  • rocketride.svg: currentColor body, CSS-controlled

Shell Props: What Your App Receives​

ShellAppProps (your App component)​

interface ShellAppProps {
/** Whether the RocketRide WebSocket is currently connected. */
isConnected: boolean;
/** Authenticated user identity, or null when not logged in. */
identity: ConnectResult | null;
}

Screen Zones​

ZoneOwnerContent
SidebarYour app component's layout (AppLayout)Classic column for a sidebar node; activity rail + panel when the app declares sidebarViews (app icon and name in the panel header, your content in the panel, account footer on the rail)
Client AreaYour app componentWhatever your app renders
Debug PanelShell (ALT+D toggle)Live event log, postMessage traffic
Status BarShellConnection status, app name, ready state
OverlaysShellAccount, Billing, Settings (triggered from sidebar footer)

If your app's layout renders no sidebar, the client area gets the full window width.

Sidebar chrome. The chrome follows the declaration. A plain sidebar={content} node renders the classic single column (which iconifies when collapsed). Declaring sidebarViews (one entry per rail icon; see SidebarViewContainer) unlocks the VS Code-style frame instead: a fixed activity rail beside a resizable panel holding your content. There, collapsing closes the panel; the rail and account footer never disappear, and your content is never asked to render an iconified form of itself. An existing menu can be projected onto the rail with viewsFromMenu(menu) — an explicit opt-in, never applied automatically. sidebarMode: 'rocketride' opts a view-declaring app back into the classic column; compact (mobile) widths always render a drawer. The user's General > Sidebar setting (rocketride.general.sidebar) overrides sidebarMode whenever it is set to anything other than default; on default the app's declaration applies. The vscode/cursor choices apply only to apps that declare sidebarViews — a classic sidebar is never shoehorned onto the rail.


Shell Hooks & APIs​

rocketride/app-sdk is a subpath export of the rocketride package: at build time it gives your app types and IntelliSense, and at runtime Module Federation's shared singleton mechanism replaces its stubs with the real implementations from the shell host itself, published as the shell package, which is why in-workspace code generated by the app scaffold imports the same hooks directly from 'shell'.

Import everything from 'rocketride/app-sdk':

import { useShellConnection, useShellApiConfig, useWorkspace, connectionManager } from 'rocketride/app-sdk';

Telemetry​

The shell owns the one product-telemetry transport (keys, consent, delivery). The platform serves these to it at runtime; your app never carries any of them. Your app receives a bound reporter and simply calls it:

import { useReport } from 'shell';

const report = useReport();
report('chat:message_sent', { length: 42 });

The shell binds the reporter to your app. Every event is stamped with an app property, last, so your props cannot overwrite it. There is nothing to initialise or configure. The stamped value is your descriptor's telemetryId when the app is first-party (id rocketride or starting rocketride.) and the alias is valid. Otherwise it is your app's id. A valid alias matches ^[A-Za-z0-9._-]{1,128}$, is not shell (reserved for the shell's own events) and is not another registered app's id. An alias that fails these checks falls back to the id with no warning. The alias is chosen once on the descriptor, never per event. Events the analytics SDK generates on its own ($pageleave, $web_vitals, $autocapture, $exception and the like) carry no app. $host and $pathname do not identify the app either, because the URL does not change on an app switch.

Events sent through getConsentedCapture(...).report are tagged internally as attributed. A tagged event is dropped at send time unless consent is still accepted and no browser privacy signal (DNT or GPC) is on. Without consent (the cookieless instance) it is always dropped. Ordinary events are never dropped because of their property names, and an app cannot set the tag itself. Event names are your app's own taxonomy (object:action by convention); document them beside your call sites. useConsent() exposes the visitor's analytics-consent state read-only (plus openSettings() to the Privacy section) for apps that gate their own captures on it. With no telemetry configured on the server (self-hosted), every call is a silent no-op.

Connection​

Hook/FunctionReturnsPurpose
useShellConnection(){ client, isConnected, statusMessage }Access the RocketRide WebSocket client
useShellApiConfig()ShellApiConfigRead runtime config (API URLs, keys, user settings)
getClient()RocketRideClient | nullNon-React access to the client singleton

Auth​

HookReturnsPurpose
useAuthUser()ConnectResult | nullCurrent authenticated user identity
useLogout()() => voidTrigger logout
useSubscriptions(){ desktopApps, isOnDesktop(appId), getStatus(appId) }User's desktop apps and subscription state

Workspace​

HookReturnsPurpose
useWorkspace()IWorkspaceContextAccess workspace state and dispatch

The workspace context provides:

  • seeded: True once pre-auth default state has been populated (before connection)
  • loaded: True once persisted workspace state has been read from disk (after connection)
  • prefs: Current app preferences (theme, active view, etc.)
  • appState: Opaque per-app state (used by Documents)
  • settings: User-configured settings
  • activeAppId: Current app ID
  • appManifest: All registered apps
  • appLoading: Whether the active app is currently loading
  • loadedApps: Map of already-loaded app descriptors (for cross-app component loading)
  • loadApp(appId): Trigger lazy loading of an app's descriptor
  • updateAppState(updater): Update per-app state — pass a function receiving the previous state and returning the next
  • updateSetting(key, value): Update a single setting
  • updatePrefs(patch): Update workspace preferences
  • themeOptions: Available theme choices
  • setTheme(themeId): Switch the active theme
  • dispatch(action): Update prefs or switch apps
  • emit(event, payload) / on(event, handler): Event bus (delegates to connectionManager)

Workspace Lifecycle: seeded vs loaded​

The workspace has a two-phase startup:

  1. Seeded (seeded = true, loaded = false): The workspace has been populated with hardcoded defaults (default prefs, empty appState, empty settings). This happens immediately, before authentication or WebSocket connection. The Shell renders at this point so unauthenticated apps (e.g. home/landing page) can display.

  2. Loaded (seeded = true, loaded = true): The WebSocket is connected and persisted state has been read from disk (.workspace/global.json, per-app workspace files, settings.json). Persisted prefs, appState, and settings overwrite the seeded defaults. Debounced persistence (auto-save) only activates after this point.

What this means for your app:

  • The Shell renders as soon as seeded is true. It is then up to each app to decide whether it needs to wait for loaded.
  • Unauthenticated apps (authenticated: false) can render immediately on seeded state, they receive isConnected=false and identity=null and should be designed to work with those values.
  • Authenticated apps that depend on persisted settings (API keys, saved state) should gate on loaded before rendering data-dependent UI:
const { loaded, settings } = useWorkspace();

if (!loaded) return <div>Loading workspace…</div>;

// Safe to read persisted settings here
const apiKey = settings.MY_API_KEY;
  • Persistence is safe: debounced saves to disk only fire when loaded is true, so seeded defaults are never accidentally written over persisted data.

The Connection Manager (connectionManager)​

A typed, module-level event bus singleton. Works from React components, hooks, plain functions, anywhere.

Basic usage​

import { connectionManager } from 'rocketride/app-sdk';

// Emit an event
connectionManager.emit('shell:loginRequest', { appId: 'rocketride.myApp' });

// Subscribe to an event (returns unsubscribe function)
const unsub = connectionManager.on('shell:connected', () => {
console.log('Connected!');
});

// Later: unsubscribe
unsub();

In a React component​

useEffect(() => {
const unsub = connectionManager.on('shell:event', ({ event }) => {
console.log('Server event:', event);
});
return unsub; // cleanup on unmount
}, []);

Defined events​

EventPayloadDirectionDescription
shell:connected{}Shell → AppsWebSocket connection established
shell:disconnected{ reason: string; hasError: boolean }Shell → AppsWebSocket connection lost
shell:login{ user: ConnectResult }Shell → AppsUser authenticated
shell:logout{}Shell → AppsUser logged out
shell:loginRequest{ appId?: string; register?: boolean; auto?: boolean; signupProperties?: SignupProperties }Apps → ShellRequest OAuth login (optionally targeting an app); register marks a sign-up intent; auto is set only by the shell's own auth gate, apps leave it unset
shell:logoutRequest{}Apps → ShellRequest logout
shell:switchApp{ appId: string }Apps → ShellSwitch the active app
shell:subscribe{ app: AppManifestEntry, plan?: CheckoutPlan }Apps → ShellOpen subscription checkout for an app; optional plan preselects a tier and skips the picker (straight to payment)
shell:myApps{}Apps → ShellNavigate to My Apps
shell:accountUpdateConnectResultServer → ShellServer-pushed account/subscription change
shell:sidebarCollapsing{}Shell → AppsSidebar is collapsing (for layout adjustments)
shell:themeChange{ tokens: Record<string, string> }Shell → AppsTheme CSS tokens changed
shell:statusChange{ message: string | null }Shell → AppsTransient status bar text changed
shell:event{ event: unknown }Server → AppsRaw server event forwarded from WebSocket
shell:telemetryTelemetryFact ({ event: string; props: Record<string, unknown>; ts: number; id: string })Shell → AppsDEPRECATED, never emitted (the shell owns the telemetry transport). Typed only for frozen-floor compatibility; see Telemetry facts
shell:appsUpdated{ apps: ShellAppEntry[] }Shell-internalApp list updated
shell:manifestRefresh{ source: string }Shell-internalApp manifest re-fetched
shell:openOverlay{ id: 'account' | 'settings' | 'environment' }Shell-internalOpen a shell overlay
shell:unsubscribe{ appId: string }Shell-internalCancel an app subscription
shell:viewActivated{ viewId: string }Shell-internalA shell view became active

The events marked Shell-internal exist only in the shell package's internal event map — they are not part of the ShellEventMap exported from rocketride/app-sdk, so external apps cannot emit or subscribe to them type-safely.

Telemetry facts​

The shell reports its own product facts on its own reporter, stamped with app shell. No app forwards them. They are auth:start, when it starts the OAuth redirect, and auth:complete, when the callback resolves an identity, with the account's new-user flag is_new, its waitlist state waitlisted, and duration_ms, the OAuth round trip in milliseconds from the redirect to the callback (null when it is not known). auth:start always carries is_authed: false and auth:complete always carries is_authed: true, whatever the state of the page load that sends them. The consent banner's consent:shown, consent:decision and consent:handoff events are the shell's too. A fact raised before the analytics SDK has started waits in the shell's queue, which is mirrored to the tab's sessionStorage, so it is replayed with its original time on the next page load (the OAuth callback, for auth:start) if this one ends first.

connectionManager.drainTelemetry() and the shell:telemetry event are deprecated. Nothing feeds them any more: drainTelemetry() always returns an empty list and shell:telemetry is never emitted. They stay typed only for compatibility with the frozen v8/v9 floor. Do not subscribe to them or forward from them; your own events go through useReport() as described in Telemetry.

Extending the event map​

Add custom events via TypeScript module augmentation:

declare module 'rocketride/app-sdk' {
interface ShellEventMap {
'myapp:dataUpdated': { recordId: string; timestamp: number };
'myapp:exportComplete': { fileUrl: string };
}
}

// Now type-safe:
connectionManager.emit('myapp:dataUpdated', { recordId: '123', timestamp: Date.now() });

Debug logging​

All events are automatically captured in a circular buffer (500 entries) visible in the Debug Panel (ALT+D).

import { getDebugLog, clearDebugLog, onAny } from 'rocketride/app-sdk';

// Get all captured events
const log = getDebugLog(); // DebugLogEntry[]

// Listen to ALL events (for custom logging)
const unsub = onAny((event, payload) => {
console.log(`[${event}]`, payload);
});

The Documents System​

A VS Code-style document model for apps that manage files/documents. Completely opt-in, simple apps don't need it.

Documents is an instantiable class: your app creates it, owns it, passes it where needed. The shell never sees it.

Core concepts​

ConceptDescription
DocumentOne per URI. Holds content in memory. Tracks dirty state and version.
EditorA view onto a Document. Independent viewport state (scroll, cursor). Multiple editors can view the same document.
EditorGroupA pane container. Holds an ordered list of editors. Supports horizontal/vertical splits.

Creating an instance​

Create a Documents instance in your App component, passing an IVirtualFileSystem:

// src/docs.ts — shared instance for your app
import { Documents } from 'rocketride/app-sdk';
import type { IVirtualFileSystem } from 'rocketride/app-sdk';

let _docs: Documents | null = null;

export function getDocs(): Documents {
if (!_docs) throw new Error('Documents not initialised');
return _docs;
}

export function createDocs(vfs: IVirtualFileSystem): Documents {
_docs = new Documents(vfs);
return _docs;
}

export function destroyDocs(): void {
_docs?.destroy();
_docs = null;
}
// src/MyApp.tsx
import { createDocs, destroyDocs } from './docs';

const MyApp: React.FC<ShellAppProps> = () => {
const { client } = useShellConnection();

useEffect(() => {
const vfs: IVirtualFileSystem = {
list: (dir) => client.fsListDir(dir),
read: (path) => client.fsReadJson(path),
write: (path, content) => client.fsWriteJson(path, content),
rename: (old, new_) => client.fsRename(old, new_),
delete: (path) => client.fsDelete(path),
mkdir: (path) => client.fsMkdir(path),
};
createDocs(vfs);
return () => destroyDocs();
}, [client]);

return <MyAppInner />;
};

Using the instance (call methods from anywhere)​

import { getDocs } from './docs';

// Open a file
await getDocs().openDocument('path/to/file.txt');

// Create a new document with initial content
const uri = getDocs().createDocument(undefined, { key: 'value' });

// Update content (any serializable value — stored as-is)
getDocs().updateContent(uri, { key: 'updated' });

// Save to disk
await getDocs().saveDocument(uri);

All operations are methods on the Documents instance:

MethodDescription
openDocument(uri, groupId?)Open a file (reads from VFS if not already open)
createDocument(groupId?, content?)Create a new untitled document
closeEditor(editorId)Close an editor (disposes doc if last clean ref)
updateContent(uri, content)Update in-memory content (marks dirty)
saveDocument(uri)Write to disk via VFS (marks clean)
revertDocument(uri)Re-read from disk (replaces content)
splitGroup(groupId, orientation)Split an editor group
moveEditor(editorId, targetGroupId)Move editor between groups
closeGroup(groupId)Close all editors in a group
setActiveEditor(groupId, index)Activate an editor within a group
setActiveGroup(groupId)Focus a group
openStaticDocument(uri, label, content?, groupId?)*Open a read-only static document with a display label
splitGroupWithDocument(groupId, orientation)*Split a group, moving the active document to the new pane
updateSplitSizes(splitNodeId, sizes)*Update the sizes of a split layout node
updateEditorViewport(editorId, patch)Merge an editor's scroll position and cursor coordinates
updateEditorViewState(editorId, viewState)*Persist an editor's opaque view state (the app owns its shape)
getState()Read state without subscribing
getDocument(uri)Get a single document by URI
destroy()Clean up the instance

* Available on the shell package's Documents implementation but not yet declared on the rocketride/app-sdk Documents typing — external TypeScript builds referencing them will fail to type-check.

React subscription​

import { getDocs } from './docs';

const MyComponent: React.FC = () => {
const state = getDocs().useStore(); // re-renders on any state change

const activeGroup = state.groups[state.activeGroupId];
const activeEditorId = activeGroup?.editorIds[activeGroup.activeEditorIndex];
const activeEditor = activeEditorId ? state.editors[activeEditorId] : undefined;
const activeDoc = activeEditor ? state.documents[activeEditor.documentUri] : undefined;

return <div>{activeDoc?.uri ?? 'No document open'}</div>;
};

Sharing across your app's tree​

Components in different parts of your app's layout (e.g. your editor area and your sidebar) can share the same Documents instance via the module-level getDocs() function:

MyApp (creates instance)     MySidebar (uses same instance)
↓ ↓
createDocs(vfs) getDocs()
↓ ↓
getDocs().useStore() getDocs().openDocument(path)

Content type​

Document.content is unknown, the exact object you store is the exact object you get back. No serialization happens inside the Documents class. The VFS handles serialization at the disk boundary.

  • Pipeline editor: stores a PipelineConfig object
  • Text editor: stores a string
  • Image editor: stores a base64 string or metadata object

The Virtual File System (IVirtualFileSystem)​

The single abstraction for all file I/O. Created by the app, passed to both new Documents(vfs) and DocExplorer.

interface IVirtualFileSystem {
list(dir: string): Promise<{ name: string; type: 'file' | 'dir' }[]>;
read(path: string): Promise<unknown>;
write(path: string, content: unknown): Promise<void>;
rename(oldPath: string, newPath: string): Promise<void>;
delete(path: string): Promise<void>;
mkdir(path: string): Promise<void>;
}

Example: RocketRide client VFS​

const vfs: IVirtualFileSystem = {
list: async (dir) => {
const result = await client.fsListDir(`projects/${dir}`);
return result.entries.map(e => ({ name: e.name, type: e.type }));
},
read: (path) => client.fsReadJson(`projects/${path}`),
write: (path, content) => client.fsWriteJson(`projects/${path}`, content),
rename: (old, new_) => client.fsRename(`projects/${old}`, `projects/${new_}`),
delete: (path) => client.fsDelete(`projects/${path}`),
mkdir: (path) => client.fsMkdir(`projects/${path}`),
};

Example: REST API VFS​

const vfs: IVirtualFileSystem = {
list: async (dir) => {
const res = await fetch(`/api/files?dir=${dir}`);
return res.json();
},
read: async (path) => {
const res = await fetch(`/api/files/${path}`);
return res.json();
},
write: async (path, content) => {
await fetch(`/api/files/${path}`, { method: 'PUT', body: JSON.stringify(content) });
},
rename: async (old, new_) => {
await fetch(`/api/files/${old}/rename`, { method: 'POST', body: JSON.stringify({ to: new_ }) });
},
delete: async (path) => {
await fetch(`/api/files/${path}`, { method: 'DELETE' });
},
mkdir: async (path) => {
await fetch(`/api/files/${path}`, { method: 'POST', body: JSON.stringify({ type: 'dir' }) });
},
};

DocExplorer: File Tree Component​

A generic file tree panel (like VS Code's EXPLORER). Renders a hierarchical file tree with:

  • Directory expand/collapse
  • Tree/flat view toggle
  • File selection and active highlight
  • Inline rename and create
  • Context menus (rename/delete)
  • Status dots (running/error/warning)
  • Optional child items under files (with action buttons)
  • Keyboard navigation
import { DocExplorer } from 'shell';
import type { DocExplorerConfig, DocEntry } from 'shell';
import type { IVirtualFileSystem } from 'rocketride/app-sdk';

const config: DocExplorerConfig = {
title: 'My Files',
extensions: ['.txt', '.md'],
displayName: (name) => name.replace(/\.(txt|md)$/, ''),
emptyMessage: 'No files yet',
createPlaceholder: 'file name',
};

<DocExplorer
vfs={myVfs}
config={config}
entries={entries}
statuses={statusMap}
isConnected={isConnected}
activeFilePath={activeUri}
onOpenFile={(path) => getDocs().openDocument(path)}
onFileManage={(action, path, newName) => { /* rename/delete/create */ }}
onRefresh={() => refreshFileList()}
/>

DocExplorerConfig​

FieldTypeDefaultDescription
titlestring(required)Section header (e.g. "Pipelines", "Photos")
extensionsstring[] | nullnullFile extensions to filter. Null = show all.
displayName(filename: string) => stringStrips known extensionsCustom display name formatter
createPlaceholderstring'file name'Placeholder for inline create input
emptyMessagestring'No files'Empty state message

DocTabs: Tab Bar Component​

A tab bar UI for a single editor group. Takes a Documents instance as a prop.

import { DocTabs } from 'shell';
import { getDocs } from './docs';

<DocTabs
docs={getDocs()}
groupId={groupId}
onDirtyClose={(editorId, uri) => {
// Show "save changes?" dialog
}}
/>

Features:

  • Tab per editor in the group
  • Dirty indicator (dot)
  • Close button (on hover)
  • Active tab highlight
  • Calls docs.setActiveEditor() / docs.closeEditor() on the provided instance

DesktopView: The Shared Desktop Page​

DesktopView renders the RocketRide desktop content — a time-aware greeting, a rotating quote, and the responsive app-card grid (launch, version switcher, remove/unsubscribe, subscription badges). It is the one desktop implementation shared by the OSS and SaaS home apps; a launcher app renders it and supplies only the app list and chrome (nav, footer, padding).

import { DesktopView } from 'shell';     // or getShellApi().DesktopView

<DesktopView
apps={apps} // AppManifestEntry[], pre-filtered/sorted
style={{ padding: '60px 40px 80px' }} // host-owned spacing
/>

Server interactions (version rails, session overrides, desktop remove, unsubscribe, subscription status) are built in — the component talks to the shell's connection itself. Optional props adjust behavior:

PropPurpose
onLaunchReplace the default launch (shell:switchApp)
greetingName / greetingOverridePersonalize or pin the greeting
showQuoteHide the rotating quote column (default shown)
allowRemoveDisable the hover X + remove/unsubscribe popover
resolveIconTheme-adaptive icon override per app
adapterOverride the server operations (DesktopAdapter)
popoverBoundarySelectorHost sticky-header selector for drop-list placement
emptyMessageZero-apps text

Types: DesktopViewProps, DesktopAdapter, DesktopQuote, DesktopVersionRow, DesktopVersionOverride. Animations (card cascade, greeting reveal, icon fade) honor prefers-reduced-motion. Theming uses the standard --rr-* CSS variables.

Dev Tools​

An app can declare itself a dev tool: a UI that host workbenches (the VS Code extension, rocket-ui) mount directly as a component — no shell boot, no iframe. Declare the manifest category and the descriptor mount points:

// package.json → appManifest
"categories": ["devTool"]
// AppDescriptor
const MY_TOOL: AppDescriptor = {
// ...existing fields
devToolFrame: MyToolSurface, // the tool's main surface
devToolSidebar: MyToolSidebar, // optional panel shown in the host's sidebar
};

Both components receive DevToolProps:

PropPurpose
channelThe tool's ONE transport surface to its other mount (frame ↔ sidebar; the mounts may live in isolated documents — VS Code webviews). Three lanes: retained state topics, fire-and-forget events, correlated ops
documentsOn multi-document hosts: open(docKey, title) / close(docKey)
docKey / activeDocKeyThe document key a frame serves / the fronted document a sidebar follows

There is NO client prop — and none is needed. The realm model in three lines:

  1. Every surface runs in a realm (the shell page, each VS Code webview, each framework page) attached to the shell bus.
  2. Every realm's useShellConnection().client is a real RocketRideClient: the root realm's client owns the socket; every other realm holds a realm client whose requests ride the bus to that same socket. There is ONE socket per host process.
  3. A tool's sidebar mount (its controller) therefore owns authority, not transport: it coordinates the tool's genuinely shared state — refcounted resources, single-writer stores, one shared poller — through tool ops, while every mount makes its own engine calls on its own client.

A tool's ops live in a src/ops/ directory with a fixed three-file layout (see sql-ui and monitor-ui for the reference shape), re-exported by an ops/index.ts barrel:

// ops/types.ts — the tool's COORDINATION protocol, declared ONCE as maps
// extending the shell's base maps (per tool; `host:*` keys are reserved).
// Only shared state belongs here — plain engine calls go through the realm
// client.
import type { ToolOpMap, ToolOpSpec, ToolStateMap, ToolEventMap } from 'shell';

export interface MyOps extends ToolOpMap {
'myTool.acquire': ToolOpSpec<{ id: string }, MyHandle>; // refcounted — ONE owner realm
}
export interface MyStateMap extends ToolStateMap { records: MyRecord[] }
export interface MyEventMap extends ToolEventMap { save: MyRecord }

// ops/server.ts — the implementations, served by the sidebar CONTROLLER mount.
export function serveMyOps(channel: ToolChannel): () => void {
const ops = createToolOpServer<MyOps>(channel);
ops.serve('myTool.acquire', async ({ id }) => acquire(id));
return () => ops.dispose();
}

// ops/client.ts — the typed calls, used by FRAME mounts.
export function createMyOpsClient(channel: ToolChannel) {
const call = createToolOpClient<MyOps>(channel);
return { acquire: (id: string) => call('myTool.acquire', { id }) };
}

// In the frame: engine work on the realm's own client; shared state via ops.
const { client, isConnected } = useShellConnection();
const rows = client ? await client.listTasks({}) : [];
const handle = await createMyOpsClient(channel).acquire(id);

Why two readiness hooks exist. useShellConnection().isConnected is this realm's connection truth — the mirrored state of the one socket the realm client rides; gate engine calls on it. useConnectionReady(channel) reads the host:connection system topic — the controller realm's reachability, published by the host (never by a tool) and retained on the channel. Today both describe the same single socket; they stay distinct because hosts are growing multiple connections (the VS Code dev/deploy slots — see host.envSlots), where "my realm's client can reach the engine" and "the controller's connection is up" stop being the same question. Gate frame↔controller coordination on useConnectionReady, engine calls on your own realm's state. useConnectionReady is tri-state: undefined means no host:connection snapshot has arrived yet (unknown — render a waiting state, never a "disconnected" claim), false means the host said disconnected, true means ready; a plain if (!ready) guard treats the initial undefined like false, which is safe for gating but wrong for displaying a disconnect.

There is no theme prop: dev-tool components are themed by the ambient --rr-* CSS custom properties of the document they mount into (the active shell theme in a browser; the editor-variable mapping in VS Code) — style exclusively with var(--rr-*) tokens. The tab icon hosts show comes from the manifest icon; the descriptor is loaded only when the tool is opened.


Cross-App Component Loading​

Apps can expose components for other apps to use, and load components from other apps at runtime via Module Federation.

Exposing components​

Add them to your components object in the AppDescriptor. They're bundled automatically because they're imported, no extra exposes in rsbuild needed.

const MY_APP: AppDescriptor = {
id: 'rocketride.myApp',
name: 'My App',
branding: { appName: 'My App' },
app: MyApp,
components: {
// Shell never mounts these, but other apps can access them
SpecialChart: MySpecialChartComponent,
DataGrid: MyDataGridComponent,
},
};

Your rsbuild.config.ts still only needs one expose:

exposes: {
'./AppDescriptor': './src/AppDescriptor.ts',
}

When the shell loads your AppDescriptor, all components referenced in components are included in the bundle automatically.

Loading components from another app​

Use useAppComponent(), it lazy-loads the target app's descriptor if needed and returns the component once available:

import { useAppComponent } from 'rocketride/app-sdk';

const MyComponent: React.FC = () => {
const Chart = useAppComponent('rocketride.otherApp', 'SpecialChart');

if (!Chart) return <div>Loading...</div>;
return <Chart data={myData} />;
};

The hook:

  • Returns null while the target app's descriptor is loading
  • Triggers a lazy load automatically if the app hasn't been visited yet
  • Returns the component once available, no manual loading needed

Theming​

The shell manages themes via CSS custom properties. Your app should use --rr-* variables for all colors, fonts, and borders.

Available CSS variables​

VariablePurpose
--rr-bg-defaultMain background
--rr-bg-paperCard/panel background
--rr-bg-surface-altHover/alternate background
--rr-bg-inputInput field background
--rr-text-primaryPrimary text
--rr-text-secondarySecondary/muted text
--rr-text-disabledDisabled text
--rr-brandBrand/accent color
--rr-borderBorder color
--rr-font-familyPrimary font
--rr-font-family-monoMonospace font
--rr-color-successSuccess green
--rr-color-warningWarning orange
--rr-color-errorError red

Responding to theme changes​

useEffect(() => {
return connectionManager.on('shell:themeChange', ({ tokens }) => {
// tokens is a Record<string, string> of all --rr-* values
console.log('New theme:', tokens['--rr-brand']);
});
}, []);

Build Configuration​

See the Getting Started section for the complete rsbuild.config.ts template.

Key points:

  • The MF container name is derived automatically from appManifest.id in package.json
  • Always expose ./AppDescriptor as the single MF entry point
  • rocketride/app-sdk must be a shared singleton so your app and the shell agree on one instance
  • React and react-dom must be shared singletons to avoid duplicate instances

For the App Builder loop, see App Builder.

Optional signup attribution​

ConnectionManager.startOAuth(register, context) and shell:loginRequest accept optional signupProperties analytics metadata. The shell validates it, carries it across the identity provider redirect in one of two ways below, consumes it once on the OAuth callback, and passes it in the PKCE credential through a resolver that rechecks consent, privacy signals and expiry immediately before the SDK sends authentication. The encoded cd_ credential uses the wire key signup_properties. Native auth:start and auth:complete telemetry facts contain no signup attribution. Missing, expired or invalid context does not stop sign-in. Embedded developer previews do not touch the host tab's storage.

A consented context is held in tab storage under active analytics consent and never appears in the identity provider URL. A cookieless context (consent_state: 'undecided') is only for a visitor who has not chosen yet. Nothing is written to site storage for it: the shell sends it as the OAuth state, base64 JSON { v: 1, signup }, and reads it back on the callback. That state is readable and unsigned, and like the rest of the authorize URL it stays in the browser's history and reaches the identity provider's request logs. PKCE prevents forged callbacks, so a forged state can only change attribution. A consented context is never accepted from the URL.

Version 1 carries experiment, experiment_revision, variant_id, assignment_id, exposure_id, landing_message_revision, exposed_at, expires_at, consent_version: 1, and schema_version: 1, plus consent_state on a cookieless context. Consumers must check consent_state before treating a context as consented. Times are milliseconds since epoch; expiry is fixed at 30 minutes after exposure. The account service validates its experiment/catalog separately. This context is untrusted analytics input and must never authorize access or establish account identity.

The consent record is written by the shell's consent banner (packages/shell/src/telemetry), under localStorage['rr_consent_v1']. Its shared schema is { v: 1, choice: 'accepted' | 'rejected', at: number }, where at is milliseconds since epoch. A record is valid up to 365 days old, with at most 60 seconds of future clock skew. A consented context needs a valid accepted record. A cookieless context needs no valid record at all (missing, malformed or expired reads as undecided), so accepting or rejecting on the banner drops it. DNT or GPC, or storage that cannot be read, omits either kind. Coordinate any change to this key or schema with both repositories. CloudAuthProvider.signIn() owns pending signup storage; startOAuth() passes validated context to it.