Node-Side API
Lookup tables for the node side: DevframeDefinition fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, the cross-devframe services surface, 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 | none |
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. |
DevframeServicesHost
The methods on ctx.services: Cross-Devframe Services.
| Method | Signature | Role |
|---|---|---|
provide | (id, service) => revoke | Publish an in-process service under a namespaced id. Throws DF0037 if the id is taken. |
get | (id) => service | undefined | The service currently provided under id (augmented type, else unknown). |
has | (id) => boolean | Whether a service is provided under id. |
whenAvailable | (id, cb) => unsubscribe | Run cb as soon as the service exists (now if provided, else on provide), and re-fire on revoke/re-provide. |
keys | () => string[] | Ids of every currently-provided service. |
install | (input, options?) => Promise<api | undefined> | Install a wire service at runtime (the dynamic escape hatch; the common path is declarative). options.resolveFrom is the descriptor's resolution base. |
ready | () => Promise<void> | Internal. Construct every queued wire service before any setup runs. Adapters call it; application code uses declarative services. |
Service tiers
The two tiers a service can take: Cross-Devframe Services.
| Tier | Shared how | Registers RPC | Advertised to clients |
|---|---|---|---|
In-process service (provide/get) | live object, node side only | No | No |
Wire service (install / declarative services) | npm package, node API + RPC | Yes, under its scope | Yes, via devframe:services shared state |
Wire-service definition fields
The fields of a DevframeServiceDefinition returned by a service package's create<X>Service factory: Shipping a wire service.
| Field | Type | Description |
|---|---|---|
package | string | Required. npm package name, also its registry key (ctx.services.has(pkg)). |
version | string | Required. Semver; advertised to clients, checked against declared ranges. |
scope | string | Required. RPC namespace its functions register under (e.g. devframes:service:open); setup gets a context pre-scoped to it. |
meta | Record<string, unknown> | Extra advertised metadata (feature flags, defaults). Must be JSON-serializable. |
options | Options | This instance's own option set, baked in by its factory; joins the merge. |
mergeOptions | (sets: Options[]) => Options | Merge multiple installers' option sets. Default: shallow, later wins. |
setup | (ctx, info) => api | Required. Register RPC on the pre-scoped context; return the node API served from ctx.services.get(package). |
Wire-service descriptor fields
The declarative reference form on DevframeDefinition.services / initHub({ services }): Declaring services.
| Field | Type | Description |
|---|---|---|
package | string | Required. npm package name; its default export is the factory the host imports. |
version | string | Accepted semver range. Unsatisfied warns (DF0069), or throws (DF0068) when required. |
required | boolean | Fail hard on a missing package (DF0067) or unsatisfied range. Default false: a missing service is skipped and clients see has() === false. |
options | Options | Option set this installer contributes to the merge. |
Advertised service meta
Each installed service's entry in the devframe:services shared state, mirrored to RPC clients as rpc.services: Feature-detecting on the RPC client.
| Field | Description |
|---|---|
package | npm package name, the registry key. |
version | Installed version of the service. |
scope | RPC namespace its functions live under. |
meta | Extra service-declared metadata. |
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 |
anonymous:devframe:auth:request-code | client → server | { ua, origin, reissue? } → print the code banner in the server terminal (reissue: true rotates the code first) |
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. |