Getting Started

Popii is a convention-first Discord bot framework built for the Bun runtime. It works like a modern web framework: drop a file in the right folder, and it gets picked up automatically. No manual registration, no restarts during development.

Prerequisites

• Bun ≥ 1.1.0
• A Discord application with a bot token — create one at the Discord Developer Portal

Scaffold a new project

bunx popii init
Copy

The interactive wizard walks you through naming your bot, picking plugins, and configuring your .env. A browser window opens so you can paste your token and select intents visually.

cd my-bot
bun run dev
Copy

Your bot is now live with hot-module replacement enabled. Save any file — command, event, middleware — and changes apply immediately without a Discord disconnect.

Project structure

my-bot/
├── src/
│   ├── index.ts          # entry point — calls popiiClient()
│   ├── commands/         # one file per command (auto-registered)
│   ├── events/           # one file per Discord event (auto-registered)
│   ├── snaps/            # persistent component handlers (auto-registered)
│   ├── middlewares/      # global middleware (auto-registered, sorted alphabetically)
│   └── tasks/            # scheduled background tasks (auto-registered)
├── .env
└── package.json
Copy

Your first bot

src/index.ts

import { popiiClient } from "popii";

const client = popiiClient({
  token: process.env.DISCORD_TOKEN!,
});

client.start();
Copy

src/commands/ping.ts

import { command } from "popii";

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

That's the entire setup. Popii finds ping.ts, registers /ping as a slash command, and starts listening.

Next steps

• Commands — options, subcommands, context menus, cooldowns
• Events — listening to Discord gateway events
• Snaps — persistent button and select menu handlers
• Middleware — shared logic across all commands
• Plugins — SQLite, voice, web dashboard, AI, and more
• Testing — unit testing commands without a Discord connection