{"id":27690,"library":"devframe","title":"devframe","description":"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.","status":"active","version":"0.1.21","language":"javascript","source_language":"en","source_url":"https://github.com/vitejs/devtools","tags":["javascript","devtools","rpc","toolbox","typescript"],"install":[{"cmd":"npm install devframe","lang":"bash","label":"npm"},{"cmd":"yarn add devframe","lang":"bash","label":"yarn"},{"cmd":"pnpm add devframe","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for MCP server adapter (devframe/adapters/mcp).","package":"@modelcontextprotocol/sdk","optional":true}],"imports":[{"note":"ESM-only package; CommonJS require is not supported.","wrong":"const { defineDevtool } = require('devframe')","symbol":"defineDevtool","correct":"import { defineDevtool } from 'devframe'"},{"note":"Direct export from main module; no subpath needed.","wrong":"import { defineRpcFunction } from 'devframe/rpc'","symbol":"defineRpcFunction","correct":"import { defineRpcFunction } from 'devframe'"},{"note":"MCP adapter is exported from a subpath, not the main entry.","wrong":"import { createMcpServer } from 'devframe'","symbol":"createMcpServer","correct":"import { createMcpServer } from 'devframe/adapters/mcp'"},{"note":"Type imports should use the 'import type' syntax in TypeScript.","wrong":"import { DevtoolDef } from 'devframe'","symbol":"defineDevtool (type)","correct":"import type { DevtoolDef } from 'devframe'"},{"note":"Must use dynamic import for CJS environments due to ESM-only nature.","wrong":"const { createMcpServer } = require('devframe/adapters/mcp')","symbol":"createMcpServer (CJS workaround)","correct":"const { createMcpServer } = await import('devframe/adapters/mcp')"}],"quickstart":{"code":"import { defineDevtool, defineRpcFunction } from 'devframe';\nimport { createServer } from 'node:http';\n\nconst getSummary = defineRpcFunction({\n  name: 'my-plugin:get-summary',\n  type: 'query',\n  agent: {\n    description: 'Return a short summary of the current build state.',\n  },\n  setup: () => ({\n    handler: async () => ({ status: 'ok', timestamp: Date.now() }),\n  }),\n});\n\nconst devtool = defineDevtool({\n  id: 'my-plugin',\n  setup(ctx) {\n    ctx.rpc.register(getSummary);\n    ctx.agent.registerResource({\n      id: 'latest-build',\n      name: 'Latest build',\n      read: () => ({ text: 'Build successful' }),\n    });\n  },\n});\n\nconst httpServer = createServer();\nhttpServer.listen(3000, () => {\n  console.log('DevFrame server listening on port 3000');\n});\n","lang":"typescript","description":"Defines a minimal devtool with an RPC function and MCP resource, then starts an HTTP server. Demonstrates core setup, RPC registration, and agent integration."},"warnings":[{"fix":"Update any hardcoded mount paths in your integrations from '/.' to '/__'.","message":"DevTools mount-path convention changed from '/.' to '/__' in v0.1.21.","severity":"breaking","affected_versions":">=0.1.21"},{"fix":"Import host modules from dedicated packages (e.g., @devframe/docks) instead of relying on devframe exports.","message":"Decoupling of docks/terminals/messages/commands from devframe core in v0.1.21 - these hosts are now separate packages.","severity":"breaking","affected_versions":">=0.1.21"},{"fix":"If you use devframe with a custom HTTPS setup, ensure your config is correctly applied to the embedded client.","message":"Respect vite https config only for embedded client in v0.1.12.","severity":"breaking","affected_versions":">=0.1.12"},{"fix":"Replace all references to ctx.logs with ctx.messages.","message":"ctx.logs renamed to ctx.messages in v0.1.17. The old ctx.logs is removed.","severity":"deprecated","affected_versions":">=0.1.17"},{"fix":"Pin your devframe version and avoid relying on undocumented agent features in production.","message":"Agent-native API (agent field, DevToolsAgentHost, MCP adapter) is experimental and may change without a major version bump.","severity":"gotcha","affected_versions":">=0.1.16"},{"fix":"Use import syntax or dynamic import with await when consuming in CommonJS environments.","message":"ESM-only package: CommonJS require() will fail.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use import syntax if your project is ESM, or use dynamic import: const { defineDevtool } = await import('devframe').","cause":"devframe is ESM-only; CommonJS require() is not allowed.","error":"ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/devframe/index.mjs from /path/to/your-file.js not supported."},{"fix":"Ensure you have installed @modelcontextprotocol/sdk and import from 'devframe/adapters/mcp' (not 'devframe').","cause":"Importing MCP adapter from wrong path or missing @modelcontextprotocol/sdk peer dependency.","error":"Cannot find module 'devframe/adapters/mcp' or its corresponding type declarations."},{"fix":"Check that you have configured the devtool with agent-native support enabled. Ensure you are using a version >=0.1.16.","cause":"Agent API is only available when using the experimental agent feature; ctx.agent may not be populated in non-agent setups.","error":"TypeError: devtool.agent.registerResource is not a function"},{"fix":"Replace ctx.logs with ctx.messages in your code.","cause":"ctx.logs was renamed to ctx.messages in v0.1.17.","error":"Logs property 'ctx.logs' is undefined in v0.1.17+"},{"fix":"Update your URL to use '/__' prefix, e.g., http://localhost:3000/__/devtools/.","cause":"Mount path convention changed from '/.' to '/__' in v0.1.21.","error":"Mount path /__/devtools/ returned 404"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}