devframe

library0.1.21jsnpmunverified

A framework-neutral foundation for building generic DevTools, part of the Vite DevTools monorepo (MIT). Current stable version is 0.1.21, with weekly releases featuring breaking changes and new capabilities. Provides an RPC layer based on birpc + valibot + WebSocket presets, plus six built-in hosts: RPC, docks, views, terminals, logs, commands, and an agent interface for MCP integration. Includes adapters for CLI, build, SPA, Vite, Kit, embedded, and MCP. Key differentiators: designed specifically for developer tooling, first-class MCP support for AI agents, and a modular architecture that decouples UI from logic since v0.1.21. Ships TypeScript types. Requires @modelcontextprotocol/sdk as a peer dependency for MCP features.

web-framework http-networking devops llm-agents

npm install devframe

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DEVFRAME

devframe

web-frameworkjavascriptv0.1.21

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineDevtool

✓ import { defineDevtool } from 'devframe'

✗ const { defineDevtool } = require('devframe')

ESM-only package; CommonJS require is not supported.

defineRpcFunction

✓ import { defineRpcFunction } from 'devframe'

✗ import { defineRpcFunction } from 'devframe/rpc'

Direct export from main module; no subpath needed.

createMcpServer

✓ import { createMcpServer } from 'devframe/adapters/mcp'

✗ import { createMcpServer } from 'devframe'

MCP adapter is exported from a subpath, not the main entry.

defineDevtool (type)

✓ import type { DevtoolDef } from 'devframe'

✗ import { DevtoolDef } from 'devframe'

Type imports should use the 'import type' syntax in TypeScript.

createMcpServer (CJS workaround)

✓ const { createMcpServer } = await import('devframe/adapters/mcp')

✗ const { createMcpServer } = require('devframe/adapters/mcp')

Must use dynamic import for CJS environments due to ESM-only nature.

Defines a minimal devtool with an RPC function and MCP resource, then starts an HTTP server. Demonstrates core setup, RPC registration, and agent integration.

import { defineDevtool, defineRpcFunction } from 'devframe'; import { createServer } from 'node:http'; const getSummary = defineRpcFunction({ name: 'my-plugin:get-summary', type: 'query', agent: { description: 'Return a short summary of the current build state.', }, setup: () => ({ handler: async () => ({ status: 'ok', timestamp: Date.now() }), }), }); const devtool = defineDevtool({ id: 'my-plugin', setup(ctx) { ctx.rpc.register(getSummary); ctx.agent.registerResource({ id: 'latest-build', name: 'Latest build', read: () => ({ text: 'Build successful' }), }); }, }); const httpServer = createServer(); httpServer.listen(3000, () => { console.log('DevFrame server listening on port 3000'); });

Debug

Known issues

breakingDevTools mount-path convention changed from '/.' to '/__' in v0.1.21.

fix

Update any hardcoded mount paths in your integrations from '/.' to '/__'.

affects: >=0.1.21

breakingDecoupling of docks/terminals/messages/commands from devframe core in v0.1.21 - these hosts are now separate packages.

fix

Import host modules from dedicated packages (e.g., @devframe/docks) instead of relying on devframe exports.

affects: >=0.1.21

breakingRespect vite https config only for embedded client in v0.1.12.

fix

If you use devframe with a custom HTTPS setup, ensure your config is correctly applied to the embedded client.

affects: >=0.1.12

deprecatedctx.logs renamed to ctx.messages in v0.1.17. The old ctx.logs is removed.

fix

Replace all references to ctx.logs with ctx.messages.

affects: >=0.1.17

gotchaAgent-native API (agent field, DevToolsAgentHost, MCP adapter) is experimental and may change without a major version bump.

fix

Pin your devframe version and avoid relying on undocumented agent features in production.

affects: >=0.1.16

gotchaESM-only package: CommonJS require() will fail.

fix

Use import syntax or dynamic import with await when consuming in CommonJS environments.

affects: >=0.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/devframe/index.mjs from /path/to/your-file.js not supported.

devframe is ESM-only; CommonJS require() is not allowed.

fix

Use import syntax if your project is ESM, or use dynamic import: const { defineDevtool } = await import('devframe').

Cannot find module 'devframe/adapters/mcp' or its corresponding type declarations.

Importing MCP adapter from wrong path or missing @modelcontextprotocol/sdk peer dependency.

fix

Ensure you have installed @modelcontextprotocol/sdk and import from 'devframe/adapters/mcp' (not 'devframe').

TypeError: devtool.agent.registerResource is not a function

Agent API is only available when using the experimental agent feature; ctx.agent may not be populated in non-agent setups.

fix

Check that you have configured the devtool with agent-native support enabled. Ensure you are using a version >=0.1.16.

Logs property 'ctx.logs' is undefined in v0.1.17+

ctx.logs was renamed to ctx.messages in v0.1.17.

fix

Replace ctx.logs with ctx.messages in your code.

Mount path /__/devtools/ returned 404

Mount path convention changed from '/.' to '/__' in v0.1.21.

fix

Update your URL to use '/__' prefix, e.g., http://localhost:3000/__/devtools/.

Upgrade

Version history

0.1.21latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkoptionalPeer dependency required for MCP server adapter (devframe/adapters/mcp).

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/devframes/devframe ↗

packagehttps://www.npmjs.com/package/devframe ↗

homepagehttps://devtools.devframe.dev ↗