Node-Side API

Lookup tables for the node side: DevframeDefinition fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, diagnostics prefixes, and the auth surface.

Lookup tables for a devframe's node side. Each section links the guide page that teaches the concept.

Definition fields

The fields of a DevframeDefinition — Devframe Definition.

Field	Type	Description
`id`	`string`	Required. Unique namespaced id (kebab-case); prefixes RPC/dock/MCP-tool names.
`name`	`string`	Required. Display name (dock, agent manifests).
`version`	`string`	Required. Semver; shown in hub UIs, diagnostics.
`packageName`	`string`	Required. npm package (`@scope/my-tool`).
`importMetaUrl`	`string`	Recommended. Pass `import.meta.url` — the deps resolution base: default `resolveFrom` for remote assets and declared services.
`homepage`	`string`	Required. Homepage/docs URL.
`description`	`string`	Required. One-line summary.
`icon`	`string \| { light, dark }`	Optional Iconify name or URL; light/dark pairs.
`basePath`	`string`	Optional mount-path override. Default `/` standalone (`cli`/`build`), `/__<id>/` hosted (`vite`/`embedded`).
`duplicationStrategy`	`'warn' \| 'silent' \| 'throw' \| 'duplicate'`	Hub reaction when another devframe shares this `id`. Default `'warn'`. See Duplication strategies; standalone adapters ignore it.
`capabilities`	`{ dev?, build? }`	Per-runtime feature flags. `boolean` = whole runtime; object = individual features.
`services`	`DevframeServiceInput[]`	Wire services consumed — descriptors (`{ package, version?, required?, options? }`) imported against the devframe's own deps, or ready definitions. See Cross-Devframe Services.
`clientAssets`	`string \| RemoteAssets`	Built SPA served as the UI — local dist dir or remote assets. Read by every UI-serving adapter (`dev`, `build`, `vite`, `next`, hub).
`rpc`	`{ snapshot?: (string \| { method, inputs })[] }`	RPC config. `rpc.snapshot` opts an RPC this devframe doesn't own into the static dump. Bare method id bakes the no-arg call; `{ method, inputs }` bakes one record per argument-tuple (`inputs` = tuples or async `(ctx) => tuples`). First tuple = fallback.
`setup`	`(ctx, info?) => void \| Promise<void>`	Required. Server-side entry point, run in every runtime. Optional 2nd arg carries runtime metadata — notably parsed CLI `flags` under `createCac`.
`cli`	`DevframeCliOptions`	CLI adapter defaults. See CLI options.

CLI options

The cli field's DevframeCliOptions — CLI options.

Field	Type	Description
`command`	`string`	Binary name in `--help`. Default: the `id`.
`port`	`number`	Preferred dev-server port.
`portRange`	`[number, number]`	Port scan range (`get-port-please`).
`random`	`boolean`	Prefer a random open port.
`host`	`string`	Default bind host.
`open`	`boolean \| string`	`true` = origin, string = a path, `false` = off (`--open`/`--no-open`). With `auth`, embeds the OTP.
`auth`	`boolean`	Disable WS trust flow when localhost-only, single-user. Default `true`.
`configure`	`(cli: CAC) => void`	Contribute flags/commands before `createCac`'s `configureCli`.

Storage scopes

The three classes ctx.host.getStorageDir(scope) places persisted state in — Storage scopes.

Scope	Placement	For
`workspace`	committable, `<workspaceRoot>/.devframe/`	team-shared: saved presets, config
`project`	per-checkout, `<cwd>/node_modules/.<app>/devframe/`	caches, personal settings
`global`	per-user, `~/.<app>/devframe/`	auth tokens, machine-wide prefs

RPC function types

The type field of defineRpcFunction — RPC.

Type	Description	Cached	Static Dump
`query`	Read operation that can change over time.	Opt-in via `cacheable`	Manual (declare `dump`)
`static`	Data that never changes for a given input.	Indefinitely	Automatic
`action`	Mutation with side effects.	Never	Never
`event`	Fire-and-forget; no response.	Never	Never

Broadcast options

The options of rpc.broadcast — Broadcasting.

Option	Type	Description
`method`	browser-side RPC name	Browser-side function to call.
`args`	any	Arguments for the browser-side function.
`optional`	`boolean`	Don't throw if no RPC client is listening.
`event`	`boolean`	Fire-and-forget.
`filter`	`(client) => boolean`	Skip specific RPC clients.

Streaming lifecycle

How each lifecycle event lands on both sides of a streaming channel — Streaming.

Event	Node side	Browser side
`stream.close()` / `stream.error(err)`	broadcasts `end`	`for await` resolves or throws
`reader.cancel()`	aborts `stream.signal` on last-subscriber cancel	`for await` ends
WS disconnects	aborts `stream.signal` on last-subscriber drop	reader survives, resubscribes on re-trust
`chat` panel closes	cancels upstream	—

Remote assets options

The fields of a RemoteAssets source for clientAssets and hostStatic — Remote assets.

Field	Purpose
`package`	npm package with the built assets.
`version`	Exact version, usually your `pkg.version`.
`resolveFrom`	Local-path resolution base. Defaults to `importMetaUrl`; `null` skips to cache + CDN.
`path`	Subpath the assets live under (default `dist`).
`provider`	`'jsdelivr'` (default), `'unpkg'`, or a custom provider (internal mirror).
`offline`	`true` serves only from local install or cache, never network.

Diagnostic code prefixes

Prefixes in use across the ecosystem — Structured Diagnostics.

Prefix	Owner
`DF`	`devframe`
`DTK`	`@vitejs/devtools` (Vite-specific)
`RDDT`	`@vitejs/devtools-rolldown`
`VDT`	`@vitejs/devtools-vite` (reserved)

Auth methods

The wire-level RPC methods of the trust handshake — Security.

RPC method	Direction	Shape
`anonymous:devframe:auth`	client → server	`{ authToken, ua, origin }` → `{ isTrusted }` — re-authenticate a stored token
`anonymous:devframe:auth:exchange`	client → server	`{ code, ua, origin }` → `{ authToken \| null }` — exchange a code for a token
`devframe:auth:revoke`	client → server	self-revoke the caller's own token
`devframe:auth:revoked`	server → client	event — token revoked

Node auth primitives

The building blocks in devframe/node/auth — Security.

Function	Role
`getTempAuthCode()` / `refreshTempAuthCode()`	read / rotate the one-time code
`exchangeTempAuthCode(code, session, { ua, origin }, storage)`	verify a code, mint + store the token, trust the session, return it (or `null`)
`verifyAuthToken(token, session, storage)`	trust a session presenting a known token
`buildOtpAuthUrl(origin, code?)`	build a magic-link URL embedding the code
`revokeAuthToken(context, storage, token)`	delete a token and disconnect sessions using it

MCP CLI commands

The agent-facing CLI surface — Agent-Native Devframe.

Command	Description
`<your-app> mcp`	Start the MCP server on `stdio`.
`<your-app> dev --mcp`	Serve the agent-consumable API on `/__mcp`.
`devframe connect`	Discover running devframes and proxy their tools — see MCP adapter.

Events Reference

Devframe carries change notifications across channels of differing direction and reach: a node event bus, server RPC, and server-pushed broadcasts and shared state.

Browser-Side API

Lookup tables for the browser side: connectDevframe options, RPC client events, connection statuses, and in-page channel error codes.