Skip to main content

Packaging and Publishing Plugins

When your plugin is ready to share, follow this checklist and publish it to the CodeBolt registry.

Pre-publish Checklist​

  • package.json includes a valid codebolt.plugin block
  • main field points to the compiled entry file (dist/index.js)
  • Plugin builds successfully (npm run build)
  • Plugin starts cleanly and handles onStart() without crashing
  • onStop() performs proper cleanup (unregister providers, close connections)
  • Required credentials or environment setup is documented
  • If using UI panels, the HTML file exists at the declared ui.path

By plugin type​

LLM Provider plugins:

  • Document providerId and supported models
  • Document config fields users need to fill in (API key, base URL, etc.)
  • Handle both onCompletionRequest and onStreamRequest

Chat gateway plugins ("type": "channel"):

  • Document the external platform setup (bot tokens, webhook URLs)
  • Use kvStore for configuration persistence (not filesystem)
  • Provide a UI panel for connection configuration
  • Document supported thread strategies

Execution plugins:

  • Document what types of requests are intercepted
  • Document the response shape returned via sendReply
  • Explain the remote environment setup

Local Development Loop​

  1. Build — npm run build
  2. Install to a plugin directory: 
    # Per-project (for testing)
    cp -r my-plugin/ <project>/.codeboltPlugins/my-plugin/

    # Or global
    cp -r my-plugin/ ~/.codebolt/plugins/my-plugin/
  3. Reload in Plugins panel (click Reload), then Start
  4. Iterate — run npx tsc --watch, stop/restart from Plugins panel after each rebuild

Publish​

codebolt plugin publish --path ./my-plugin

List published plugins:

codebolt plugin list

Common Mistakes​

MistakeFix
Missing codebolt.plugin in package.jsonServer won't recognize as a plugin
Forgetting to build dist/index.jsAlways npm run build before loading
Storing config in filesystemUse plugin.kvStore for persistence
Not handling onStop() cleanupLeads to dangling connections, leaked subscriptions
Using startup trigger for chat gateway plugins that need configUse manual — auto-load saved config in onStart
Using @codebolt/client-sdk instead of @codebolt/plugin-sdkClient SDK is for standalone UIs, plugin SDK is for server extensions

See Also​