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

183 lines
5.6 KiB
Markdown

# 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
```bash
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:**
```bash
# 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
```bash
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
```typescript
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:
```bash
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`:
```typescript
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
- [Getting Started: Your First Plugin](getting-started-plugin.md) -- end-to-end tutorial
- [Plugin SDK Reference](plugin-sdk-reference.md) -- complete API reference
- [Writing Plugins](../architecture/writing-plugins.md) -- full guide to plugin APIs