Skip to main content
chapterjs start runs your bot in every server it is in, after chapterjs build prepared it. It is what the start script of your project runs, on the machine that hosts your bot:
That is all: the bot is online everywhere, with its commands shown in every server and in private messages. It runs what chapterjs build kept, not your files as they are now.
The --processes option, the environment variables and the exit codes are in the CLI reference.

What changes from dev

What it needs

One value: the token of your bot.
.env
On a host, you usually upload no .env file: you give BOT_TOKEN in its settings (often called “environment variables” or “secrets”). Both work, and the real environment wins when both are there. Without it:
Your token is a password. Never put it in your code, and never commit your .env file.
And a build. Without one, or with one made by another version of ChapterJS, the command stops and says what to run:
When your files changed since the build, the bot still starts, with the build:
A build that can’t run any more (a package or Node changed since it was made) stops the command: ✗ The build of your bot can't run any more: ..., followed by Run "chapterjs build" again: it says what to fix.

What it checks

The process you start checks everything once, for all the processes of the bot, before anything is online:
  • The token. A refused token stops the command: ✗ Discord refused the bot token. ...
  • The privileged intents your files need. Nothing waits in production: the message is an error and the command stops.
  • The commands, registered for everyone, only when they changed since the last start from this folder: ✓ Commands updated for everyone. Nothing is sent otherwise, and nothing is printed.
  • How many sessions the bot may still start today. Discord limits that, and resets the token of a bot that goes over, so ChapterJS stops first:

A second bot for development

We recommend two applications from the start: one bot for development on your computer, one bot for production. Discord has no way to keep what one bot does on your computer apart from what it does for everyone: its commands, its presence, its settings and its limits are the bot’s, in every server at once.
If you have one application only, make a second one for your computer: open the Developer Portal, click New Application again (name it after your bot, with “dev” in the name), and copy the token of its Bot page into the .env of your computer. Production keeps the token of the first application.
.env on your computer
Add the dev bot to your test server (chapterjs dev prints the link) and enable the same privileged intents on it when your files need some: chapterjs dev says which ones. From then on, the two bots have nothing in common:
  • your test server only shows the commands of the dev bot, exactly as your files declare them, and never one twice;
  • the presence, the privileged intents and the token of production stay as they are while you try things;
  • Discord counts what each bot does on its own: the sessions it may start per day, the requests it may send.
The rest of this page about dev is for one bot doing both.

One bot for dev and production

A bot in production and chapterjs dev can also share one token. Add DEV_GUILD_ID next to BOT_TOKEN in production too, with the same value as on your computer:
.env
Production then leaves that server alone, and you can keep working with chapterjs dev on the same bot while it is online for everyone:
  • what happens in your test server is only handled by chapterjs dev;
  • what happens everywhere else, and in private messages, is only handled by chapterjs start.
They never answer the same thing. Without DEV_GUILD_ID, production runs every server, your test server included. With it, the server count leaves it out, and says so:
What one bot can’t separate:
  • Commands. Your test server shows the commands of everyone, like any server. chapterjs dev does not add them a second time: it only registers there the commands that are new or different in your project. Used in your test server, a command always runs the code on your computer. While you are changing a command that is already in production, your test server shows it twice (yours, and the one everyone has), and chapterjs dev tells you once:
    A command for everyone belongs to the bot, not to a server: Discord gives no way to hide it in one server, and removing it would remove it for everyone. That is why two bots is the way to never see that.
  • The presence. src/presence.ts is sent by both, for one bot: Discord does not say which of the two it shows. The one you try on your computer may be seen by everyone.
  • The Developer Portal. A privileged intent you enable to try an event is enabled for production too, and resetting the token stops production.
  • The limits. The sessions a bot may start per day and the requests it may send are counted for the bot: what chapterjs dev uses is taken from production.

Large bots

Discord splits large bots in several connections, called shards. ChapterJS asks Discord how many are needed and opens them by itself. When there are many, it also spreads them over several processes, so your bot uses every CPU of the machine. You see it in the first line:
Each process runs your project for its share of the servers, and what it prints starts with its number:
  • Nothing to configure. One process is used for every 4 shards, never more than your machine has CPUs. A bot under a few thousand servers runs in one process.
  • A process that stops by itself is started again, and its servers are back in a moment. The others don’t notice. One that ran for more than a minute starts again right away; one that keeps falling waits longer each time, up to a minute.
  • Stopping the bot stops them all, cleanly. When Discord refuses the bot for good in one process, every process stops and the command ends with exit code 1.
To choose the number yourself, pass it. It is never more than the number of shards:
Asking for more processes than the bot has shards runs one process per shard, and says so:
Anything else after start is refused:

What it means for your code

Each process has its own memory. A variable of one process is not seen by the others:
  • The ready event runs once in each process, with the servers of that process.
  • guilds and everything your bot remembers are the ones of the process.
  • Private messages are all handled by the first process.
To share something between processes, keep it outside of them, in a database.
Every process runs on the same machine. Spreading a bot over several machines is not available yet.

Stopping

Press Ctrl+C, or let your host stop the process. The bot disconnects properly and goes offline at once:

Deploy

Put your bot on a machine that stays on.

Troubleshooting

Every message, and what to do about it.