popii-framework

library0.7.6jsnpmunverified

A convention-first Discord bot framework built exclusively for the Bun runtime (>=1.1.0). Current stable version is 0.7.6 with active development and frequent releases. Key differentiators: folder-based routing where file paths become slash commands (no manual registration), hot-module replacement during development, a plugin marketplace, and built-in plugins for SQLite, voice, AI, economy, and web dashboard. Requires discord.js ^14.0.0, ioredis ^5.0.0, and optional voice dependencies. Full TypeScript support with augmentable context types. Designed as all-in-one alternative to frameworks like Sapphire or discordx, with a focus on zero-boilerplate developer experience.

messaging

npm install popii-framework

package ↗homepage ↗

INSTALL

IMPORT

SIG · POPII-FRAMEWORK

popii-framework

messagingjavascriptv0.7.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import Popii from 'popii-framework'

✗ const Popii = require('popii-framework')

ESM-only; require() will fail. Use default import for the main client class.

command

✓ import { command } from 'popii-framework'

✗ import command from 'popii-framework/command'

command is a named export from the main package, not a subpath. Export available since v0.5.

event

✓ import { event } from 'popii-framework'

✗ import { event } from 'popii-framework/events'

Named export from 'popii-framework', not a subpath. Used for event listeners.

slash

✓ import { slash } from 'popii-framework'

✗ import { SlashCommandBuilder } from 'discord.js' and manually register

Popii handles slash command registration automatically via file routing. Prefer 'command' with 'slash: true'.

Context

✓ import type { Context } from 'popii-framework'

Type import for the pop context object. Available since v0.6.

Shows basic setup with Popii client, a ping command using file-based routing, and a ready event listener.

import Popii from 'popii-framework'; import { command, event } from 'popii-framework'; const client = new Popii({ token: process.env.DISCORD_TOKEN ?? '', intents: ['Guilds', 'GuildMessages', 'MessageContent'], }); // Command automatically loaded from src/commands/ping.ts // This file would contain: export default command({ name: 'ping', description: 'Replies with pong!', slash: true, async do(pop) { await pop.reply(`Pong! ${pop.client.discord.ws.ping}ms`); }, }); // Event example event('ready', (pop) => { console.log(`Logged in as ${pop.client.discord.user?.tag}`); }); client.login();

Debug

Known issues

breakingBun runtime is required: 'Error: This module can only be run with Bun'

fix

Install Bun (https://bun.sh) and use 'bun run' instead of 'node'.

affects: >=0.1.0

breakingNode.js is not supported: 'require is not defined' or ESM errors

fix

Popii is designed exclusively for Bun; do not attempt to run with Node.js or other runtimes.

affects: >=0.5.0

gotchaDefault export is the Popii client class, not a factory function

fix

Use 'new Popii(options)' after default import, not 'Popii(options)'.

affects: >=0.1.0

deprecated'PopiiShardingManager' import path changed in v0.7: previously exported from 'popii-framework/sharding'

fix

Import from 'popii-framework' directly: import { PopiiShardingManager } from 'popii-framework'.

affects: >=0.7.0

gotchaPlugin marketplace commands ('popii add') require network access to the Popii registry

fix

Ensure the machine can reach 'https://api.popii.dev' during installation.

affects: >=0.6.0

Errors

Common errors & fixes

error: Cannot find module 'popii-framework'

Missing dependency or running with Node.js instead of Bun

fix

Run 'bun add popii-framework discord.js ioredis' and use 'bun run' to start.

TypeError: Class extends value undefined is not a constructor or null

CommonJS require() used instead of ESM import, or missing peer dependency

fix

Use ESM import syntax and ensure all peer dependencies (discord.js, ioredis) are installed.

Error: DISCORD_TOKEN is required

Missing environment variable for the bot token

fix

Set DISCORD_TOKEN in .env file or environment, or pass token in Popii constructor options.

Upgrade

Version history

0.7.6latest on npm

Audit

Dependencies

discord.jsrequiredCore Discord API library

ioredisrequiredRequired for sharding and caching

@discordjs/voiceoptionalRequired for voice plugin

libsodium-wrappersoptionalRequired for voice encryption

Agent activity

22 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagepopii-framework ↗

homepagehttps://docs.loveyourmaid.moe ↗