Plugin developer guide

ItsMyBot plugins are TypeScript packages that run inside the ItsMyBot runtime. A plugin can add slash commands, react to Discord events, expose typed server configuration, persist small amounts of data, and publish a marketplace presentation.

These docs are only for developers creating plugins.

Author lifecycle

1. Create a plugin project that depends on itsmybot.
2. Keep src/index.ts as the bundler entrypoint.
3. Split metadata, config, commands, and events into focused files.
4. Run itsmybot bundle . to generate .itsmybot/manifest.json and .itsmybot/runtime.js.
5. Run itsmybot publish . to upload the build.
6. Install the beta build in a test guild, then request stable review.

Install SDK

Use your package manager inside the plugin project:

pnpm add itsmybot

With npm:

npm install itsmybot

Add local scripts so bundle and publish commands are repeatable:

{
  "scripts": {
    "bundle": "itsmybot bundle .",
    "publish": "itsmybot publish ."
  },
  "dependencies": {
    "itsmybot": "latest"
  }
}

What a plugin exports

The bundler starts at src/index.ts. That file should export:

• defaultConfig, when the plugin has server configuration.
• a default plugin instance.

The plugin instance declares metadata, capabilities, commands, events, and optional storage:

import {
  Plugin,
  PluginCapability,
  PluginCategory,
} from "itsmybot";

interface Config extends Record<string, unknown> {
  greeting: string;
}

class WelcomePlugin extends Plugin<Config> {
  readonly id = "welcome-helper";
  readonly version = "0.1.0";
  readonly name = "Welcome Helper";
  readonly summary = "Send configurable welcome messages.";
  readonly category = PluginCategory.Engagements;
  readonly compatibilityDate = "2026-04-20";
  readonly capabilities = [PluginCapability.DiscordInteractionReply] as const;
}

export default new WelcomePlugin();

Start here

• Project structure: choose files and ownership before the plugin grows.
• First plugin: build a typed command plugin end to end.
• Commands and events: add slash commands and Discord event handlers.
• Configuration: expose dashboard fields with JSDoc.
• Runtime rules: understand sandbox limits, actions, KV, and storage.
• Bundle and publish: generate artifacts and ship a beta.

Rules to keep in mind

• Plugin metadata lives in code; generated .itsmybot/* files are build output.
• README.md is the long marketplace presentation. summary stays short.
• Declare every Discord write capability your plugin needs.
• Do not use Node-only APIs such as fs or child_process in runtime code.
• Server validation runs again on publish; SDK validation is convenience, not source of truth.