--- title: 'Node-Side API' navigation: icon: i-lucide-server-cog description: '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](/guide/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](/guide/client-assets) and declared [services](/guide/services#wire-services). | | `homepage` | `string` | **Required.** Homepage/docs URL. | | `description` | `string` | **Required.** One-line summary. | | `icon` | `string \| { light, dark }` | Optional Iconify name, image URL, light/dark pairs, etc. See [Icon values](#icon-values). | | `basePath` | `string` | Optional mount-path override. Default `/` standalone (`cli`/`build`), `/__/` hosted (`vite`/`embedded`). | | `duplicationStrategy` | `'warn' \| 'silent' \| 'throw' \| 'duplicate'` | Hub reaction when another devframe shares this `id`. Default `'warn'`. See [Duplication strategies](/references/hub-api#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](/guide/services#wire-services). | | `clientAssets` | `string \| RemoteAssets` | Built SPA served as the UI: local dist dir or [remote assets](/guide/client-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` | **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). | ## Icon values The `icon` field, and every dock entry, command, and terminal icon, accept the same string forms. A `{ light, dark }` pair picks the matching variant per active color scheme, and each side takes any of these forms: | Form | Example | Rendered as | |---|---|---| | Iconify name | `ph:gauge-duotone`, `logos:nuxt-icon` | the `collection:icon` glyph, fetched from Iconify as inline SVG | | Image URL | `/icons/logo.svg`, `https://example.com/logo.png` | an ``; relative URLs resolve against the supplying hub | | Data URL | `data:image/svg+xml,%3Csvg…%3E` | an inline `` from the embedded data | | SVG mask | `mask:/icons/logo.svg`, `mask:data:image/svg+xml,%3Csvg…%3E` | an alpha mask tinted with `currentColor`, following the surrounding text color | | Light/dark pair | `{ light: './logo-light.svg', dark: './logo-dark.svg' }` | the variant matching the active color scheme; each side is any string form above | The reference hub UI and terminal SPA render `mask:` icons with the surrounding text color, preserving the image's shape and opacity, so a bundled monochrome SVG follows the dock's foreground color through selected and dimmed states. For a bundled SVG, use `` `mask:data:image/svg+xml,${encodeURIComponent(svg)}` ``. A mask produces one color; use an ordinary image URL for multicolor artwork. Relative mask URLs on dock entries resolve against the supplying hub's URL. Custom hub UI providers implement this string convention in their own icon renderer. ## CLI options The `cli` field's `DevframeCliOptions`: [CLI options](/guide/devframe-definition#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](/guide/devframe-definition#storage-scopes). | Scope | Placement | For | |-------|-----------|-----| | `workspace` | committable, `/.devframe/` | team-shared: saved presets, config | | `project` | per-checkout, `/node_modules/./devframe/` | caches, personal settings | | `global` | per-user, `~/./devframe/` | auth tokens, machine-wide prefs | ## RPC function types The `type` field of `defineRpcFunction`: [RPC](/guide/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](/guide/rpc#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](/guide/streaming#lifecycle-and-cancellation). | 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](/guide/client-assets#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](/guide/services#the-devframeserviceshost-api). | Method | Signature | Role | |--------|-----------|------| | `provide` | `(id, service) => revoke` | Publish an in-process service under a namespaced id. Throws [`DF0037`](/errors/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` | Install a [wire service](#wire-service-definition-fields) at runtime (the dynamic escape hatch; the common path is declarative). `options.resolveFrom` is the descriptor's resolution base. | | `ready` | `() => Promise` | **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](/guide/services). | Tier | Shared how | Registers RPC | Advertised to clients | |------|-----------|---------------|-----------------------| | In-process service (`provide`/`get`) | live object, node side only | No | No | | [Wire service](/guide/services#wire-services) (`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 `createService` factory: [Shipping a wire service](/guide/services#shipping-one). | 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` | 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](/guide/services#declaring). | 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`](/errors/DF0069)), or throws ([`DF0068`](/errors/DF0068)) when `required`. | | `required` | `boolean` | Fail hard on a missing package ([`DF0067`](/errors/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](/guide/shared-state), mirrored to RPC clients as `rpc.services`: [Feature-detecting on the RPC client](/guide/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](/guide/diagnostics#code-conventions). | 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](/guide/security#authentication-flow). | 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](/guide/security#the-ready-made-layer). | 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](/guide/agent-native). | Command | Description | |---------|-------------| | ` mcp` | Start the MCP server on `stdio`. | | ` dev --mcp` | Serve the agent-consumable API on `/__mcp`. | | `devframe connect` | Discover running devframes and proxy their tools; see [MCP adapter](/adapters/mcp#discovery-devframe-connect). |