RPC

Devframe's RPC layer is type-safe bidirectional communication between your server (Node.js) and client (browser), built on birpc and validated at runtime with valibot. In dev mode it runs over WebSocket; in build / SPA mode it serves a pre-computed static dump so the client still works offline.

Overview

Defining a function

import { defineRpcFunction } from 'devframe'
import * as v from 'valibot'

export const getModules = defineRpcFunction({
  name: 'get-modules', // bare — the scope namespaces it to `my-devframe:get-modules`
  type: 'query',
  args: [v.object({ limit: v.number() })],
  returns: v.array(v.object({ id: v.string(), size: v.number() })),
  setup: ctx => ({
    handler: async ({ limit }) => {
      // `ctx` is the full DevframeNodeContext.
      return loadModules().slice(0, limit)
    },
  }),
})

Register it in setup through a scoped context — ctx.scope(id) auto-namespaces ids, so you register and call by bare name:

import { defineDevframe } from 'devframe'
import { getModules } from './rpc/functions/get-modules'

export default defineDevframe({
  id: 'my-devframe',
  name: 'My Devframe',
  setup(ctx) {
    const my = ctx.scope('my-devframe')
    my.rpc.register(getModules)
  },
})

The unscoped ctx.rpc.register(getModules) works too — it's the underlying primitive the scoped surface wraps.

Place each function in its own file under src/rpc/functions/, and barrel them in src/rpc/index.ts as const serverFunctions = [...] as const. The same array feeds the type-safe client registry and keeps registration order explicit. When per-file functions need to share setup-time state (channels, shared state handles, loaders), expose it through a WeakMap<DevframeNodeContext, T> in a sibling src/context.ts.

Naming convention

Scope with your devframe id and use kebab-case for the action: my-devframe:get-modules, my-devframe:read-file, my-devframe:trigger-rebuild. A scoped context applies this prefix for you: ctx.scope('my-devframe').rpc.register({ name: 'get-modules' }) stores my-devframe:get-modules. Define each function with a bare name and let the scope namespace it.

Function types

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

Use static for data collected once during setup and shipped to read-only static / SPA clients.

Handler arguments

Handlers accept any serializable arguments. With args valibot schemas, arguments are validated at the boundary:

defineRpcFunction({
  name: 'get-file',
  type: 'query',
  args: [v.object({ path: v.string(), includeSource: v.optional(v.boolean()) })],
  returns: v.object({ path: v.string(), source: v.optional(v.string()) }),
  setup: () => ({
    handler: async ({ path, includeSource }) => ({
      path,
      source: includeSource ? await readFile(path, 'utf-8') : undefined,
    }),
  }),
})

Prefer a single object argument (args: [v.object({ ... })]) over positional args — property names are self-describing and agents/IDEs work best with object shapes.

Setup vs handler

Two ways to wire a handler:

setup(ctx) — receives the DevframeNodeContext and returns { handler, dump? }. Use this when you need the context (shared state, logs, ctx.mode, etc.).
handler(...) — shorthand when the handler is pure and doesn't touch the context.

// With setup:
defineRpcFunction({
  name: 'count',
  type: 'query',
  setup: ctx => ({
    handler: async () => ctx.rpc.sharedState.keys().length,
  }),
})

// Shorthand:
defineRpcFunction({
  name: 'echo',
  type: 'query',
  handler: (msg: string) => msg,
})

Broadcasting

rpc.broadcast sends a message from the server to every connected client. Through a scoped context the client method name is namespaced for you:

defineDevframe({
  id: 'my-devframe',
  name: 'My Devframe',
  setup(ctx) {
    const my = ctx.scope('my-devframe')
    watcher.on('change', (file) => {
      void my.rpc.broadcast({
        method: 'on-file-changed', // -> my-devframe:on-file-changed
        args: [{ file }],
      })
    })
  },
})

