PopiiClientConfig

Popii / PopiiClientConfig

Interface: PopiiClientConfig<TState>

Configuration passed to popiiClient when creating the bot.

Only token is required. Everything else has sensible defaults.

Examples

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

const client = popiiClient({
  token: process.env.DISCORD_TOKEN!,
  devGuildId: process.env.DEV_GUILD_ID,
  owners: ["your_discord_user_id"],
  prefix: "!",
  status: ["Serving {{guilds}} servers", "Try /help"],
  plugins: [sqlitePlugin(), webPlugin(), errorHandlerPlugin()],
});

Type Parameters

TState

TState = any

Properties

token

token: string

Defined in: types.ts:661

Your Discord bot token. Keep this in .env — never commit it.

mode?

optional mode?: "websocket" | "http"

Defined in: types.ts:667

Connection mode.

"websocket" (default) — standard Gateway connection.
"http" — HTTP interactions endpoint for serverless deployments. Requires publicKey and port.

publicKey?

optional publicKey?: string

Defined in: types.ts:669

Required when mode is "http". Your application’s public key from the Discord Developer Portal.

port?

optional port?: number

Defined in: types.ts:671

Port for the HTTP interactions server when mode is "http". Defaults to 3000.

prefix?

optional prefix?: string | ((message) => string | string[] | Promise<string | string[] | null> | null)

Defined in: types.ts:676

Enables legacy text commands. Provide a string prefix (e.g. "!") or a function that returns the prefix(es) per message.

intents?

optional intents?: number[]

Defined in: types.ts:678

Override the auto-detected Gateway intents. Popii infers intents from your event filenames by default.

redisUrl?

optional redisUrl?: string

Defined in: types.ts:680

Redis connection URL (e.g. "redis://localhost:6379"). Enables Redis-backed storage and sharding coordination.

redis?

optional redis?: string | Record<string, unknown>

Defined in: types.ts:682

Alternative to redisUrl. Pass a connection string or an ioredis options object.

storage?

optional storage?: PopiiStorageAdapter

Defined in: types.ts:684

Provide a custom storage adapter to replace the built-in in-process Map with any backend.

partials?

optional partials?: Partials[]

Defined in: types.ts:686

Override the auto-detected Discord.js Partials. Popii infers partials from your event filenames by default.

devGuildId?

optional devGuildId?: string

Defined in: types.ts:692

A guild ID used to register slash commands during development. Guild commands sync instantly; global commands can take up to an hour. Remove or leave empty in production.

onError?

optional onError?: (error, pop) => void | Promise<void>

Defined in: types.ts:694

Called when a command or snap throws an error that is not caught by a middleware.

Parameters

error

unknown

pop

Pop

Returns

void | Promise<void>

onGlobalError?

optional onGlobalError?: (error) => void | Promise<void>

Defined in: types.ts:696

Called for unhandled promise rejections and uncaught exceptions not tied to a command.

Parameters

error

unknown

Returns

void | Promise<void>

owners?

optional owners?: string[]

Defined in: types.ts:698

Discord user IDs that have bot-owner privileges (e.g. ownerOnly: true commands).

state?

optional state?: TState

Defined in: types.ts:700

Initial value for pop.state and client.state. Persisted to Redis/storage between restarts.

commands?

optional commands?: object

Defined in: types.ts:701

dir?

optional dir?: string

folderRouting?

optional folderRouting?: boolean

Automatically maps nested folders into subcommands and subcommand groups. e.g. src/commands/config/set.ts becomes /config set.

Default

true

autoSync?

optional autoSync?: boolean

Automatically sync Slash Commands to Discord on startup. Disable this in production to prevent rate-limits, and use popii sync instead.

Default

true

help?

optional help?: boolean | { enabled?: boolean; command?: string; aliases?: string[]; }

Defined in: types.ts:721

Configure or disable the built-in /help command. Set to false to disable it entirely, or an object to customise the command name and aliases.

status?

optional status?: string | string[]

Defined in: types.ts:730

Bot status/activity string. Pass an array to rotate between multiple statuses. Supports template tokens: {{guilds}}, {{users}}, {{shardId}}.

