> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# chapterjs build

> Check every file of your bot and compile it into one file for production

`chapterjs build` checks your bot and compiles it for production. Everything that can be wrong with your files is found here, before anything is online. It is what the `build` script of your project runs:

```bash pnpm theme={"theme":{"light":"github-light","dark":"vesper"}}
pnpm build
```

```bash npm theme={"theme":{"light":"github-light","dark":"vesper"}}
npm run build
```

```bash yarn theme={"theme":{"light":"github-light","dark":"vesper"}}
yarn build
```

```bash bun theme={"theme":{"light":"github-light","dark":"vesper"}}
bun run build
```

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
✓ Types checked
✓ Built in .chapterjs/build: 4 commands, 6 events (18 kB)
ℹ Run chapterjs start to put it online.
```

That is all: [`chapterjs start`](https://www.chapterjs.org/run/start) runs what was built. The build needs no token and never talks to Discord: run it anywhere, as often as you want.

> [!NOTE]
>
> The exit codes and what the command writes are in the [CLI reference](https://www.chapterjs.org/reference/cli.md#chapterjs-build).

## What it does

**1. Checks the types**

What your editor underlines, for the whole project at once, with the TypeScript installed in your project (`tsc -b`). One error stops the build:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
✗ Your project has type errors, so it was not built:
  src/commands/ban.ts(12,25): error TS18047: 'message.member' is possibly 'null'.
```

Without TypeScript, or without a `tsconfig.json`, the build says so and goes on:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
ℹ Types were not checked: TypeScript is not installed in this project (or it has no tsconfig.json).
```

**2. Runs every file once**

Every file of `src/` is loaded and what it declares is checked, like `chapterjs dev` does when you save: a name Discord refuses, an option without a description, two declarations of the same command... Each broken file is reported, then the build stops:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
✗ src/commands/poll.ts This command has no description: write it in src/messages/en-US.ts (commands: { "poll": { description: '...' } }), or in the file (description: '...').
✗ This file can't run, so your bot was not built. Fix it and build again: chapterjs dev shows the same errors while you write.
```

With several, the last line counts them: `✗ These 2 files can't run, so your bot was not built. Fix them and build again: ...`.

**3. Compiles your bot**

Your whole bot becomes **one JavaScript file**, `.chapterjs/build/bot.js`:

* every file of `src/` (commands, events, components, tasks, presence, languages), with what they import from your project;
* only what is used: code nothing calls is left out;
* compact, but with the names you wrote, and a map back to your files.

A file the compiler can't read stops the build the same way, with `can't be compiled` in the last line.

**4. Runs what it compiled**

The compiled file is loaded once, exactly as production will load it. A file that runs from `src/` but not once compiled stops the build with `can't run once compiled` in the last line.

A build that fails leaves nothing behind: the previous build is removed before compiling, so there is never a half-built bot to start by mistake.

The build also writes `.chapterjs/build/build.json`: the version of ChapterJS that made it, a fingerprint of `src/` and whether your files join voice channels. `chapterjs start` reads it to know whether the build is the one to run.

## Production runs the build, not your files

Once built, your bot does not change when you edit a file. The changes go online the next time you build and start again; until then, `chapterjs start` reminds you:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
⚠ Your files changed since the last build: the bot runs the build, not your changes. Run "chapterjs build" to put them online.
```

So you can keep working in the same folder while your bot runs. A build made by another version of ChapterJS is not run at all:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
✗ This build was made with chapterjs 0.1.3, and this is chapterjs 0.1.4.
  Run "chapterjs build" again.
```

## Errors still name your files

The compiled file is not made to be read, but you never have to: when something fails in production, the error names the file and the line **you wrote**, because the build keeps a map from the compiled file back to your sources.

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
✗ src/lib/levels.ts:42 Cannot read properties of undefined (reading 'xp')
```

The names of your functions and variables are kept too.

## What is in the build

| | In the build |
| - | - |
| Your commands, events, components, tasks, presence and languages | Yes |
| What they import from your project, wherever it is | Yes |
| Files and folders starting with `_`, when something imports them | Yes |
| Packages you installed | No: they stay in `node_modules`, which production needs too |
| Files your code reads while running (a JSON opened with `readFile`, an image...) | No: keep them next to your project |
| Your sources | No: the map only holds file names and lines |

## Nothing to install

The compiling is done by [esbuild](https://esbuild.github.io), which comes with ChapterJS: your project has nothing to add, and nothing to configure. It is only loaded by `chapterjs build`: running your bot never needs it.

> [!NOTE]
>
> With **pnpm**, a project needs one more file, or pnpm refuses to install it: esbuild comes with an install script, and pnpm wants to be told what to do with it. `create chapterjs` writes that file for you; in a project made another way, see [Project structure](https://www.chapterjs.org/setup/project-structure.md#with-pnpm-one-more-file).

> [card] [chapterjs start](https://www.chapterjs.org/run/start.md)
>
> Run for everyone the bot you built.

> [card] [Deploy](https://www.chapterjs.org/run/deploy.md)
>
> Put your bot on a machine that stays on.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.