Option	Type	Description
`method`	client RPC name	Function registered on the client side.
`args`	any[]	Arguments passed to the client function.
`optional`	`boolean`	Don't throw if no client is listening.
`event`	`boolean`	Fire-and-forget (don't wait for responses).
`filter`	`(client) => boolean`	Skip specific clients.

Streaming

For chunk-style server→client feeds (chat deltas, log lines, build progress), use streaming channels — they handle stream IDs, cancellation, replay, and Web Streams interop for you:

const channel = ctx.rpc.streaming.create<string>('my-devframe:chat', {
  replayWindow: 256,
})
const stream = channel.start()
sourceReadable.pipeTo(stream.writable)

See the Streaming guide for the full API.

Local invocation

A scoped rpc.call invokes a registered server function directly, skipping the transport — useful for cross-function composition on the server side. Bare names resolve within the namespace:

const my = ctx.scope('my-devframe')
const modules = await my.rpc.call('get-modules', { limit: 10 })

This wraps ctx.rpc.invokeLocal('my-devframe:get-modules', { limit: 10 }). Pass a fully-qualified name (containing :) to call another tool's function.

Client-side calls

From the browser, connectDevframe (or getDevframeRpcClient) returns a client. Scope it the same way to call registered functions by bare name:

import { connectDevframe } from 'devframe/client'

const client = await connectDevframe()
const my = client.scope('my-devframe')

const modules = await my.rpc.call('get-modules', { limit: 10 })

Client-side registration (for server→client calls) goes through my.rpc.register() — the mirror API of the server-side scoped rpc.register().

Type-safe client registry

Devframe exposes two augmentable interfaces — DevframeRpcServerFunctions (client→server calls) and DevframeRpcClientFunctions (server→client calls) — so each registered RPC name shows up on the typed client. Augment them once per devframe via declare module 'devframe'.

The recommended pattern collects every server-side definition into a const array and feeds it through RpcDefinitionsToFunctionsWithNamespace — it prefixes each bare definition name with your devframe id, matching the ids the scoped register stores at runtime:

import type { RpcDefinitionsToFunctionsWithNamespace } from 'devframe/rpc'
import { getFile, getModules } from './rpc'

const serverFunctions = [getModules, getFile] as const

declare module 'devframe' {
  interface DevframeRpcServerFunctions
    extends RpcDefinitionsToFunctionsWithNamespace<'my-devframe', typeof serverFunctions> {}
}

If you define functions with full namespaced names instead, use RpcDefinitionsToFunctions<typeof serverFunctions> (no namespace argument) and register them through the unscoped ctx.rpc.register.

Now connectDevframe() returns a client where every registered name is autocompletable and argument-typed:

import { connectDevframe } from 'devframe/client'

const my = (await connectDevframe()).scope('my-devframe')
const modules = await my.rpc.call('get-modules', { limit: 10 })
//                          ^? typed from the augmentation above

For one-off augmentations, declare a single key with RpcFunctionDefinitionToFunction:

import type { RpcFunctionDefinitionToFunction } from 'devframe/rpc'

declare module 'devframe' {
  interface DevframeRpcServerFunctions {
    'my-devframe:get-modules': RpcFunctionDefinitionToFunction<typeof getModules>
  }
}

For server→client calls invoked via ctx.rpc.broadcast, augment DevframeRpcClientFunctions the same way.

Static dumps

For static functions, Devframe records the handler's output during createBuild and bakes it into the build:

defineRpcFunction({
  name: 'build-meta',
  type: 'static',
  args: [],
  returns: v.object({ version: v.string(), builtAt: v.number() }),
  setup: () => ({
    handler: async () => ({ version: '1.0.0', builtAt: Date.now() }),
  }),
})

For query functions, provide an explicit dump to enumerate which argument sets to pre-compute:

defineRpcFunction({
  name: 'get-session',
  type: 'query',
  setup: ctx => ({
    handler: async (id: string) => loadSession(id),
    dump: {
      inputs: [['session-a'], ['session-b']],
      fallback: { id: 'unknown', data: null },
    },
  }),
})

At runtime, static clients resolve my.rpc.call('get-session', 'session-a') from the baked dump; unmatched arguments resolve to dump.fallback (or throw without one).

JSON-serializable declaration

Devframe's WS transport ships payloads using one of two encoders, picked per RPC function:

`jsonSerializable`	Encoder	Wire prefix	Round-trips
`false` (default)	`structured-clone-es`	`s:`	`Map`, `Set`, `Date`, `BigInt`, cycles, class instances
`true` (opt-in)	strict `JSON.stringify`	(unprefixed)	JSON-only

The wire stays plain JSON when every participating function is JSON-flagged — debuggable in Devframe, friendly to MCP, and a good default for tools that already speak JSON.

Discovering shape errors during dev

jsonSerializable: true is a contract. When a handler returns a value JSON cannot round-trip (a Map, a Date, a class instance, …), the strict serializer throws DF0020 synchronously on the offending call — surfacing the bad value next to the call site in dev:

defineRpcFunction({
  name: 'graph',
  jsonSerializable: true,
  // ⚠ throws DF0020 because Map cannot round-trip through JSON
  handler: () => ({ nodes: new Map([['a', 1]]) }),
})

For richer types, leave the flag unset (or false) — structured-clone-es preserves them on the wire and in build dumps. The flag is opt-in, so existing code keeps working untouched.

MCP requires JSON

MCP tools expose their schemas as JSON Schema, and agent harnesses assume JSON-shaped data. agent: {...} therefore requires jsonSerializable: true; registering one without the other throws DF0019. See the next section for how to attach the agent field once your function is JSON-safe.

Agent exposure

Add an agent field to surface the function to coding agents over MCP. Agent exposure is opt-in; functions without an agent field stay private. Agent-exposed functions must also declare jsonSerializable: true (see above).

defineRpcFunction({
  name: 'get-modules',
  type: 'query',
  jsonSerializable: true,
  args: [v.object({ limit: v.number() })],
  returns: v.array(v.object({ id: v.string(), size: v.number() })),
  agent: {
    description: 'List the N largest modules in the current build. Safe to call freely.',
    title: 'List modules',
    // safety inferred from type: 'query' → 'read'
  },
  setup: () => ({
    handler: async ({ limit }) => loadModules().slice(0, limit),
  }),
})

See Agent-Native for the full safety model and MCP integration.

What's next

Shared State — observable state synced across clients
Client — connecting from the browser
Agent-Native — exposing RPCs to agents

RPC ​

Overview ​

Defining a function ​

Naming convention ​

Function types ​

Handler arguments ​

Setup vs handler ​

Broadcasting ​

Streaming ​

Local invocation ​

Client-side calls ​

Type-safe client registry ​

Static dumps ​

JSON-serializable declaration ​

Discovering shape errors during dev ​

MCP requires JSON ​

Agent exposure ​

What's next ​

RPC