Shell API
A complete guide for developers building micro-frontend applications for the RocketRide Cloud platform.
Table of Contents
- Architecture Overview
- Getting Started
- The App Manifest
- The App Descriptor
- Shell Props: What Your App Receives
- Screen Zones
- Shell Hooks & APIs
- The Connection Manager (connectionManager)
- The Documents System
- The Virtual File System (IVirtualFileSystem)
- DocExplorer: File Tree Component
- DocTabs: Tab Bar Component
- DesktopView: The Shared Desktop Page
- Cross-App Component Loading
- Theming
- 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
rocketridedeveloper namespace; on OSS that is every app, since every OSS app id isrocketride.<name>) may declarepublicPages, and only a root app (RR_PUBLIC_ROOT_APPS, defaultrocketride.home) may declare pages.sitegoes with the/page: a platform app that declaressitewithout declaring/is refused, and a third-party app'ssiteis ignored, since it can never take effect. pathis absolute and lowercase, with no query, fragment, trailing slash, empty or dot segment. Each segment uses onlya-z,0-9,-,.,_and~, so/caféand/caf%C3%A9are refused. Wildcard pages are not supported.- Paths under a root route the engine serves itself (
/api,/apps,/auth,/mcp,/shell,/status,/task,/.well-knownand 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
dataentry isplans,plans:<appId>orapp:<appId>, and a page names each source (plans,app) at most once. snapshotandsite.notFoundmust be a relative.htmlpath that exists in the built version, at most 2 MiB.imageandsite.imageare anhttps://URL, a root path (/apps/..., never//) or a relative path inside the build output, with no empty or dot segment, at most 2048 characters.publishedandmodifiedare 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, andmodifiedmay not be earlier thanpublished.authorsholds at most 5 entries, each with a non-emptynameand, if given, anhttps://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.docsUrlmust be anhttps://URL, with<,>,",'and`percent-encoded.site.redirects(at most 100): eachfromis one exact path in thepathgrammar, except that a trailing slash is allowed (/master-saas-agreement/); it may not be reserved, and neither it nor its slash twin (/xand/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. Eachtois the exact path of one of the manifest's own pages.site.feeds(at most 5): eachpathis one exact path in thepathgrammar 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'sfromor a server route; it appears once.prefixis a page path ending in/(/blog/, or/for every page), andtitlea non-empty string of at most 300 characters.site.organizationneeds a non-emptyname(at most 300 characters) and anhttps://url;logois anhttps://URL,descriptionat most 1000 characters, andsameAsa list of at most 20https://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:
plansandplans:<appId>:{{#plans}}...{{/plans}}iterates the plans of the declaring app or of the named app, each{id, name, price, currency, period, features[]}, withpricea decimal string such as29or29.50(the server accepts a string, an integer or a decimal, never a float) andcurrencyan upper-case code such asUSD.app:<appId>:{{#app}}...{{/app}}holds{name, description, url}.urlis 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 assettings['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;
}
appis 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 mountsidebarlets an app ask for the shell sidebar collapsed on activation; absent means no opinioncomponentsentries (e.g.Canvas,Toolbar,DataGrid) are never mounted by the shell but are loadable by other apps viauseAppComponent()devToolFrame/devToolSidebarare 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:
iconDark/iconLight(matched to the active palette mode)icon(generic branding icon)- Manifest
iconURL (frompackage.json) - 2-letter monogram fallback
Pre-built theme-aware SVGs are available in shared/assets/rocketride/:
rocketride-dark.svg: light body (#E0DDF0) for dark backgroundsrocketride-light.svg: dark body (#1E1A34) for light backgroundsrocketride.svg:currentColorbody, 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
| Zone | Owner | Content |
|---|---|---|
| Sidebar | Your 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 Area | Your app component | Whatever your app renders |
| Debug Panel | Shell (ALT+D toggle) | Live event log, postMessage traffic |
| Status Bar | Shell | Connection status, app name, ready state |
| Overlays | Shell | Account, 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/Function | Returns | Purpose |
|---|---|---|
useShellConnection() | { client, isConnected, statusMessage } | Access the RocketRide WebSocket client |
useShellApiConfig() | ShellApiConfig | Read runtime config (API URLs, keys, user settings) |
getClient() | RocketRideClient | null | Non-React access to the client singleton |
Auth
| Hook | Returns | Purpose |
|---|---|---|
useAuthUser() | ConnectResult | null | Current authenticated user identity |
useLogout() | () => void | Trigger logout |
useSubscriptions() | { desktopApps, isOnDesktop(appId), getStatus(appId) } | User's desktop apps and subscription state |
Workspace
| Hook | Returns | Purpose |
|---|---|---|
useWorkspace() | IWorkspaceContext | Access 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 settingsactiveAppId: Current app IDappManifest: All registered appsappLoading: Whether the active app is currently loadingloadedApps: Map of already-loaded app descriptors (for cross-app component loading)loadApp(appId): Trigger lazy loading of an app's descriptorupdateAppState(updater): Update per-app state — pass a function receiving the previous state and returning the nextupdateSetting(key, value): Update a single settingupdatePrefs(patch): Update workspace preferencesthemeOptions: Available theme choicessetTheme(themeId): Switch the active themedispatch(action): Update prefs or switch appsemit(event, payload)/on(event, handler): Event bus (delegates to connectionManager)
Workspace Lifecycle: seeded vs loaded
The workspace has a two-phase startup:
-
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. -
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
seededis true. It is then up to each app to decide whether it needs to wait forloaded. - Unauthenticated apps (
authenticated: false) can render immediately on seeded state, they receiveisConnected=falseandidentity=nulland should be designed to work with those values. - Authenticated apps that depend on persisted settings (API keys, saved state) should gate on
loadedbefore 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
loadedis 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
| Event | Payload | Direction | Description |
|---|---|---|---|
shell:connected | {} | Shell → Apps | WebSocket connection established |
shell:disconnected | { reason: string; hasError: boolean } | Shell → Apps | WebSocket connection lost |
shell:login | { user: ConnectResult } | Shell → Apps | User authenticated |
shell:logout | {} | Shell → Apps | User logged out |
shell:loginRequest | { appId?: string; register?: boolean; auto?: boolean; signupProperties?: SignupProperties } | Apps → Shell | Request 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 → Shell | Request logout |
shell:switchApp | { appId: string } | Apps → Shell | Switch the active app |
shell:subscribe | { app: AppManifestEntry, plan?: CheckoutPlan } | Apps → Shell | Open subscription checkout for an app; optional plan preselects a tier and skips the picker (straight to payment) |
shell:myApps | {} | Apps → Shell | Navigate to My Apps |
shell:accountUpdate | ConnectResult | Server → Shell | Server-pushed account/subscription change |
shell:sidebarCollapsing | {} | Shell → Apps | Sidebar is collapsing (for layout adjustments) |
shell:themeChange | { tokens: Record<string, string> } | Shell → Apps | Theme CSS tokens changed |
shell:statusChange | { message: string | null } | Shell → Apps | Transient status bar text changed |
shell:event | { event: unknown } | Server → Apps | Raw server event forwarded from WebSocket |
shell:telemetry | TelemetryFact ({ event: string; props: Record<string, unknown>; ts: number; id: string }) | Shell → Apps | DEPRECATED, never emitted (the shell owns the telemetry transport). Typed only for frozen-floor compatibility; see Telemetry facts |
shell:appsUpdated | { apps: ShellAppEntry[] } | Shell-internal | App list updated |
shell:manifestRefresh | { source: string } | Shell-internal | App manifest re-fetched |
shell:openOverlay | { id: 'account' | 'settings' | 'environment' } | Shell-internal | Open a shell overlay |
shell:unsubscribe | { appId: string } | Shell-internal | Cancel an app subscription |
shell:viewActivated | { viewId: string } | Shell-internal | A 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
| Concept | Description |
|---|---|
| Document | One per URI. Holds content in memory. Tracks dirty state and version. |
| Editor | A view onto a Document. Independent viewport state (scroll, cursor). Multiple editors can view the same document. |
| EditorGroup | A 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:
| Method | Description |
|---|---|
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
PipelineConfigobject - 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
| Field | Type | Default | Description |
|---|---|---|---|
title | string | (required) | Section header (e.g. "Pipelines", "Photos") |
extensions | string[] | null | null | File extensions to filter. Null = show all. |
displayName | (filename: string) => string | Strips known extensions | Custom display name formatter |
createPlaceholder | string | 'file name' | Placeholder for inline create input |
emptyMessage | string | '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:
| Prop | Purpose |
|---|---|
onLaunch | Replace the default launch (shell:switchApp) |
greetingName / greetingOverride | Personalize or pin the greeting |
showQuote | Hide the rotating quote column (default shown) |
allowRemove | Disable the hover X + remove/unsubscribe popover |
resolveIcon | Theme-adaptive icon override per app |
adapter | Override the server operations (DesktopAdapter) |
popoverBoundarySelector | Host sticky-header selector for drop-list placement |
emptyMessage | Zero-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:
| Prop | Purpose |
|---|---|
channel | The 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 |
documents | On multi-document hosts: open(docKey, title) / close(docKey) |
docKey / activeDocKey | The 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:
- Every surface runs in a realm (the shell page, each VS Code webview, each framework page) attached to the shell bus.
- Every realm's
useShellConnection().clientis a realRocketRideClient: 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. - 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
nullwhile 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
| Variable | Purpose |
|---|---|
--rr-bg-default | Main background |
--rr-bg-paper | Card/panel background |
--rr-bg-surface-alt | Hover/alternate background |
--rr-bg-input | Input field background |
--rr-text-primary | Primary text |
--rr-text-secondary | Secondary/muted text |
--rr-text-disabled | Disabled text |
--rr-brand | Brand/accent color |
--rr-border | Border color |
--rr-font-family | Primary font |
--rr-font-family-mono | Monospace font |
--rr-color-success | Success green |
--rr-color-warning | Warning orange |
--rr-color-error | Error 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
nameis derived automatically fromappManifest.idinpackage.json - Always expose
./AppDescriptoras the single MF entry point rocketride/app-sdkmust 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.