Introduction

Nubis is a TypeScript framework for Discord bots. It treats a bot the way modern web frameworks treat an app: a file is a command, types come from what you wrote, and tests run without Discord.

// commands/ping.ts → /ping
import { command } from "nubis";

export default command({
	description: "Check that the bot is alive",
	run: ({ reply }) => reply("Pong!"),
});

That file is the whole command. Run nubis dev and /ping appears in your test server; edit the file and it updates.

Why another framework

Discord's API is large, and the libraries around it mostly hand it to you as it is. You end up writing the same things in every bot: a command registry, a custom_id parser, a "did I already reply?" flag, a deploy script for commands, and the checks Discord applies only after you have shipped.

Nubis writes those once:

• Files are commands. commands/config/set.ts is /config set. Folders become subcommands and groups.
• Types come from definitions. Option values, choice unions, component state, select values and modal fields are inferred. There are no string lookups.
• Components carry typed state in their custom_id, validated with any Standard Schema library on every click.
• Discord's rules are checked when you define something, not when Discord rejects it: name formats, length limits, option counts, custom_id length, rows of components.
• One reply(). Nubis shows "thinking…" for slow handlers, turns later replies into follow-ups and answers errors, so "already replied" and "did not respond" stop happening by accident.
• Tests without Discord. nubis/testing runs commands, buttons, selects, modals and menus the way Discord would.
• Runs anywhere. Node and Bun, over the gateway or as an HTTP interactions endpoint.

How a bot is laid out

my-bot/
├── commands/          one slash command per file
│   ├── ping.ts        → /ping
│   └── fun/
│       ├── _folder.ts settings for /fun
│       └── roll.ts    → /fun roll
├── components/        buttons, selects and modals
├── menus/             right-click commands
├── events/            gateway events
├── tests/
└── nubis.config.ts    bot-wide settings

Every folder is optional. Project layout has the details.

Packages

Next: Getting started.