--- title: 'Client Scripts & Client Context' navigation: icon: i-lucide-square-code description: 'A dock client script runs a devframe''s code inside the host page; the client context is how client scripts reach the hub.' --- A dock **client script** runs a devframe's code inside the **host page**; the **client context** is how client scripts reach the hub. > [!WARNING] Experimental > The hub API is still being refined. Names may change before 1.0. ## The client runtime `createDevframeClientRuntime()` (`@devframes/hub/client`) boots the host page: it connects (or adopts) an RPC client, publishes the `DevframeClientContext`, and imports each dock's client script: ```ts // main.ts: the host page's browser entry import { connectDevframe, createDevframeClientRuntime } from '@devframes/hub/client' const rpc = await connectDevframe({ baseURL: '/__hub/' }) const { context, dispose } = await createDevframeClientRuntime({ rpc }) ``` ### Options Pass an already-connected `rpc` (or `connect` options for `connectDevframe`), the page's `clientType` (`'standalone'` by default, `'embedded'` inside a user app), `loadClientScripts: false` to skip dock client scripts, and boot-time `renderers` (which win over the hub's [renderer manifest](/guide/hub-initiate#renderer-modules)); see the [Hub API reference](/references/hub-api#client-runtime-options). A second boot replaces the context and warns; `dispose()` tears down listeners and unpublishes it. ## The client context The context carries the [RPC client](/guide/client) (`rpc`) and the page's `clientType`, plus six hub facets: `docks` (entries, selection, [client-only registration](#client-only-docks)), `panel` (dock panel state), `commands` (the command palette), `renderers` (the dock-renderer registry), `when` (the [when-clause](/references/when-clauses) context), and `connection` (live [connection status](/guide/client#handling-connection-and-auth-errors)). Every property is in the [Hub API reference](/references/hub-api#client-context-properties). ### Accessing the context `getDevframeClientContext()` returns the context anywhere; `undefined` before boot. ### Tracking panel state `ctx.panel.state` is the current dock panel snapshot. It contains `state: 'open' | 'closed' | 'hidden'` and includes `selectedDockId` while a dock is selected. Subscribe to [`ctx.panel.events`](/references/events#client-context-events) for later changes: ```ts import type { DockClientScriptContext } from '@devframes/hub/client' import { HUB_EVENTS } from '@devframes/hub/constants' export default function setup(context: DockClientScriptContext) { const reportPanelState = (panelState: typeof context.panel.state) => { void context.rpc.call('my-devframe:panel-state', panelState).catch(error => console.error(error)) } reportPanelState(context.panel.state) context.panel.events.on( HUB_EVENTS.client.docksPanelStateChanged, reportPanelState, ) } ``` The custom RPC keeps node-side reporting opt-in. ### Client-only docks A client runtime can register a dock local to the host page (unlike [node hub context](/guide/hub) docks synced via `devframe:docks`). `ctx.docks.register(entry)` (e.g. `type: 'custom-render'` with `renderer: { importFrom }`) returns a handle whose `update({ badge })` patches in place (id immutable) and `dispose()` removes it. One sharing a server dock's id overrides it locally; re-registering an owned id throws unless you pass `register(entry, true)`. A client-only dock can also carry `type: 'json-render'` with an inline [JSON-render](/guide/json-render) `view: { spec }` (a `DevframeJsonRenderSpec` built in-browser), rendered when a `json-render` renderer is registered at boot. `view` also accepts `{ stateKey }` for live shared state (from `createJsonRenderView`). ## Dock client scripts A client script is a `ClientScriptEntry`: `{ importFrom, importName?, eager? }`. `importName` defaults to `'default'` and `eager` defaults to `false`. An `iframe` entry's optional `clientScript` runs inside the host page when the dock entry is first activated. An `action` entry runs its `action` on each activation, while a `custom-render` entry initializes its `renderer` after selection so it can mount into the panel. Set `eager: true` on an `iframe` `clientScript` or an `action` to initialize it as soon as the RPC connection is trusted, before opening a dock panel. This suits background subscriptions and page commands, such as an `action` that registers page commands or subscribes to `entry:activated` before its first click. A `custom-render` `renderer` needs its mounted panel, so it always initializes on activation. Both the reference hub UI and `createDevframeClientRuntime()` honor these settings ([Hub API reference](/references/hub-api#dock-client-script-fields)). The exported function (`DockClientScriptContext`) receives the client context and two dock-scoped extras: - **`current`** holds this entry's state: `entryMeta`, `isActive`, `domElements`, `events` (`entry:activated`, `entry:deactivated`, `entry:updated`, `dom:panel:mounted`, `dom:iframe:mounted`). - **`messages`**: an entry-scoped messages client (`category` defaults to the entry id; `info`/`warn`/`error`/`success`/`debug` shortcuts for `add()`). Failed setup retries on the next activation, or on a dock update for eager scripts. Setup is cached per RPC connection, dock and import descriptor. Action clicks always execute again, except for a [toggle action](#toggle-actions). ### Toggle actions Set `toggle: true` on an `action` entry to make it an on/off tool, such as an in-page element picker. A click turns it on and a second click turns it off. While it is on: - the dock button shows as active (`current.isActive` is `true`); - the selected dock stays selected, and an open panel is hidden until the tool turns off; - `Escape` turns it off in the reference hub UI. The script sets up once and drives the tool from `entry:activated` / `entry:deactivated`. Call `docks.setActionActive(id, false)` when the tool is done, which brings the hidden panel back. Selecting another dock, or `switchEntry(null)`, also turns the tool off, and then the panel stays as the new selection leaves it. ```ts // Dock entry: { type: 'action', toggle: true, action: { importFrom } } import type { DockClientScriptContext } from '@devframes/hub/client' export default function setup(ctx: DockClientScriptContext) { const id = ctx.current.entryMeta.id ctx.current.events.on('entry:activated', () => { startPicker({ onPick: () => ctx.docks.setActionActive(id, false) }) }) ctx.current.events.on('entry:deactivated', () => stopPicker()) } ``` ### Shipping a client script `importFrom` accepts three shapes: - **A URL served by the host framework**: a self-contained ES module; works on every host framework. - **A bare npm specifier** (`'vite-plugin-vue-tracer/client/vite-devtools'`): resolved through the host framework. - **An absolute filesystem path**, declared on the definition's `dock.clientScript`. The hub serves its directory under `__page-script/` and rewrites `importFrom` to that URL, so mounting by package name needs no host wiring. Per-mount, attach a URL via `ctx.install(myDevframe, { dock: { clientScript: { importFrom } } })`; under Vite `/@fs/` serves it, and other host frameworks mount the directory statically. ### Bare npm specifiers Resolving a bare specifier is the **host framework's capability**: a host framework advertises a resolution template at `ConnectionMeta.configs.dock.clientModuleResolution` (loaders replace `{specifier}` before import). A Vite host declares this by default (`@devframes/vite/hub`) as `initHub({ clientModuleResolution: '/@id/{specifier}' })`; then use the specifier alone as `importFrom`. A host framework with no template (Next.js) supports the URL shape only, warning [`DF8111`](/errors/DF8111) on a specifier. A hub UI provider can override with `createDevframeClientRuntime({ resolveClientModule })`. Client scripts execute in the user app's page realm (`window`); anchor shared state on `globalThis`. ### Dual boots One bundle can serve as both a client script (default export) and, via a globally-guarded self-boot, a standalone page script ([a11y inspector](/add-ons/devframes/a11y)). ## Iframe panels Dock iframes are their own documents: the panel calls `connectDevframe()`, discovering `./__connection.json` from its base. A client script and an iframe panel share the node side via RPC and shared state, or talk directly (server-free, static-build-friendly) over the [in-page channel](/guide/in-page-channel). ## Shared-iframe soft navigation A tool with many internal views (Nuxt DevTools' tabs) can surface each as a hub dock sharing **one** live iframe: the **anchor** owns a `frameId` and opts in via `ctx.install(…, { dock: { frameId, subTabs: { protocol: 'postmessage' } } })`. On mount, the client runtime attaches a **frame-nav adapter** speaking an origin-locked `postMessage` protocol on `devframe:frame-nav`: the iframe reports its tab list (`ready` / `manifest`), the host page requests a view (`navigate`), and the iframe reports internal navigation back (`navigated`). Message shapes are in the [Hub API reference](/references/hub-api#frame-nav-messages). It materializes a [client-only dock](#client-only-docks) per tab (id `:`) sharing the anchor's `frameId` and a `navTarget`, independent of [`groupId`](/guide/hub#grouping-dock-entries). ### The hub UI provider's part A hub UI provider keeps one iframe alive per `frameId` (shown/hidden); on mount, it sets the element on the anchor's `docks.getStateById(anchorId)` state (`domElements.iframe`) and emits `dom:iframe:mounted`. See the "Tabbed Tool" in [`examples/custom-hub-vite`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite) / [`custom-hub-next`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next).