Popii lets you build Discord bots the way modern web frameworks handle routing — drop a file, get a command. No boilerplate, no manual registration, no restarts during development.

// src/commands/ping.ts
import { command } from "popii-framework";

export default command({
  name: "ping",
  description: "Replies with pong!",
  slash: true,
  async do(pop) {
    await pop.reply(`Pong! ${pop.client.discord.ws.ping}ms`);
  }
});

That's it. Popii finds the file, registers the slash command, and hot-reloads it on save.

Features

• Folder-based routing — src/commands/config/set.ts becomes /config set automatically
• Hot-module replacement — edit commands, events, and middleware without disconnecting from Discord
• Plugin system — extend the pop context with new methods and properties
• Plugin marketplace — install community plugins with popii add <name>
• Built-in plugins — SQLite, voice, AI, economy, web dashboard, and more out of the box
• Middleware — Express-style middleware pipeline for commands and events
• Sharding — first-class multi-shard support via PopiiShardingManager
• Type-safe — full TypeScript support with augmentable context types

Getting Started

bunx popii init

The setup wizard scaffolds a new project with your chosen plugins, folder structure, and .env in seconds. Open your browser, pick your plugins, paste your token, done.

cd my-bot
bun run dev

Your bot is live with HMR enabled. Save any file and changes apply instantly.

CLI Reference

| Command | Description | |---------|-------------| | popii init | Scaffold a new bot project | | popii dev | Start the dev server with HMR | | popii sync | Manually sync slash commands to Discord | | popii add <name> | Install a plugin from the marketplace | | popii remove <name> | Uninstall a plugin | | popii search <query> | Search the plugin marketplace | | popii list | List installed plugins | | popii g <type> <name> | Generate a command, event, snap, middleware, task, or test | | popii doctor | Check your environment for common issues | | popii deploy | Generate deployment config for Railway, Fly.io, or VPS | | popii migrate <create\|up> | Run SQLite migrations | | popii console | Start an interactive REPL with the bot in scope | | popii dashboard | Print web dashboard setup instructions |

Built-in Plugins

| Plugin | Description | |--------|-------------| | sqlitePlugin | Bun SQLite database injected into every pop context | | mongoosePlugin | MongoDB via Mongoose ODM | | voicePlugin | Voice channel playback with queue, SponsorBlock, and now-playing cards | | webPlugin | HTTP server with health checks, metrics, and an optional web dashboard | | deskPlugin | Full support ticket system | | popiiAiPlugin | AI assistant via OpenAI, Gemini, or Anthropic | | economyPlugin | Virtual currency, inventory, and shop system | | uiPlugin | Pagination, forms, and interactive prompts | | payPlugin | Payment processing | | autoModPlugin | Automated moderation | | giveawayPlugin | Giveaway system | | canvasPlugin | Image generation and now-playing cards | | lastFmPlugin | Last.fm scrobbling and now-playing integration | | captchaPlugin | Verification captchas | | activityRotatorPlugin | Rotating bot status messages | | telemetryPlugin | Performance monitoring | | commandLoggerPlugin | Command execution logging | | commandAnalyticPlugin | Usage analytics | | permissionGuardPlugin | Automatic permission enforcement | | errorHandlerPlugin | Graceful error handling | | reloadPlugin | Adds a /reload slash command |

Plugin Marketplace

Install community plugins directly from the CLI:

bunx popii add economy        # installs popii-plugin-economy
bunx popii search music       # search the registry
bunx popii list               # show installed plugins

Plugins are discovered automatically on startup when autoDiscover: true is set:

const client = popiiClient({
  token: process.env.DISCORD_TOKEN!,
  autoDiscover: true,
  pluginConfig: {
    "popii-plugin-economy": { currencySymbol: "🪙" }
  }
});

Want to build a plugin? Use the plugin template to get started.

Requirements

• Bun ≥ 1.1.0
• discord.js ^14.0.0 (peer dependency, installed automatically by popii init)

Optional peer dependencies installed as needed:

• ioredis — for Redis-backed storage and multi-shard coordination
• @discordjs/voice + libsodium-wrappers — for the voice plugin

License

MIT