# seedcord guide

> The guide to building Discord bots with seedcord.

- seedcord has no presence in training data. Read a page before you write code against it.
- `seedcord` on npm is the command line tool. A bot installs `@seedcord/gateway` for a websocket connection, or `@seedcord/http` to answer Discord's interactions endpoint. It installs one of the two.
- Read the current version of every package from the npm registry. Each one has its own version number.
- A command is declared in one file and answered in another, by a handler class carrying a route decorator. seedcord reads those decorators at startup and dispatches every interaction itself.
- `seedcord codegen` writes the typed tables for slash commands, user and message context menus, emojis, and plugin keys. Run it after changing any of those.
- The steps for building a bot are at https://guide.seedcord.org/.well-known/agent-skills/seedcord/SKILL.md.
- The API reference is at https://docs.seedcord.org, one page per symbol.
- The project site is at https://seedcord.org.

- [Start here](https://guide.seedcord.org/index.md): The guide to seedcord, a TypeScript framework for Discord bots built on discord.js. Covers what the framework does, the thinking behind it, errors you can act on, commands that type your handlers, what a project looks like, the two transports, and what you need installed.
- [Gateway or http](https://guide.seedcord.org/gateway-or-http.md): seedcord ships two transports, and a bot installs one of them. Covers what gateway receives, what http receives, how to pick, and switching later.
- [Create your Discord application](https://guide.seedcord.org/discord-application.md): Set your bot's application up in Discord's developer portal before you write any code. Covers the token, the intents you turn on, the public key an http bot verifies requests with, and adding the bot to a server.
- [Your first bot](https://guide.seedcord.org/first-bot.md): Create a seedcord project with the scaffolder and get it answering in Discord. Covers what it asks, running it, what the scaffolder made, changing the ping command, and a file that fails to import.
- [The core object](https://guide.seedcord.org/core.md): Read your config and your plugins from any handler through this.core. Covers what it carries, running work while your bot starts and stops, and the property a plugin becomes.
- [Where to go next](https://guide.seedcord.org/where-to-go-next.md): You have a running bot, and this is where the rest of the guide goes. Covers each tab, the example bots in the repo, the API reference, and where to ask when you get stuck.
- Commands
  - [Commands](https://guide.seedcord.org/commands.md): Create a slash command from two files, one that declares it to Discord and one that answers it. Covers the command file, where each command deploys, codegen, the handler file, and what happens when a command has no handler or its constructor throws.
  - [Options](https://guide.seedcord.org/commands/options.md): Declare options on a slash command and read them back through getters typed from what you declared. Covers the option kinds, required options dropping the null, choices, channel types, and a getter that goes missing.
  - [Subcommands and groups](https://guide.seedcord.org/commands/subcommands.md): Put related slash commands under one name with subcommands and groups. Covers the route each branch gets, the parent that stops being a route, and the middle segment a group adds.
  - [One handler, several commands](https://guide.seedcord.org/commands/one-handler.md): One handler class can answer several slash commands and branch on the route that ran. Covers subcommands, the options every route shares, keeping both lists on the same routes, and the arm every route needs.
  - [Autocomplete](https://guide.seedcord.org/commands/autocomplete.md): Suggest option values while someone types, so they pick from your data rather than guessing. Covers one arm per field, serving several commands from one handler, the string value you always receive, and reading the options they already filled in.
  - [Context menu commands](https://guide.seedcord.org/commands/context-menus.md): Add a right-click command on a user or a message, and read what someone ran it on. Covers the base class each kind has, reaching the member, serving several commands from one handler, and the separate names each kind keeps.
  - [Command mentions](https://guide.seedcord.org/commands/mentions.md): Mention a slash command in your bot's messages, so a reader clicks it rather than retyping it. Covers the route keys, what an entry holds, why a command in two servers has no mention, when the list fills during startup, and context menu commands.
  - [Deployed commands](https://guide.seedcord.org/commands/deployed.md): Your bot sends its commands to Discord every time it starts. Covers the request that replaces a whole scope, the last global command that stays live, removing guild commands, and the flags.
  - [Why your command has not appeared](https://guide.seedcord.org/commands/missing.md): Your logs say a command deployed and Discord doesn't show it. Covers checking the scope first, the permissions that hide it from everyone, and the limits you may be near.
- Replying
  - [Replying](https://guide.seedcord.org/replying.md): Answer an interaction from its handler with reply, defer, edit, and followUp. Covers why the answer goes through the handler, a reply as a list of components, keeping it to one person, and the message you get back.

  - **Sending**
  - [Deferring](https://guide.seedcord.org/replying/deferring.md): Keep an interaction open past Discord's three-second limit, then fill the reply in when your handler finishes. Covers setting ephemeral at deferral time, the throw when you call reply() after, and deferring before anything slow.
  - [Follow-ups and edits](https://guide.seedcord.org/replying/more-messages.md): Send more messages after the first reply, then edit or delete them later. Covers the targets that have to come from this interaction, and send() picking the method for you.
  - [When a reply throws](https://guide.seedcord.org/replying/ack-states.md): Discord tracks what state an interaction is in, and that decides which reply methods still work. Covers the states, the methods each one allows, and three errors a reply call throws.
  - [Files and attachments](https://guide.seedcord.org/replying/files.md): Upload files with a reply and show them in the message. Covers the component that has to reference the upload, and the four fields.
  - [Raw acks](https://guide.seedcord.org/replying/raw-acks.md): Reply through discord.js's own methods on this.event and seedcord stops tracking the interaction. Covers the stale state that leaves, the lint rule reporting it, and the two cases that need one.

  - **Throwing**
  - [Throwing](https://guide.seedcord.org/replying/throwing.md): Refuse from a handler by throwing a Notice, so the user gets a reason rather than silence. Covers what each kind of throw produces, the fields on a Notice, and what render receives.
  - [Faults](https://guide.seedcord.org/replying/faults.md): A throw your handler doesn't catch still owes the user an answer. Covers the card every fault renders, anything else you throw, stopping without a reply, and throws outside any handler.
  - [Reporting faults](https://guide.seedcord.org/replying/reporting.md): Send the throws your bot reports to a Discord channel through a webhook. Covers what seedcord checks at boot, writing a reporter of your own, and the one card a minute limit.
  - [Tuning error behavior](https://guide.seedcord.org/replying/error-behavior.md): Set what your bot does with an error through the errors block on your config. Covers replacing the card an unknown fault shows, the two ignore lists, and catching seedcord's own errors by code.

  - **Formatting a message**
  - [Formatting helpers](https://guide.seedcord.org/replying/formatting.md): Helpers for the text your bot sends, so a raw id or a millisecond count reaches the user as something readable. Covers snowflake timestamps, durations, big numbers, ranks, names a reader scans, random picks, and objects that won't stringify.
  - [Rendering a table](https://guide.seedcord.org/replying/render-table.md): Draw an aligned table into a message with renderTable(). Covers picking a frame, aligning and capping columns, wide characters and emoji, filling and spacing, and paging past Discord's character limit.
- Components
  - [Components](https://guide.seedcord.org/components.md): Build the cards, buttons, and rows your bot sends as classes over the discord.js builders. Covers a row of buttons, which builder each key wraps, your bot color, and emojis by name.

  - **Custom IDs**
  - [Custom IDs](https://guide.seedcord.org/components/custom-ids.md): Declare what a component's custom id carries with CustomId, so a click arrives with typed values. Covers minting the string, the field kinds, reading an id back by hand, and clicks the router should skip.
  - [When a custom id goes stale](https://guide.seedcord.org/components/stale.md): Someone clicks a component your bot minted under an older custom id shape. Covers the edits that change the shape hash, what your user sees, a wire from a different id, and replacing both cards with your own.

  - **Handling a click**
  - [Buttons](https://guide.seedcord.org/components/buttons.md): Answer a button click with ButtonHandler, reading the values its custom id carries. Covers rewriting the message the click came from, and one handler serving several buttons.
  - [Select menus](https://guide.seedcord.org/components/select-menus.md): Answer a select menu pick, from a string menu you write the options for to the menus Discord resolves for you. Covers routing the pick, the resolving kinds, and one handler serving several menus.
  - [Modals](https://guide.seedcord.org/components/modals.md): Collect text, menu picks, files, and checkboxes from a user with a modal. Covers opening it with showModal, reading the submission, what a label can hold, and rewriting the message it came from.
  - [Confirmation prompts](https://guide.seedcord.org/components/confirm.md): Ask for a second click before something destructive with getConfirmation(). Covers its options, replacing the prompt after an answer, building the prompt's buttons yourself, and when a prompt is the wrong tool.

  - **Pagination**
  - [Pagination](https://guide.seedcord.org/components/pagination.md): Page through a long list with Paginator, so a user walks it with buttons. Covers where the items come from, what a paginator takes, and rendering each item.
  - [Sources](https://guide.seedcord.org/components/pagination-sources.md): Decide where a paginator's items come from, whether that's an array you already hold or one page at a time from your database. Covers a source without a total, the page every source returns, and writing one of your own.
  - [Custom rendering](https://guide.seedcord.org/components/pagination-render.md): Take over a paginator's whole message with render(). Covers a page with no buttons on it, and placing the nav buttons back yourself.
  - [Paging it yourself](https://guide.seedcord.org/components/pagination-headless.md): Page a message without a Paginator, using paginate() where the class doesn't fit. Covers the cursor you declare, what paginate() returns, and where the buttons still work.
- Checks
  - [Checks](https://guide.seedcord.org/checks.md): Decide whether a handler runs, and run code around it. Covers the order seedcord runs a dispatch in, gates, middleware, rate limits, and checks inside a handler.

  - **Gates**
  - [Gates](https://guide.seedcord.org/checks/gates.md): Run checks before your handler with @Gated, so a caller who fails one never reaches your code. Covers how a gate refuses, stacking several on one handler, the gates seedcord ships, and rewording the refusal a user sees.
  - [Permissions](https://guide.seedcord.org/checks/permissions.md): Check the caller's permissions, your bot's permissions, or the caller's role before a handler runs. Covers channel and server permissions, event handlers, and rewording each refusal.
  - [Your own gates](https://guide.seedcord.org/checks/your-own.md): Write a gate of your own with defineGate() when the shipped ones don't fit your rule. Covers what a check reads, narrowing it to certain handlers, the two guild permission fields, async checks, and what to throw.
  - [Combining gates](https://guide.seedcord.org/checks/combining.md): Combine gates with or() and and(), for example to let a command run when any one gate passes, or to group checks you reuse. Covers which handlers a combined gate fits, when an or moves on to its next arm, and what the user sees when every arm refuses.
  - [Effect gates](https://guide.seedcord.org/checks/effect-gates.md): Write a gate that changes something, like spending a credit, with defineEffectGate(). Covers when the change runs, what happens when a later gate refuses, and effect gates inside an or().

  - **Middleware**
  - [Interaction middleware](https://guide.seedcord.org/checks/middleware.md): Run code before your interaction handlers with middleware. Covers which interactions it runs for, the order, stopping a dispatch, replying, and cleaning up in after().
  - [The dispatch context](https://guide.seedcord.org/checks/dispatch-context.md): Pass values from a middleware to the rest of a dispatch with the dispatch context. Covers typing its keys and reading them in a handler, a gate, and a fault card.

  - **Rate limiting**
  - [Cooldowns](https://guide.seedcord.org/checks/cooldown.md): Limit how often a command runs with the Cooldown() gate. Covers durations, uses per window, who shares a window, wording the refusal, and keeping windows across restarts.
  - [The rate limiter](https://guide.seedcord.org/checks/rate-limiter.md): Count uses against any key you build with the rate limiter. Covers charging and reading a window, building keys, clearing a key, and writing a durable store.

  - **Inside a handler**
  - [Permissions in a handler](https://guide.seedcord.org/checks/in-handler-permissions.md): Check permissions inside a handler with assertPermissions() and the gateway helpers. Covers asserting a bitfield, refusing a permission the target holds, rewording the refusal, and checking a member, a role, or your own bot.
  - [Changing roles](https://guide.seedcord.org/checks/changing-roles.md): Check that your bot can assign a role, then build and write a member's new role list. Covers hasPermsToAssign(), rewording its refusals, mergeRoles(), and writing the list on each transport.
- Events
  - [Your first event handler](https://guide.seedcord.org/events.md): Run code when a discord.js event fires, with an event handler class. Covers registering an event, reading its payload, where handler files go, intents, running a handler once, and several handlers for one event.
  - [Several events in one class](https://guide.seedcord.org/events/several-events.md): Run one handler class for several discord.js events with this.match(). Covers what each arm receives, the compile error for a missing arm, returning a value from an arm, and mixing frequencies.
  - [Event middleware](https://guide.seedcord.org/events/middleware.md): Run code before your event handlers with event middleware. Covers stopping an event, choosing which events it runs for, the order, passing values along, cleaning up in after(), and where middleware files go.
  - [Handling messages](https://guide.seedcord.org/events/messages.md): Read the text of messages in a gateway event handler. Covers what the Message Content intent hides, the cases Discord exempts, turning the intent on, and when a slash command is the better route.

  - **The bus**
  - [The bus](https://guide.seedcord.org/events/bus.md): Send your own events between parts of your bot with the bus. Covers declaring a key, writing a subscriber, publishing, running once, listening with a callback, and the keys seedcord publishes.
  - [The framework's bus keys](https://guide.seedcord.org/events/default-keys.md): Subscribe to the keys seedcord publishes on the bus. Covers which transport publishes each key, deploys, incoming interactions and events, unhandled errors, and faults.
  - [Reading the telemetry](https://guide.seedcord.org/events/telemetry.md): Measure how long your bot takes to answer with the telemetry keys on the bus. Covers what each interaction, write, and event reports, the two timing clocks, catching a failed write, joining the keys on dispatchId, and typing a payload.
- Plugins
  - [Plugins](https://guide.seedcord.org/plugins.md): Add your own services to a bot with plugins, which seedcord starts and stops with it. Covers attaching a plugin, reading it from a handler, grouping several under one name, and where a plugin can run.
  - [Typing a plugin](https://guide.seedcord.org/plugins/typing.md): Type the plugins you attached on this.core with seedcord codegen. Covers what the generated Core block holds and when to run codegen again.
  - [The lifecycle](https://guide.seedcord.org/plugins/lifecycle.md): Control when a plugin starts and stops with init(), ready(), and dispose(). Covers the startup and shutdown phases, moving a method to another phase, timeouts, and what happens when init() or dispose() fails.
  - [Writing your own](https://guide.seedcord.org/plugins/your-own.md): Write your own plugin by extending Plugin. Covers which base to import, declaring where it runs, constructor options, rejecting bad options, logging, dev reloads, and putting it on npm.

  - **Mongoose**
  - [Mongoose](https://guide.seedcord.org/plugins/mongoose.md): Connect a gateway or http bot to MongoDB with the mongoose plugin. Covers installing and attaching it, its options, how it starts and stops, and reading the mongoose instance.
  - [Mongoose services](https://guide.seedcord.org/plugins/mongoose-services.md): Write a service class for each MongoDB collection with the mongoose plugin. Covers its schema and key, the model name, typing the services map, and reading a service from a handler.

  - **Kysely and Postgres**
  - [Kysely and Postgres](https://guide.seedcord.org/plugins/kysely.md): Connect a gateway or http bot to Postgres through Kysely with the kysely plugin. Covers its options, where the pool comes from, creating the database, startup and shutdown, and the Kysely instance.
  - [Your schema](https://guide.seedcord.org/plugins/kysely-schema.md): Type your Postgres tables for the kysely plugin by declaring a schema on KyselyDatabase. Covers the column helpers, what an undeclared schema lets through, and keeping the schema in step with your migrations.
  - [Kysely services](https://guide.seedcord.org/plugins/kysely-services.md): Write a service class for each Postgres table with the kysely plugin. Covers its table and key, overriding the table name, typing the services map, and reading a service from a handler.
  - [Migrations](https://guide.seedcord.org/plugins/kysely-migrations.md): Create and change your Postgres tables with Kysely migrations in the kysely plugin. Covers where the files go, how they're ordered, when they run, running them yourself, and what happens when one fails.
- Tooling
  - [Tooling](https://guide.seedcord.org/tooling.md): Configure a seedcord project through its two config files, one for the CLI and one for your bot. Covers every key in seedcord.config.ts, the commands that read it, and where each key of your bot's own config gets taught.
  - [The dev loop](https://guide.seedcord.org/tooling/dev.md): Run your bot locally with seedcord dev, which reloads a changed file without restarting the process. Covers what its terminal shows, the keys that drive it, filtering the log, small windows, the log files, and the health server.
  - [Hot reload](https://guide.seedcord.org/tooling/hot-reload.md): Save a file and seedcord dev swaps it into your running bot. Covers the saves that need a restart, marking your own files as one of them, rolling back a file that throws, and type-checking while you work.
  - [Codegen](https://guide.seedcord.org/tooling/codegen.md): Type your commands, emojis, and plugins by running seedcord codegen. Covers why a separate step exists, what it writes, how it loads your bot, catching a stale file in CI, and the commands it skips or rejects as duplicates.
  - [Building](https://guide.seedcord.org/tooling/build.md): Compile your bot for production with seedcord build. Covers the steps it runs, starting the output, its config keys, build failures, the runtime key, and the health server your host calls.
  - [The dev tunnel](https://guide.seedcord.org/tooling/tunnel.md): Give an http bot a public address while you work on it locally. Covers installing cloudflared, the quick tunnel seedcord dev opens by default, using a URL you already serve, turning the tunnel off, and what happens when it fails.
  - [Logging](https://guide.seedcord.org/tooling/logging.md): Log from your handlers, subscribers, and plugins through the logger each of them carries. Covers the five levels, the label on every line, extra arguments, format specifiers, channels, and logging several lines at once.
  - [Configuring the logger](https://guide.seedcord.org/tooling/logger-config.md): Set where your bot's logs go and how much of them prints, through the logger block on your bot config. Covers the level floor, a floor per channel, replacing the sinks, writing your own sink, and installing one alongside the rest.
  - [Linting](https://guide.seedcord.org/tooling/lint.md): Catch bot mistakes in your editor with the shared ESLint config and its seedcord and discord.js rules. Covers the config file, what each rule set catches, turning one rule off, the other options, formatting, and adding all of it to an existing project.