5.6 KiB
Dev Mode
Dev mode lets you load a local plugin into a running OpenACP instance with automatic hot-reload on file changes. This is the fastest way to develop and debug plugins.
What Is Dev Mode?
When you run openacp dev <path>, OpenACP:
- Compiles your plugin's TypeScript (if
tsconfig.jsonexists) - Starts
tsc --watchin the background for continuous compilation - Boots the OpenACP server with your local plugin loaded alongside all other plugins
- Watches the
dist/directory for changes and reloads your plugin automatically
Your plugin runs in the same environment as a production install -- same PluginContext, same services, same event bus. The only difference is that it is loaded from a local path instead of ~/.openacp/plugins/.
Usage
openacp dev <plugin-path> [options]
Options:
| Flag | Description |
|---|---|
--no-watch |
Disable file watching (no hot-reload, no tsc --watch) |
--verbose |
Enable verbose logging (shows tsc --watch output and debug logs) |
Examples:
# Develop a plugin in the current directory
openacp dev .
# Develop a plugin at a specific path
openacp dev ./my-plugin
# Develop without hot-reload
openacp dev ../adapter-matrix --no-watch
# Develop with verbose logging
openacp dev ./my-plugin --verbose
TypeScript Support
Dev mode automatically handles TypeScript compilation:
-
Initial compile: Runs
npx tscin your plugin directory before starting the server. If compilation fails, the process exits with an error. -
Watch mode: Unless
--no-watchis passed, startsnpx tsc --watch --preserveWatchOutputin the background. Output is hidden unless--verboseis set. -
Auto-reload: When
tsc --watchrecompiles and updates files indist/, the plugin is automatically reloaded.
If your plugin is plain JavaScript (no tsconfig.json), the TypeScript steps are skipped and the plugin is loaded directly.
Hot-Reload Behavior
What happens on file change
When a file in your plugin's dist/ directory changes:
- The current plugin instance's
teardown()is called (if defined) - The plugin module is re-imported from
dist/index.js - The new plugin's
setup()is called with a freshPluginContext - Services, commands, middleware, and event listeners are re-registered
How ESM cache busting works
Node.js caches ESM modules by URL. To force a fresh import on reload, the dev loader copies dist/index.js to a temporary file with a unique name, imports from there, then cleans up the temp file. This ensures you always get the latest code.
Limitations
- Entry file only: The watcher monitors
dist/index.js. If your plugin imports other local modules, those modules are also refreshed as part of the re-import, but changes to deeply nested dependencies may require a manual restart. - State loss: On reload, all in-memory state from the previous plugin instance is lost. Use
ctx.storagefor data that should survive reloads. - Side effects: If your plugin creates external resources (database connections, webhooks), make sure
teardown()cleans them up to avoid leaks on reload.
Debugging Tips
Enable verbose logging
openacp dev ./my-plugin --verbose
This shows:
- TypeScript compiler output (errors and warnings)
- Plugin load/unload events
- All debug-level log messages from your plugin
Use ctx.log for plugin logging
async setup(ctx: PluginContext) {
ctx.log.info('Plugin loaded')
ctx.log.debug('Config:', ctx.pluginConfig)
ctx.log.warn('Something might be wrong')
ctx.log.error('Something went wrong', error)
}
In dev mode with --verbose, all log levels are visible.
Check the OpenACP logs
If the server logs to a file (configured via logging.logDir), tail those logs in another terminal:
openacp logs
Troubleshooting
TypeScript compilation fails
TypeScript compilation failed. Fix errors and try again.
Fix the TypeScript errors in your source code and run openacp dev again. The initial compile must succeed before the server starts.
Plugin not found
Error: plugin path does not exist: /path/to/plugin
Make sure the path exists and is a directory containing either dist/index.js (compiled) or src/index.ts (source).
Built plugin not found
Error: Built plugin not found at /path/to/plugin/dist/index.js. Run 'npm run build' first.
Your plugin has source files but no compiled output. Run npm run build in the plugin directory first, or let openacp dev handle it (it compiles automatically if tsconfig.json exists).
Invalid plugin
Error: Invalid plugin at dist/index.js. Must export default OpenACPPlugin with name and setup().
Your plugin must have a default export that includes at least name (string) and setup (function). Check your src/index.ts:
const plugin: OpenACPPlugin = {
name: '@myorg/my-plugin', // required
version: '0.1.0',
setup(ctx) { ... }, // required
}
export default plugin // must be default export
Changes not taking effect
If hot-reload does not pick up your changes:
- Check that
tsc --watchis running (use--verboseto see its output) - Verify that
dist/index.jsis being updated (check its modification time) - Try stopping and restarting
openacp dev - If using
--no-watch, rebuild manually withnpm run build
Further Reading
- Getting Started: Your First Plugin -- end-to-end tutorial
- Plugin SDK Reference -- complete API reference
- Writing Plugins -- full guide to plugin APIs