# Firefox engine

> The Firefox engine on code.extension.dev runs a real Gecko in the page beside the emulator and reports its verdict on every build.

Canonical: https://docs.extension.dev/code/firefox-engine
This page as Markdown: https://docs.extension.dev/code/firefox-engine.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) · [Build console](https://docs.extension.dev/code/build-console.md) · [Checkpoints](https://docs.extension.dev/code/checkpoints.md) · [Drafts](https://docs.extension.dev/code/drafts.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

---

# Firefox engine

The Firefox engine is a real Gecko that boots in the page and installs your
extension, in place of the Chromium emulator. Reach for it when you want
Firefox's own verdict on a build, in Firefox's own words.

## Quick start

```text
preview-firefox
```

Press **Switch to Firefox** in the actions bar above the preview. The address
gains a `/firefox` suffix, the engine boots, and the build installs. Type the
command above in the terminal and it prints whether the engine is alive,
which build it judged, and the verdict.


## How it works

### A switch, not a second page

The actions bar names the runner, **Chromium runner** or **Firefox runner**,
with a link to switch. Each engine has its own address: `/new/chromium` and
`/new/firefox`, `/drafts/<id>/chromium` and `/drafts/<id>/firefox`. The
switch is drawn only when the browser can run the engine: WebAssembly JSPI, a
viewport at least 768 px wide, and a fine pointer such as a mouse.

### Who can open it

The engine answers only to logins on its own allowlist, which is separate
from the workbench's. Any other login, and any address outside the
workbench, gets a 404. Today that list is the owner's.

### What Gecko gets

Firefox refuses `background.service_worker`, so the build is adapted on its
way to Gecko: `service_worker` becomes `background.scripts`,
`firefox:`-prefixed manifest keys apply, `chromium:`-prefixed keys drop, and
a `browser_specific_settings.gecko.id` is added. Scripts and styles stay the
Chromium build, so an API only Chrome ships can still fail there, and
whatever Gecko refuses is reported in its own words.

### Reading the verdict

`preview-firefox` prints the engine's liveness, the current build, and one
of three verdicts: booted and painted the first build, applied, or refused
with Gecko's sentence. A refusal exits non-zero. A verdict for an older
build carries a `[stale: ...]` mark until the newer build is answered. The
same refusal sentence appears above the terminal as **Firefox refused this
build**, and `preview-errors` carries a `firefox:` line while the engine is
up.

## Reference

| Address | Engine |
| --- | --- |
| `/new/chromium`, `/drafts/<id>/chromium` | Chromium emulator |
| `/new/firefox`, `/drafts/<id>/firefox` | Real Gecko |

| Requirement | Value |
| --- | --- |
| WebAssembly JSPI | Required |
| Viewport | 768 px or wider, with a fine pointer |
| Login | On the engine allowlist |

| Output of `preview-firefox` | Meaning |
| --- | --- |
| `firefox: booted and painted the first build` | The engine is up and the first build installed |
| `firefox: applied` | The current build installed |
| `firefox refused: <sentence>` | Gecko refused the install, exit 1 |
| `No verdict yet: the engine is booting or the first build is still applying.` | Wait and run it again |

## When it fails

- **There is no Switch to Firefox link.** The browser has no WebAssembly
  JSPI, the window is narrower than 768 px, or the pointer is coarse. Open
  the workbench on a desktop Chrome or Edge 137 or newer, or Firefox 153 or
  newer.
- **The `/firefox` address answers Not found.** Your login is not on the
  engine's allowlist. The Chromium address still works.
- **`preview-firefox` says no Firefox tab has spoken yet.** The engine has
  not booted. Switch to Firefox and wait for the first paint, then run it
  again.
- **Gecko refused the build.** Read the sentence word for word. A
  `background.service_worker` refusal means the adaptation did not apply,
  and a refused permission is one Firefox does not grant.
- **The download still says chrome.** The built zip is the Chromium build.
  The Gecko adaptation happens in the preview only.

## Next

- [Live preview](/code/preview) for the Chromium emulator
- [Terminal](/code/terminal) for `preview-firefox` beside the other commands
- [Download and run locally](/code/download-and-run) for running the build in
  a browser of your own