disploy

Visit disploy.dev to get started!

Warning: We're still in development, and packages are published to npm every 12 hours to the @dev tag. You can view our v1.0.0 milestone to see what features are planned for the first release and their current status.

Disploy is a flexible router for building HTTP interaction-based Discord bots with ease. It's designed to make it easy to build, test and deploy Discord bots.

Features

Disploy features a library and an opinionated framework with tooling inspired by Next.js.

Library

Disploy does not come included with a "server", that's up to you to implement. We have a guide showcasing you how to do so with Express (Node.js) and Deno's inbuilt server.

This is a slimmed-down guide to using Disploy with Next.js as your server.

Usage with Next.js

The API entry point:

// Entrypoint - pages/api/interactions.ts
import { createNextAdapter } from 'disploy';
import { ExampleApp } from '../../lib/main';

export default createNextAdapter(ExampleApp);

Note: An "adapter" is a function that transforms requests from your server implementation of choice and creates a TRequest that's fed into App#router#entry which returns a Promise<TResponse> which your adapter should transform and return to Discord.

Setting up the Disploy App:

// Main Bot - lib/core/main.ts
import { App } from 'disploy';
import commands from './commands/commands';

const clientId = process.env.DISCORD_CLIENT_ID;
const token = process.env.DISCORD_TOKEN;
const publicKey = process.env.DISCORD_PUBLIC_KEY;

if (!clientId || !token || !publicKey) {
    throw new Error('Missing environment variables');
}

export const ExampleApp = new App({
    logger: {
        debug: true,
    },
});

ExampleApp.start({
    clientId,
    token,
    publicKey,
});

for (const command of commands) {
    ExampleApp.commands.registerCommand(command);
}

Setting up an array of commands:

// Command Array - lib/core/commands/commands.ts
import Ping from './core/ping';

const c = [Ping];

export default c;

Example command:

import type { ChatInputInteraction, Command } from 'disploy';

const Ping: Command = {
    name: 'ping',
    description: 'pong!',

    run(interaction: ChatInputInteraction) {
        interaction.reply({
            content: 'Hello World!',
        });
    },
};

export default Ping;

Framework

Disploy comes inbuilt with a CLI that can bundle your bot based on a file system structure, which is inspired by Next.js.

Use the "TypeScript Framework" boilerplate from create-disploy-app.

npx create-disploy-app@latest

Here are two examples, a command and a message component handler. Keep in mind none of this is exclusive to the framework, the only "framework exclusive" feature showcased here is the file structure and default exports.

// Example command - commands/ping.ts
import type { Command } from 'disploy';

export default {
    // Command "data"
    name: 'ping',
    description: 'pong!',

    // Command entrypoint
    async run(interaction) {
        if (!interaction.guild) {
            return void interaction.reply({
                content: 'You must use this in a guild.',
            });
        }

        interaction.deferReply(); // Synchronously reply to the incoming HTTP request
        const guild = await interaction.guild.fetch(); // BaseInteraction#guild is a ToBeFetched class, awaiting fetch on it will return the full structure

        // All our methods take in raw JSON (or our Message structure, coming soon)
        return void interaction.editReply({
            content: 'hello world!!!!!!!!',
            components: [
                {
                    type: 1,
                    components: [
                        {
                            type: 2,
                            label: 'Click me!',
                            style: 1,
                            custom_id: `ping-${interaction.user.id}`, // You can handle message components with express-like routes.
                        },
                    ],
                },
            ],
        });
    },
} satisfies Command;

// Example message component handler - handlers/ping.ts
import type { ButtonHandler } from 'disploy';

export default {
    customId: 'ping-:userId',

    async run(interaction) {
        const originalUser = await interaction.params.getUserParam('userId'); // This fetches a user structure from the interaction's params, it would be better to use getParam in this use case, but we're showcasing the getUserParam method here.
        const clicker = interaction.user;

        return void interaction.reply({
            content: `hello world!!!!!!!! (clicked by ${clicker}) [made by ${originalUser}]`,
        });
    },
} satisfies ButtonHandler;

disploy dev # test your bot locally with hot-reloading and tunneling

disploy deploy # deploy your bot to Cloudflare Workers

The CLI bundles your app by taking in commands and message components and turning them into a single bundle. It accomplishes this by transforming your default exports into an array, creating an App instance, and attaching an adapter for your specified target.

Planned Features

Testing

@disploy/disbench will be a testing library that will allow you to test your bot in a similar way to how you would test a web app with a mocked Discord API. View the repository here.

Example usage (this is not final):

// Disbench demo snippet (fake code)
import { Disbench } from '@disploy/disbench';

const disbench = new Disbench({
    app: 'dist/bot.js',
});

await disbench.setup(); // This will start the bot and start communicating with the framework to "deploy" commands to the mocked API

const echoCommand = disbench.commands.find({ name: 'echo' });

const response = await disbench.interact(echoCommand, {
    options: {
        message: 'Hello World!',
    },
});

expect(response).toEqual('Hello World!');

---

Join our Discord server for support and updates!