Hub API
Lookup tables for @devframes/hub: its node-side subsystems and its browser-side client runtime. Each section links the guide page that teaches the concept.
Hub subsystems
What DevframeHubContext adds to DevframeNodeContext: Hub.
| Subsystem | API | Purpose |
|---|---|---|
ctx.docks | register / update / values / activate | Dock entries (iframes, launchers, custom-render) and groups; activate(dockId, params?) sets the active dock (Cross-iframe dock activation). |
ctx.terminals | register / startChildProcess / startPtySession | Aggregate terminal sessions, streaming output (Terminals). |
ctx.messages | add / update / remove / clear | Server-side toast/notification queue (FIFO, capped at 1000). |
ctx.commands | register / execute / list | Hierarchical command palette with keybindings and when clauses. |
Launcher fields
The optional launcher fields that make a type: 'launcher' dock entry a live process controller: Process-control launchers.
| Field | Purpose |
|---|---|
command | Bound command id; out-of-process hub UI providers dispatch via hub:commands:execute (register a handler via ctx.commands). |
terminalSessionId | Tracked session id; a "view in terminal" action calls hub:docks:activate with the terminals dock id and { sessionId }. |
digest | Latest progress line, shown inline; patch via docks.update(). |
Duplication strategies
The duplicationStrategy values deciding what happens when a devframe shares an already-mounted id: Duplicate devframes.
| Strategy | Behavior |
|---|---|
'warn' (default) | Keep the first, drop the later, emit DF8105. |
'silent' | Drop the later one without warning. |
'throw' | Throw DF8105. |
'duplicate' | Every instance coexists under a disambiguated dock id (my-tool, my-tool-2, …). |
Dock categories
DEFAULT_CATEGORIES_ORDER (from @devframes/hub, /node, /client, /constants) names the default dock-rail buckets: The dual role of category.
| Category | Weight | Typical use |
|---|---|---|
framework | -100 | Framework internals. |
default | 0 | Uncategorized. |
app | 100 | App tools. |
ui | 150 | Components, styling. |
data | 250 | State, storage, queries. |
web | 300 | Network, platform, a11y. |
performance | 350 | Profiling, metrics. |
advanced | 400 | Power-user tools. |
docs | 500 | Documentation. |
~builtin | 1000 | Built-in views; always last. |
Hub UI protocol
The shared-state keys and RPC methods a hub UI provider renders from: The hub UI protocol.
| Channel | Type | What it carries |
|---|---|---|
devframe:docks shared state | DevframeDockEntry[] | Every registered dock entry. |
devframe:commands shared state | DevframeServerCommandEntry[] | Serializable command list (handlers stripped). |
devframe:user-settings shared state | DevframeDocksUserSettings | Persisted project-scope hub settings. |
devframe:docks:active shared state | DevframeDocksActiveState | Most recent dock activation request. |
hub:commands:execute RPC | (id, ...args) => unknown | Server-side command dispatch. |
hub:docks:activate RPC | ({ dockId, params? }) => void | Switch the active dock. |
Hub namespace routes
What initHub() serves under its base: The namespace.
| Path | Serves |
|---|---|
/ | the ui.viewer SPA, or index document when headless |
<id>/ | each devframe's SPA + own __connection.json → shared socket |
embedded.js | the ui.embedded bootstrap (404 if none) |
__connection.json | meta for the shared RPC socket |
__ws | WebSocket upgrade route |
__index.json | machine-readable index: mounted devframes, endpoints |
__client-imports.js | dock client-script import map for hub UI providers |
__mcp | aggregate MCP endpoint over the tool registry (mcp: 'auto' default: mounted once agent tools exist) |
Onboarding options and routes
What createOnboarding() from @devframes/hub-ui-onboard accepts and serves: Opt-in DevTools with Onboarding.
| Option | Default | Meaning |
|---|---|---|
packages | required | Package specs the Install button adds |
base | /__devframes/ | Mount base, shared with the hub that takes over later |
cwd | process.cwd() | Project that receives the dependency and whose lockfile picks the package manager |
stateDir | <cwd>/node_modules/.devframe | Directory of the hub-ui-onboard.json state file |
dev | true | Install as a devDependency |
branding | {} | productName (default Devframes), logo (URL or { light, dark }), primaryColor |
messages | derived from productName | Overrides for title, description, install, hide, disable, installing, restart, retry |
onInstalled | none | Runs after a verified install, or on the first request when the packages already exist; a returned handler takes over base |
| Route | Serves |
|---|---|
GET <base>embedded.js | the floating button, a self-contained ES module |
GET <base>__onboard/status | { state, command, branding, messages, error? } |
POST <base>__onboard/install | starts the install (202), same-origin only |
POST <base>__onboard/disable | writes the state file (204), same-origin only |
state | Meaning |
|---|---|
idle | nothing installed yet; the panel offers Install |
installing | the package manager is running; the button polls once a second |
installed | installed, no hub handler to hand off to; the panel asks for a restart |
ready | onInstalled returned a handler; the button loads the real embedded.js and removes itself |
error | the install or onInstalled failed; error.code is a DF90xx diagnostic |
disabled | the user chose Disable entirely; the button renders nothing |
buildHub options
The options of buildHub() from @devframes/hub/build: Static builds. devframes, services, rpcDeclarations, configure, ui, renderers, name, version, cwd, and getStorageDir carry the same contracts as their initHub counterparts.
| Option | Purpose |
|---|---|
outDir | Output directory for the hub subtree; corresponds to base at serve time (build base: '/__devframes/' into dist/__devframes). A mount served outside the hub base (a devframe SPA or asset dir kept as a sibling of it) is written to this directory's parent (the deploy root) by its absolute path. |
base | Mount base baked into every absolute URL the build emits. Default /__devframes/. |
context | An already-mounted DevframeHubContext to bake instead of devframes (the build counterpart of initHub({ context })); reads ctx.frames and ctx.views.buildStaticDirs. Mutually exclusive with devframes. |
clean | Remove outDir before writing. Default true; set false to bake beside an app's own build output. |
pretty | Pretty-print RPC dump JSON shards. Default false (minified). |
Client runtime options
The options of createDevframeClientRuntime(): The client runtime.
| Option | Description |
|---|---|
rpc | An already-connected DevframeRpcClient; when omitted, created via connectDevframe(connect). |
connect | Forwarded to connectDevframe when rpc is omitted (e.g. baseURL). |
clientType | 'standalone' (default) owns the page; 'embedded' runs inside a user app alongside a panel. |
loadClientScripts | Import and run dock client scripts (default true). |
renderers | Dock renderers registered at boot, keyed by dock type; local wins over the hub's renderer manifest. |
Client context properties
The properties of DevframeClientContext: The client context.
| Property | Description |
|---|---|
rpc | The RPC client: server/client functions, shared state. |
clientType | 'embedded' (inside the user app) or 'standalone' (independent hub page). |
docks | entries, selected, groupedEntries, switchEntry(), toggleEntry(), getStateById(), register() / update() for client-only docks. |
panel | Current state, local events, session, position, size, and drag/resize state for the dock panel. |
commands | Command palette: register(), execute(), getKeybindings(), paletteOpen, paletteScopeId, openPalette(atCommandId?). Passing an id opens the palette drilled into that command's children (Activating a group). |
renderers | Dock-renderer registry: register(), get(), has(), mount(entry, container). Routes a dock type to a renderer (local boot or the hub's manifest; local wins). mount() resolves a status: mounted (with dispose), missing-renderer, or load-error (with error). |
when | The when-clause context. |
connection | Live connection status: status, error, events. |
Dock client script fields
Which ClientScriptEntry field carries an entry's client script, and when it runs: Dock client scripts.
| Entry kind | Field | Runs |
|---|---|---|
action | action | when the dock button is activated |
custom-render | renderer | to render the entry's panel |
iframe | clientScript (optional) | inside the host page on first activation |
ClientScriptEntry.eager defaults to false. Set it to true on an iframe clientScript or an action to initialize it after RPC trust, before dock activation. A custom-render renderer needs its mounted panel, so it always initializes on activation regardless of eager. Setup is cached per RPC connection and dock; action clicks execute on every activation.
Frame-nav messages
The origin-locked postMessage protocol on devframe:frame-nav: Shared-iframe soft navigation.
| Message | Direction | Meaning |
|---|---|---|
ready / manifest | iframe → host page | tab list ({ tabs, current }), on load and change |
navigate | host page → iframe | show a view ({ tabId, navTarget }); the SPA routes client-side |
navigated | iframe → host page | the SPA navigated internally; the hub UI provider highlights the dock |
Dock entry types
The built-in variants of the open dock union (DevframeDockEntryRegistry, @devframes/hub/types) a hub UI provider renders: Build Your Own Hub UI. Each entry's icon takes any of the icon values. Each entry's title has an optional titleLocales map of translations, resolved with resolveTitle(entry, locale) from @devframes/hub/client; commands and launchers carry the same pair.
| Type | The hub UI provider renders |
|---|---|
iframe | the entry's url in a kept-alive iframe (per frameId when shared); honor subTabs soft nav; show the existing address bar with addressBar: true, or configure Back, Reload, and Open externally by passing an addressBar object |
action | a dock-rail button; activating runs its client script |
custom-render | a container its client script mounts into |
launcher | a launch call-to-action reflecting launcher.status |
group | one dock-rail button collapsing its member entries |
~builtin | your native views (settings, feeds) for reserved ids |