Devtool Definition

Every Devframe tool starts with a single defineDevtool call. The returned DevtoolDefinition is a portable value that any of the adapters can consume — the same definition runs under createCli, createBuild, createMcpServer, kit's createPluginFromDevframe, and so on.

Minimal definition

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

export default defineDevtool({
  id: 'my-devtool',
  name: 'My Devtool',
  icon: 'ph:gauge-duotone',
  setup(ctx) {
    // Register your RPC functions, shared state, etc. here.
    ctx.rpc.register(defineRpcFunction({
      name: 'my-devtool:hello',
      type: 'static',
      jsonSerializable: true,
      handler: () => ({ message: 'hello' }),
    }))
  },
})

When mounted into Vite DevTools via createPluginFromDevframe, the dock entry and iframe mount are derived from id, name, icon, and basePath automatically. Hub-level features (docks, terminals, messages, commands) live on the kit-augmented context.

Definition fields

Field	Type	Description
`id`	`string`	Required. Unique, namespaced identifier (kebab-case). Used as a prefix for RPC names, dock IDs, and MCP tool names.
`name`	`string`	Required. Display name shown in the dock and agent manifests.
`icon`	`string \| { light, dark }`	Optional Iconify name or URL; supports light/dark pairs.
`version`	`string`	Optional version string surfaced to clients.
`basePath`	`string`	Optional mount path override. Defaults depend on the adapter: `/` for standalone (`cli` / `spa` / `build`), `/.<id>/` for hosted (`vite` / `kit` / `embedded`).
`capabilities`	`{ dev?, build?, spa? }`	Per-runtime feature flags. A `boolean` applies to the runtime as a whole; an object enables individual features.
`setup`	`(ctx, info?) => void \| Promise<void>`	Required. Server-side entry point. Runs in every runtime. The optional second argument carries runtime metadata — most notably the parsed CLI `flags` when running under `createCli`.
`setupBrowser`	`(ctx) => void \| Promise<void>`	Browser-only entry used by the SPA adapter.
`cli`	`DevtoolCliOptions`	Defaults for the CLI adapter. See CLI options below.
`spa`	`DevtoolSpaOptions`	Defaults for the SPA adapter (`base`, `loader`).

Runtime flags

The ctx.mode field is either 'dev' or 'build'. Use it to gate work that should only run in one runtime:

defineDevtool({
  id: 'my-devtool',
  name: 'My Devtool',
  setup(ctx) {
    if (ctx.mode === 'build') {
      // Static-only work — baked into the RPC dump.
    }
    else {
      // Dev-mode wiring, file watchers, etc.
    }
  },
})

The CLI dev server sets mode: 'dev'; createBuild sets mode: 'build'.

The setup context

setup(ctx) receives a DevToolsNodeContext:

interface DevToolsNodeContext {
  readonly cwd: string
  readonly workspaceRoot: string
  readonly mode: 'dev' | 'build'

  host: DevToolsHost // runtime abstraction (mountStatic / resolveOrigin / getStorageDir)
  rpc: RpcFunctionsHost // register + broadcast + sharedState
  views: DevToolsViewHost // static file hosting (`hostStatic`)
  diagnostics: DevToolsDiagnosticsHost
  agent: DevToolsAgentHost // experimental

  createJsonRenderer: (spec) => JsonRenderer
}

Hub-level subsystems — docks, terminals, messages, commands — live on the kit-augmented context owned by @vitejs/devtools-kit. A devframe app that wants to register kit-only behavior does so through the optional setup hook on createPluginFromDevframe.

Each host has a dedicated page:

RPC — ctx.rpc
Shared State — ctx.rpc.sharedState
Diagnostics — ctx.diagnostics
Agent-Native — ctx.agent
Hub-side surfaces — Dock System, Commands, Messages, Terminals — live in the Vite DevTools Kit docs.

Browser setup

The SPA adapter supports a setupBrowser(ctx) hook that runs inside the deployed client bundle. Use it for tools that perform their own in-browser work — parsing a dropped file, calling public APIs from the client, etc.

defineDevtool({
  id: 'my-devtool',
  name: 'My Devtool',
  setup(ctx) { /* server-side */ },
  setupBrowser(ctx) {
    // `ctx.rpc` is the write-disabled static client in SPA mode.
  },
})

Deployed SPAs that use setupBrowser ship their own client entry that registers the handlers.

CLI options

cli configures the CLI adapter's defaults and plugs additional flags/commands into the CAC instance:

defineDevtool({
  id: 'my-devtool',
  name: 'My Devtool',
  cli: {
    command: 'my-devtool', // binary name; default: the `id`
    distDir: './client/dist', // required for dev / build / spa
    port: 9876, // preferred port; default: 9999
    portRange: [9876, 10000], // forwarded to get-port-please
    random: false, // forwarded to get-port-please
    host: 'localhost', // default host; --host overrides
    open: true, // auto-open the browser on dev start
    auth: false, // skip the trust handshake (single-user localhost)
    configure(cli) { // contribute capability flags/commands
      cli
        .option('--my-flag <value>', 'Tool-specific flag')
    },
  },
  setup(ctx, { flags }) {
    // `flags` carries the parsed cac bag — contains built-in flags
    // (`--port`, `--host`, `--open`, `--no-open`) and anything you added
    // in `configure`.
  },
})

Field	Type	Description
`command`	`string`	Binary name surfaced in `--help`. Default: the definition's `id`.
`distDir`	`string`	SPA dist directory. Required for `dev` / `build` / `spa`.
`port`	`number`	Preferred port for the dev server.
`portRange`	`[number, number]`	Port scan range, passed through to `get-port-please`.
`random`	`boolean`	Prefer a random open port.
`host`	`string`	Default bind host.
`open`	`boolean \| string`	`true` opens the origin, a string opens a specific path, `false` disables. Matches the `--open` / `--no-open` flags.
`auth`	`boolean`	Disable the WS trust flow when the tool is localhost-only and single-user. Default `true`.
`configure`	`(cli: CAC) => void`	Contribute capability flags/commands. Runs before `createCli`'s `configureCli` option so the final tool author always has the last word.

setup(ctx, info) receives info.flags populated from both devframe's built-in flags and any you declared via configure — saves duplicating flag parsing.

SPA options

defineDevtool({
  id: 'my-devtool',
  spa: {
    base: '/',
    loader: 'query', // 'query' | 'upload' | 'none'
  },
})

See Adapters for how each adapter consumes these.

Multiple runtimes, one definition

The definition is a plain value, so wire it into multiple adapters from the same file:

import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { createBuild } from 'devframe/adapters/build'
import { createCli } from 'devframe/adapters/cli'

const devtool = defineDevtool({ id: 'my-devtool', name: 'My Devtool', setup() {} })

// 1. Standalone CLI:
await createCli(devtool).parse()

// 2. Embedded in a Vite project (from `vite.config.ts`):
export const myPlugin = () => createPluginFromDevframe(devtool)

// 3. Offline snapshot:
await createBuild(devtool, { outDir: 'dist-static' })

What's next

Adapters — pick a deployment target
RPC — register server functions
Vite DevTools Kit — mount your devtool into the multi-integration hub

Devtool Definition ​

Minimal definition ​

Definition fields ​

Runtime flags ​

The setup context ​

Browser setup ​

CLI options ​

SPA options ​

Multiple runtimes, one definition ​

What's next ​