Getting Started

Popii is a convention-first Discord bot framework for Bun. The core idea is simple: the file structure is the configuration. Drop a file in the right folder and Popii picks it up — no registration calls, no restart needed.

Prerequisites

Bun ≥ 1.1.0 — install Bun
A Discord bot token — create an application at the Discord Developer Portal

Scaffold a project

Run the init wizard
Terminal window
```
bunx popii init
```
The interactive CLI walks you through naming your bot and picking which plugins to include. At the end it opens a browser window so you can paste your token and choose gateway intents visually — no manual .env editing required.
Start the dev server
Terminal window
```
cd my-bot
bun run dev
```
Your bot connects to Discord immediately. From here, every file save triggers a hot-reload: commands re-register, events re-bind, middleware re-wraps — all without dropping the WebSocket connection.

Project layout

Directorymy-bot/
- Directorysrc/
  - index.ts (entry point — calls popiiClient)
  - Directorycommands/ (one file = one slash command)
    …
  - Directoryevents/ (one file = one Discord event handler)
    …
  - Directorysnaps/ (persistent button/select/modal handlers)
    …
  - Directorymiddlewares/ (global pipeline — loaded alphabetically)
    …
  - Directorytasks/ (scheduled background jobs)
    …
  - Directorylocales/ (optional i18n JSON files)
    …
- .env
- package.json

Every folder is optional. Popii only loads what exists.

Your first command

src/index.ts

import { popiiClient } from "popii-framework";

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

client.start();

src/commands/ping.ts

import { command } from "popii-framework";

export default command({
  name: "ping",
  description: "Check the bot's latency",
  async do(pop) {
    await pop.reply(`Pong! ${pop.client.discord.ws.ping}ms`);
  },
});

That’s the entire setup. Popii finds ping.ts, registers /ping as a slash command, and starts listening. No client.commands.set(), no manifest file.

During development, slash commands sync to a devGuildId if you set one — instant updates. Without it, global sync takes up to an hour.

popiiClient({
  token: process.env.DISCORD_TOKEN!,
  devGuildId: process.env.DEV_GUILD_ID,
});

What’s next

Commands

Options, subcommands, cooldowns, context menus, and text commands. Read more →

Events

React to Discord gateway events with automatic intent detection. Read more →

Snaps

Persistent handlers for buttons, select menus, and modals that survive restarts. Read more →

Plugins

SQLite, voice, web dashboard, economy, AI, and 20+ more — all zero-config. Read more →