PopiiPlugin

Popii / PopiiPlugin

Interface: PopiiPlugin<TState>

The interface all Popii plugins must implement.

A plugin is a plain object returned from a factory function. It hooks into the client lifecycle via setup, ready, reload, and cleanup, and can also intercept every command execution via onCommandExecute and onCommandError.

Example

import type { PopiiPlugin } from "popii";

export function myPlugin(): PopiiPlugin {
  return {
    name: "my-plugin",
    setup(client) {
      // runs once at startup — register listeners, create DB tables, etc.
    },
    ready(client) {
      // runs after Discord connects — safe to use client.discord.guilds.cache
    },
    cleanup(client) {
      // runs on graceful shutdown — clear intervals, close connections
    }
  };
}

Type Parameters

TState

TState = any

Methods

setup()?

optional setup(client): void | Promise<void>

Defined in: types.ts:610

Runs once at startup, before connecting to Discord. Register event listeners, create DB tables, and perform one-time initialisation here. Optional when the plugin only provides commands or settingsSchema.

Parameters

client

PopiiClient<TState>

Returns

void | Promise<void>

ready()?

optional ready(client): void | Promise<void>

Defined in: types.ts:612

Runs after the bot successfully connects to Discord. Safe to access guild and user caches.

Parameters

client

PopiiClient<TState>

Returns

void | Promise<void>

reload()?

optional reload(client): void | Promise<void>

Defined in: types.ts:614

Runs after a hot-reload. Re-wrap commands with middleware or refresh state here.

Parameters

client

PopiiClient<TState>

Returns

void | Promise<void>

cleanup()?

optional cleanup(client): void | Promise<void>

Defined in: types.ts:616

Runs on graceful shutdown. Clear intervals and close external connections here.

Parameters

client

PopiiClient<TState>

Returns

void | Promise<void>

onCommandExecute()?

optional onCommandExecute(pop, command): void | Promise<void>

Defined in: types.ts:618

Called before every command or snap executes. Useful for analytics and tracing.

Parameters

pop

Pop<TState>

command

PopiiCommandDefinition<TState, any, PopiiLocals & Record<string, any>> | PopiiComponentDefinition<TState, any, PopiiLocals & Record<string, any>>

Returns

void | Promise<void>

onCommandError()?

optional onCommandError(error, pop): void | Promise<void>

Defined in: types.ts:620

Called when a command or snap throws an unhandled error.

Parameters

error

unknown

pop

Pop<TState>

Returns

void | Promise<void>

onContextCreate()?

optional onContextCreate(pop): void

Defined in: types.ts:622

Called when a new pop context is created. Inject data into the context here.

Parameters

pop

EventPop<TState>

Returns

void

health()?

optional health(): { ok: boolean; message?: string; } | Promise<{ ok: boolean; message?: string; }>

Defined in: types.ts:627

Optional health check. Called by /health and popii doctor at runtime. Return { ok: false, message: "why" } to signal degraded state.

Returns

{ ok: boolean; message?: string; } | Promise<{ ok: boolean; message?: string; }>

onConfigChange()?

optional onConfigChange(newOptions): boolean | void | Promise<boolean | void>

Defined in: types.ts:632

Called when the bot owner updates plugin options at runtime via the dashboard. Receives the new merged options object. Return false to reject the change.

Parameters

newOptions

Record<string, any>

Returns

boolean | void | Promise<boolean | void>

Properties

name

name: string

Defined in: types.ts:535

manifest?

optional manifest?: PluginManifest

Defined in: types.ts:537

Popii 1.0 lifecycle and security metadata. Added automatically to legacy built-ins.

configSchema?

optional configSchema?: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

Defined in: types.ts:539

Configuration boundary used by the 1.0 plugin runtime.

dashboard?

optional dashboard?: DashboardContribution | DashboardContributionV2

Defined in: types.ts:541

Safe, typed pages and actions contributed to the Cakemix dashboard.

version?

optional version?: string

Defined in: types.ts:546

The semantic version of this plugin (e.g. "1.2.0"). Used by other plugins to declare version-range requirements in requires.

requires?

optional requires?: string[]

Defined in: types.ts:553

Plugin names that must be loaded before this plugin. Append @<range> to enforce a semver constraint on the required plugin’s version (e.g. "popii-sqlite@>=2.0.0", "popii-sqlite@^1.0.0"). Popii throws at startup if any listed plugin is missing or out of range.

requiresOneOf?

optional requiresOneOf?: string[][]

Defined in: types.ts:562

Each inner array is an OR group — at least one name from each group must be loaded. Use this when a plugin can work with any one of several alternatives (e.g. SQLite or Mongoose). Popii throws at startup if no plugin from an inner array is present.

Example

requiresOneOf: [["popii-sqlite", "popii-mongoose"]]

conflicts?

optional conflicts?: string[]

Defined in: types.ts:567

Plugin names this plugin cannot coexist with. Popii throws at startup if any listed plugin is also present.

priority?

optional priority?: number

Defined in: types.ts:572

Execution order during the setup lifecycle. Higher values run first.

Default

settingsSchema?

optional settingsSchema?: PopiiServerSetting[]

Defined in: types.ts:577

Declarative per-guild settings exposed in the web dashboard’s server settings form. The category defaults to the plugin name if omitted.

intents?

optional intents?: number[]

Defined in: types.ts:583

Gateway intents this plugin requires. Popii ORs these into the auto-detected intent set so you never need to manually configure intents for built-in plugins. Use GatewayIntentBits values (numbers).

partials?

optional partials?: Partials[]

Defined in: types.ts:587

Discord.js Partials this plugin requires. Merged into the auto-detected partials set.

commands?

optional commands?: PopiiCommandDefinition<TState, any, PopiiLocals & Record<string, any>>[]

Defined in: types.ts:604

Commands bundled with this plugin. Registered automatically on startup and after every hot-reload. Commands in the user’s src/commands/ directory with the same name always take priority, giving users a clean override path without touching the plugin source.

Use pluginCommands.disable in your bot config to suppress individual commands, or pluginCommands.overrides to patch them without a full replacement.

Example

import { command } from 'popii-framework';
commands: [
  command({ name: 'ping', description: 'Ping the bot', do: (pop) => pop.reply('Pong!') })
]