# Build console

> The build console under the preview on code.extension.dev reports each compile, names what the browser refused, and hands the error to the agent.

Canonical: https://docs.extension.dev/code/build-console
This page as Markdown: https://docs.extension.dev/code/build-console.md
Section: Code
Siblings: [AI generation](https://docs.extension.dev/code.md) · [Terminal](https://docs.extension.dev/code/terminal.md) · [Chat mode](https://docs.extension.dev/code/chat-mode.md) · [Starters and templates](https://docs.extension.dev/code/starters.md) · [Live preview](https://docs.extension.dev/code/preview.md) · [Select to edit](https://docs.extension.dev/code/select-to-edit.md) · [The Code tab](https://docs.extension.dev/code/code-tab.md) · [Checkpoints](https://docs.extension.dev/code/checkpoints.md) · [Drafts](https://docs.extension.dev/code/drafts.md) · [Firefox engine](https://docs.extension.dev/code/firefox-engine.md) · [Download and run locally](https://docs.extension.dev/code/download-and-run.md) · [Share links](https://docs.extension.dev/code/share.md) · [Publish and import](https://docs.extension.dev/code/publish.md) · [Generation allowance](https://docs.extension.dev/code/allowance.md) · [Settings and sign-in](https://docs.extension.dev/code/settings.md)
Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt

---

# Build console

The build console is the strip under the preview that reports every compile.
Reach for it when the preview did not change, or when it changed and
something is red.

## Quick start

```text
build
```

Type that in the terminal. The console reads **Build ready** when the
compile passed, or **Build failed** with the error under it. Press **Fix in
terminal** and the error is prefilled as a prompt for the agent.


## How it works

### Nothing compiles on a server

The compiler is esbuild built to WebAssembly, running in a web worker in the
page. It handles TypeScript, JSX and TSX, CSS and CSS modules on its own, so
a project written in React or TypeScript builds with no toolchain of yours.
The edit to preview loop never leaves your machine.

### When a build runs

Every write from the terminal compiles on its own after a short wait: 150 ms
after a lone write, 500 ms after a burst. A second write landing inside the
open wait makes it a burst. `build` skips the wait, and **Save & rebuild**
in the Code tab compiles at once.

### What the console says

| Line | What it means |
| --- | --- |
| **Build ready** | The compile passed and the preview reloaded |
| **Build failed** | The compile stopped, and the **Build error** panel holds the diagnostic |
| **Built, but the browser refused to install it** | The build compiled and the emulated browser rejected the manifest |
| **Built, but a page failed to start** | A surface threw before it was ready |
| **Built, but the background script hit an error** | The service worker threw |

### Fix in terminal, Fix in chat

A failed build offers one button. In terminal mode it reads **Fix in
terminal** and prefills the prompt line with the error. In chat mode it
reads **Fix in chat** and fills the prompt box. Nothing is sent until you
press Enter, so you can add a sentence first.

The prefilled prompt reads:

```text
Building the extension failed with this error. Please fix it:

<the build error>
```

### Measuring a cycle

`loop-trace` prints the timing of the last edit-to-paint cycle, one line per
span, and a total that is the cycle's own clock:

```text
cycle cycle-00 trigger=agent build=build-00
  debounce-wait 500ms
  compile:total 40ms
  remount-to-ready 300ms
  total 845ms
```

`--last N` prints the last N cycles and `--json` prints them raw. Typed in
the terminal, `loop-trace` goes to the agent as a prompt, and the agent runs
it for you.

## Reference

| Limit | Value |
| --- | --- |
| Wait after a lone write | 150 ms |
| Wait after a burst of writes | 500 ms |
| Cycles `loop-trace` keeps | 50 |

| Command | What it does |
| --- | --- |
| `build` | Compiles the workspace now and prints the diagnostics |
| `loop-trace [--last N] [--json]` | Prints the timing of the last cycle, span by span |

## When it fails

- **Build failed names a file the manifest points at.** The agent wrote the
  manifest before the file. Wait for the next write, or run `build` once the
  file exists.
- **Built, but the browser refused to install it.** The manifest is valid
  JSON and still wrong for the browser. The line under it carries the
  browser's reason. Hand it to the agent with **Fix in terminal**.
- **The repairs did not land.** Restore the last known good checkpoint from
  the header, then describe the change again in smaller steps.
- **`loop-trace` says there is no cycle.** Nothing has been written since the
  page loaded. Make an edit or run `build`, then read it again.

## Next

- [Terminal](/code/terminal) for `build` and the rest of the commands
- [Live preview](/code/preview) for what a passing build reloads
- [Checkpoints](/code/checkpoints) for the restore point a build stamps