---

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