0xmrpeter 4121840b84 docs: add plugin dev tooling guides (getting started, SDK reference, dev mode)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 21:07:56 +07:00

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:

  1. Compiles your plugin's TypeScript (if tsconfig.json exists)
  2. Starts tsc --watch in the background for continuous compilation
  3. Boots the OpenACP server with your local plugin loaded alongside all other plugins
  4. 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:

  1. Initial compile: Runs npx tsc in your plugin directory before starting the server. If compilation fails, the process exits with an error.

  2. Watch mode: Unless --no-watch is passed, starts npx tsc --watch --preserveWatchOutput in the background. Output is hidden unless --verbose is set.

  3. Auto-reload: When tsc --watch recompiles and updates files in dist/, 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:

  1. The current plugin instance's teardown() is called (if defined)
  2. The plugin module is re-imported from dist/index.js
  3. The new plugin's setup() is called with a fresh PluginContext
  4. 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.storage for 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:

  1. Check that tsc --watch is running (use --verbose to see its output)
  2. Verify that dist/index.js is being updated (check its modification time)
  3. Try stopping and restarting openacp dev
  4. If using --no-watch, rebuild manually with npm run build

Further Reading