Your first bot

You need the token from the last page.

pnpm create seedcord

• Where the project goes. The folder name becomes the package name, so it takes lowercase letters, digits, and . _ -.
• TypeScript or JavaScript.
• How Discord reaches your bot. Gateway or http, the choice from two pages ago.
• What your bot should react to. Gateway only. A checklist covering messages in servers, reactions, member joins, polls, and more. Each one says which intents and partials it needs, and the privileged ones are marked. The scaffolder writes the set into your bot.ts.
• Your bot token.
• Your app public key. Http only.
• Your bot color. Every embed and container you build takes it, unless you set a color on that one yourself.

Then the scaffolder installs your dependencies, formats the project, runs seedcord codegen, and makes a git commit.

cd my-bot
pnpm run dev

Your bot logs in and sends its commands to Discord. The terminal turns into a dev console.

The scaffold ships a ping command. Type /ping in a server your bot is in.

The command probably won't be there yet. Global commands take time to appear, and Discord doesn't publish how long that takes.

The ping command came from a file the scaffolder wrote, along with everything else in this tree.

my-bot/
├─ .vscode/
│  └─ extensions.json
├─ src/
│  ├─ commands/
│  │  └─ Ping.ts
│  ├─ events/
│  │  └─ Ready.ts
│  ├─ handlers/
│  │  └─ Ping.ts
│  ├─ bot.ts
│  ├─ index.ts
│  └─ seedcord-gen.d.ts
├─ .env
├─ .gitignore
├─ .prettierignore
├─ eslint.config.ts
├─ package.json
├─ prettier.config.ts
├─ README.md
├─ seedcord.config.ts
├─ tsconfig.build.json
└─ tsconfig.json

• src/bot.ts builds your bot and exports it. src/index.ts imports that and starts it. They are separate so the CLI can import bot.ts and read your commands without logging in.
• seedcord.config.ts configures the CLI. Your bot's own settings go in bot.ts, which is the file below.
• src/seedcord-gen.d.ts carries the types generated from your config and your commands. seedcord codegen writes it and you commit it.
• tsconfig.json type-checks the project. tsconfig.build.json compiles src into dist.
• .env holds your token. bot.ts sets Envapter.baseDir to the project root, which is where envapt (opens in a new tab) then looks for the file.
• src/events/ holds Ready.ts. Picking any of the message capabilities swaps that for Mentioned.ts, which answers when someone mentions your bot.

Every answer you gave shows up in one object.

import { resolve } from 'node:path';

import { Seedcord } from '@seedcord/gateway';
import { GatewayIntentBits } from 'discord.js';
import { Envapter } from 'envapt';

Envapter.baseDir = resolve(import.meta.dirname, '..');

export const seedcord = new Seedcord({
    bot: {
        // passed straight to the discord.js Client constructor
        clientOptions: {
            intents: [GatewayIntentBits.Guilds]
        },
        interactions: {
            path: resolve(import.meta.dirname, './handlers')
        },
        commands: {
            path: resolve(import.meta.dirname, './commands')
        },
        events: {
            path: resolve(import.meta.dirname, './events')
        }
    },
    subscribers: {
        path: null
    },
    botColor: '#4ade80',
    notifications: {
        developerUsername: 'you'
    }
});

export default seedcord;

The path keys name the folders seedcord scans at startup. The tab that teaches each folder covers its key.

Two files make /ping work.

import {
    BuilderComponent,
    RegisterCommand
} from '@seedcord/gateway';

@RegisterCommand('global')
export class Ping extends BuilderComponent<'command'> {
    constructor() {
        super('command');

        this.instance
            .setName('ping')
            .setDescription('Check that the bot is answering')
            .addBooleanOption((option) =>
                option
                    .setName('detailed')
                    .setDescription('Include process uptime')
            );
    }
}

Discord gets a name, a description, and one optional boolean.

import {
    SlashHandler,
    SlashRoute,
    timestampFromSnowflake
} from '@seedcord/gateway';

@SlashRoute('ping')
export class Ping extends SlashHandler<'ping'> {
    public async execute(): Promise<void> {
        const roundtrip =
            Date.now() - timestampFromSnowflake(this.event.id);
        const lines = ['### Pong', `Roundtrip **${roundtrip}ms**`];

        if (this.options.getBoolean('detailed')) {
            lines.push(
                `Uptime **${Math.round(process.uptime())}s**`
            );
        }

        await this.reply(lines.join('\n'));
    }
}

That runs when someone uses it. 'ping' appears twice, on the decorator and on the generic, and both have to match the name the command sets. The compiler catches a mismatch. this.options carries detailed because seedcord codegen recorded it off the command file.

Open src/handlers/Ping.ts and change what it replies with. Save.

The dev server reloads the handler while the bot stays connected. Run /ping again and the new reply comes back.

Now open src/commands/Ping.ts and change the command itself, its description for example. Save, then look at the terminal. The dev server asks whether to re-register.

Commands updated:
- src/commands/Ping.ts
Refresh commands? (y/n)

A handler edit needs no confirmation because nothing leaves your machine. A command edit does, since the new definition has to go to Discord before anyone sees it.

Press y. That sends the new command to Discord and runs seedcord codegen, which rewrites src/seedcord-gen.d.ts so your handler's types match what the command now declares.

Press n if you want Discord to keep the old command.

seedcord imports every file under src/commands, src/handlers, and src/events at startup. A syntax error in any one of them stops the whole scan. A half-typed file saved mid-edit does it too, so the restart below is the normal way back.

src/handlers/Ping.ts threw while importing.

Fix the file and press r to restart.