statusInterval?

optional statusInterval?: number

Defined in: types.ts:732

Interval in ms between status rotations when status is an array. Defaults to 30000.

plugins?

optional plugins?: PopiiPlugin<TState>[]

Defined in: types.ts:734

Plugins to load. Plugins run in list order (highest priority first within that order).

pluginCommands?

optional pluginCommands?: object

Defined in: types.ts:749

Fine-grained control over commands that plugins bundle via their commands array. User commands in src/commands/ always take priority regardless of this config.

disable?

optional disable?: string[]

Command names to suppress. The command won’t be registered or synced to Discord.

overrides?

optional overrides?: Pick<PopiiCommandDefinition<any, any, PopiiLocals & Record<string, any>>, "name"> & Partial<Omit<PopiiCommandDefinition<any, any, PopiiLocals & Record<string, any>>, "name">>[]

Partial overrides merged on top of a plugin’s command definition. Useful for changing permissions, cooldowns, or descriptions without a full fork. The name field identifies which command to patch.

Example

pluginCommands: {
  // Suppress the economy daily command entirely
  disable: ['daily'],
  // Tighten permissions on the lastfm command without replacing it
  overrides: [{ name: 'lastfm', ownerOnly: true }],
}

autoDiscover?

optional autoDiscover?: boolean

Defined in: types.ts:765

When true, Popii scans node_modules for installed popii-plugin-* packages (identified by a "popii" field in their package.json) and loads them automatically. Explicitly registered plugins in plugins always take precedence.

Default

false

pluginConfig?

optional pluginConfig?: Record<string, unknown>

Defined in: types.ts:766

events?

optional events?: object

Defined in: types.ts:768

Override the directory Popii scans for event files. Defaults to "./src/events".

dir?

optional dir?: string

snaps?

optional snaps?: object

Defined in: types.ts:772

Override the directory Popii scans for snap files. Defaults to "./src/snaps".

dir?

optional dir?: string

middlewares?

optional middlewares?: object

Defined in: types.ts:776

Override the directory Popii scans for middleware files. Defaults to "./src/middlewares".

dir?

optional dir?: string

tasks?

optional tasks?: object

Defined in: types.ts:780

Override the directory Popii scans for task files. Defaults to "./src/tasks".

dir?

optional dir?: string

locales?

optional locales?: object

Defined in: types.ts:789

Localization configuration.

dir — directory containing <locale>.json files. Defaults to "./src/locales".
default — fallback locale code. Defaults to "en-US".
url — remote URL to fetch locale files from (fetched at startup).

dir?

optional dir?: string

default?

optional default?: string

url?

optional url?: string

logger?

optional logger?: PopLogger

Defined in: types.ts:795

Custom logger implementation. Defaults to the built-in Popii logger.

logLevel?

optional logLevel?: "debug" | "info" | "warn" | "error"

Defined in: types.ts:804

Minimum log level to emit. Messages below this level are silently dropped.

"debug" — everything (verbose)
"info" — info, warn, error (default)
"warn" — warn and error only
"error" — errors only

Default

"info"

fileLogging?

optional fileLogging?: boolean

Defined in: types.ts:806

Write logs to rotating files in ./logs/. Defaults to false.

structuredLogs?

optional structuredLogs?: boolean

Defined in: types.ts:808

Emit log lines as newline-delimited JSON instead of human-readable text.

presenceStrategy?

optional presenceStrategy?: "local" | "coordinated"

Defined in: types.ts:816

Controls how rotating status messages are coordinated across shards.

'local' (default): each shard rotates independently.
'coordinated': shard 0 leads rotation and broadcasts the active status to all other shards via Redis pub/sub or IPC so they all show the same string. Supports template tokens: {{shardId}}, {{guilds}}, {{users}}.

stateTtlMs?

optional stateTtlMs?: number

Defined in: types.ts:818

TTL in milliseconds for persisted bot state in Redis/storage. Defaults to 90 days.

serverSettings?

optional serverSettings?: PopiiServerSetting[]

Defined in: types.ts:819