Popii - v0.5.1
    Preparing search index...

    Interface PopiiClientConfig<TState>

    Configuration passed to popiiClient when creating the bot.

    Only token is required. Everything else has sensible defaults.

    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()],
    });
    interface PopiiClientConfig<TState = any> {
        token: string;
        mode?: "websocket" | "http";
        publicKey?: string;
        port?: number;
        prefix?:
            | string
            | (
                (
                    message: Message,
                ) => string | string[] | Promise<string | string[] | null> | null
            );
        intents?: number[];
        redisUrl?: string;
        redis?: string | Record<string, unknown>;
        storage?: PopiiStorageAdapter;
        partials?: Partials[];
        devGuildId?: string;
        onError?: (error: unknown, pop: Pop) => void | Promise<void>;
        onGlobalError?: (error: unknown) => void | Promise<void>;
        owners?: string[];
        state?: TState;
        commands?: { dir?: string; folderRouting?: boolean; autoSync?: boolean };
        help?:
            | boolean
            | { enabled?: boolean; command?: string; aliases?: string[] };
        status?: string | string[];
        statusInterval?: number;
        plugins?: PopiiPlugin<TState>[];
        autoDiscover?: boolean;
        pluginConfig?: Record<string, unknown>;
        events?: { dir?: string };
        snaps?: { dir?: string };
        middlewares?: { dir?: string };
        tasks?: { dir?: string };
        locales?: { dir?: string; default?: string; url?: string };
        logger?: PopLogger;
        fileLogging?: boolean;
        structuredLogs?: boolean;
        presenceStrategy?: "local" | "coordinated";
        stateTtlMs?: number;
        serverSettings?: PopiiServerSetting[];
    }

    Type Parameters

    • TState = any
    Index

    Properties

    token mode? publicKey? port? prefix? intents? redisUrl? redis? storage? partials? devGuildId? onError? onGlobalError? owners? state? commands? help? status? statusInterval? plugins? autoDiscover? pluginConfig? events? snaps? middlewares? tasks? locales? logger? fileLogging? structuredLogs? presenceStrategy? stateTtlMs? serverSettings?

    Properties

    token: string

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

    mode?: "websocket" | "http"

    Connection mode.

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

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

    port?: number

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

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

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

    intents?: number[]

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

    redisUrl?: string

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

    redis?: string | Record<string, unknown>

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

    storage?: PopiiStorageAdapter

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

    partials?: Partials[]

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

    devGuildId?: string

    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?: (error: unknown, pop: Pop) => void | Promise<void>

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

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

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

    owners?: string[]

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

    state?: TState

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

    commands?: { dir?: string; folderRouting?: boolean; autoSync?: boolean }

    Type Declaration

    • Optionaldir?: string
    • OptionalfolderRouting?: boolean

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

      true
    • OptionalautoSync?: boolean

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

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

    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?: string | string[]

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

    statusInterval?: number

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

    plugins?: PopiiPlugin<TState>[]

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

    autoDiscover?: boolean

    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.

    false
    pluginConfig?: Record<string, unknown>
    events?: { dir?: string }

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

    snaps?: { dir?: string }

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

    middlewares?: { dir?: string }

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

    tasks?: { dir?: string }

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

    locales?: { dir?: string; default?: string; url?: string }

    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).
    logger?: PopLogger

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

    fileLogging?: boolean

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

    structuredLogs?: boolean

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

    presenceStrategy?: "local" | "coordinated"

    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?: number

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

    serverSettings?: PopiiServerSetting[]

    Settings

    Member Visibility

    On This Page

    Properties