Skip to main content
You have a bot account and a test server. This page turns them into a bot that is online, with a first command to try. Everything happens in a terminal.

Create the project

Open a terminal in the folder where you keep your projects, and run the command of your package manager:
It asks up to three questions:
  1. Where to create the project. A folder name, like buddy. The folder must not exist yet, or be empty. (. means “right here”, for a folder you already created.)
  2. Which package manager to use. Only the ones installed on your computer can be picked, and the one you ran the command with is preselected: press Enter.
  3. Which template to start from. Take minimal, preselected: one file, enough to see the bot online, and this tutorial adds the rest. The others (tickets, moderation, levels, giveaways) are complete bots to read once you know the framework: see Templates.
Then it copies the template, installs the dependencies (this is the part that takes a moment) and prints what to do next. A question with only one possible answer is never asked: the framework takes the answer and says so with ℹ. You will see that habit everywhere.
Pass the folder name to skip the first question: pnpm create chapterjs buddy.
Move into the folder and open it in your editor:

Give it your bot

The project has a file called .env.example:
.env.example
Copy it to a file called .env (same folder, without .example), and fill in the two values from the previous page: the token after BOT_TOKEN=, the server ID after DEV_GUILD_ID=, no quotes, no spaces. Why two files? .env.example is committed to git and shows what the project needs, with empty values. .env holds the real values and is ignored by git (look at .gitignore: it is already there). That way, your token never ends up in a repository, even a private one, and whoever gets the project knows what to fill in.
If you ever see your token in a terminal, a screenshot or a commit, reset it in the Developer Portal right away. The old one stops working, and nobody can run your bot with it.

Run it

The first time, the bot is not in your test server yet, so the terminal gives you a link and waits:
Open the link in your browser, check that it shows your test server, and confirm. The link adds the bot to that server only, with every permission: a test server is a playground, and giving the bot everything there means a missing permission never gets in the way while you learn. In production, the people who add your bot choose what they give it. Back in the terminal, the command goes on by itself:
Look at your test server: the bot is online, with “Getting ready” under its name. It does nothing else yet: the template is one file, and the next pages add everything else.

Reading the terminal

Each line of that output tells you something, and the symbol in front says what kind: Now the lines, one by one:
  • ✓ Connected to My Server as buddy: the program logged in with your token, and found your test server. “My Server” is the name of the server of DEV_GUILD_ID.
  • ℹ Intents computed from your files: GUILDS: the intents of the previous chapter. The framework read your files and asked Discord for what they need. GUILDS is the one every bot needs to know its servers; nothing in the template needs more.
  • ✓ a presence loaded: the files of src/ were read: one presence, and nothing else yet. It is the one file of the template, src/presence.ts, and it is why “Getting ready” shows under the name of the bot. Commands, events, buttons, languages: each is a chapter of this tutorial.

Stopping

Press Ctrl+C in the terminal. The bot disconnects properly and goes offline at once:
Press it once and wait for that line. A second Ctrl+C kills the program without saying goodbye, and Discord then keeps the bot shown online for a while, until it notices that nobody is on the line.

When something is wrong

Every value of .env is checked before anything else, and every problem is printed at once with what to do:
A token Discord does not recognize is refused at the first request:
That usually means the token was reset since you copied it. Reset it again, copy the new one, and start again. Every message the bot can print is gathered in Troubleshooting, with what to do about it.

Recap

  • pnpm create chapterjs (or the command of your package manager) creates the project and installs it.
  • .env holds BOT_TOKEN and DEV_GUILD_ID, and git ignores it.
  • pnpm dev runs the bot on your test server; the first time, a link adds the bot there.
  • The symbol of each line says what kind of message it is; ✗ always comes with what to do.
  • Ctrl+C once, then wait for ✓ Disconnected.

A tour of the project

What each file is for, and the rule behind all of them.

Guide: Quickstart

The same steps on one page.