# Install Firenook

> Add Firenook to a project with npm, pnpm, Yarn or Bun, check that your machine can run it, and confirm the install before you start.

Firenook is one npm package. Install it in your project, next to firebase-tools
if you have it: keep that for deploying, since Firenook has no deploy or login
command.

**npm**

```sh
npm install --save-dev firenook
```

**pnpm**

```sh
pnpm add --save-dev firenook
```

**Yarn**

```sh
yarn add --dev firenook
```

**Bun**

```sh
bun add --dev firenook
```

Commit the lockfile: it keeps every machine and every CI run on the release
you installed until you upgrade.

Run it through your package manager (`npx firenook`, `pnpm exec firenook`,
`yarn firenook` or `bunx firenook`) or from a script in `package.json`. These
docs use `npx`.

## What it needs

The emulators run on **Node 22, 24 or 26**. Your Functions run on the same
Node, as they run on Node in production, so pick the one your Functions
target. The other commands, such as `init` and `--version`, run on any Node
from 20 up.

An older Node is refused, with the way to switch:

```console
$ npx firenook emulators:start
Firenook: the emulators need Node 22, 24 or 26, since your Functions run on it; this is Node 20.20.2. Switch to Node 24 (with nvm: nvm install 24) and run it again
```

An odd or newer major, such as Node 23 or 27, starts with a warning:

```text
Firenook: Node 23.11.0 is not one the emulators are tested on (22, 24 and 26); they start on it, and your Functions run on it. If something behaves differently, switch to Node 24 (with nvm: nvm install 24)
```

A Functions codebase whose `engines.node` asks for another Node still loads,
and the log says so, as the official emulator does:

```text
firenook functions: functions/package.json asks for Node 24 in engines.node, but these functions run on Node 22.23.3, the Node running the emulators; start the emulators with Node 24 to run them on the Node they ask for (with nvm: nvm use 24)
```

Firenook runs on these platforms, each with its own engine package:

| Platform | Engine package |
| --- | --- |
| macOS on Apple silicon | `@firenook/cli-darwin-arm64` |
| macOS on Intel | `@firenook/cli-darwin-x64` |
| Linux x64 with glibc | `@firenook/cli-linux-x64` |
| Linux arm64 with glibc | `@firenook/cli-linux-arm64` |
| Windows x64 | `@firenook/cli-win32-x64` |

On Linux the engine needs glibc 2.28 or newer: RHEL 8 and its rebuilds,
Debian 10, Ubuntu 20.04, the `node:24` and `node:24-slim` images, or a later
release of any of them. Each release starts the engine on AlmaLinux 8,
Debian 11, Ubuntu 22.04 and `node:24-slim` before it is published.

Alpine and other musl-based systems have no glibc, and an older glibc is too
old. Firenook says what the system lacks and stops:

```text
Firenook: the Linux engine needs glibc 2.28 or newer, and this system has no glibc: its C library is musl, as on Alpine Linux. Use a glibc system or image instead, such as node:24 or node:24-slim rather than node:24-alpine
```

Windows on Arm and 32-bit systems are not supported either.
[CI](https://firenook.dev/docs/get-started/ci) and [Docker](https://firenook.dev/docs/get-started/docker) say what
this means for the image you pick.

## How the engine gets installed

The `firenook` package is a small launcher. Its optional dependencies hold one
engine per platform, and your package manager installs only the one that
matches your machine. Nothing runs at install time: there is no postinstall
script and no download. Your lockfile records the engine of every platform, so
a lockfile written on a Mac installs the Linux engine in CI.

npm, pnpm, Yarn (classic, and Yarn 4 with Plug'n'Play) and Bun all install the
right engine. Keep optional dependencies enabled. Without them, for example
after `npm install --omit=optional`, every command that needs the engine
stops:

```console
$ npx firenook binary-path
Firenook: Missing @firenook/cli-darwin-arm64@0.2.0. Install with optional dependencies enabled. No postinstall script is needed.
```

> **Note**
>
> Recent releases of Yarn 4 install a version only once it is a day old (the
> `npmMinimalAgeGate` setting). On the day of a release, Yarn reports that the
> new version is quarantined; install it the next day, or lower that setting.

Nothing else is downloaded, at install or at start: no Java, no
firebase-tools, no emulator archives. The one exception is an Extension from
the registry, which is fetched once, on first use; `firenook ext:vendor`
copies it into the project so that even that works offline. In a terminal,
Firenook also asks the npm registry once a day whether a newer release is out.
It never asks in CI, and `FIRENOOK_NO_UPDATE_CHECK=1` turns the check off.

## Keep its working data out of Git

Every run keeps its working data under `.firenook/` in your project. Add that
folder to your `.gitignore`:

```text
.firenook/
```

`firenook init` adds this line for you, with `*-debug.log`.

## Check the install

`--version` prints the release and the engine's source revision. `binary-path`
finds the engine for your machine, checks it against the checksum it was
published with, and prints where it is:

```console
$ npx firenook --version
0.2.0 (engine source 7a9614bea49f8208f96d2126b29ef11ee2f2810b)
$ npx firenook binary-path
~/demo-shop/node_modules/@firenook/cli-darwin-arm64/bin/firenook
```

In a project with a `firebase.json`, `doctor` runs the checks that
`emulators:start` runs, starts nothing, and prints what it found as JSON: the
engine, the Node, the project id, the services that would start, their ports
and any warnings. Trimmed:

```console
$ npx firenook doctor
{
  "binary": "~/demo-shop/node_modules/@firenook/cli-darwin-arm64/bin/firenook",
  "node": {
    "version": "24.20.0",
    "major": 24,
    "tested": true,
    "path": "~/.nvm/versions/node/v24.20.0/bin/node"
  },
  "project": {
    "project": "demo-shop",
    "demo": true,
    "services": [
      "firestore",
      "auth",
      "storage",
      "functions",
      "pubsub"
    ],
    "host": "localhost",
    "errors": [],
    "warnings": []
  },
  "warnings": [],
  "problems": [],
  "version": "0.2.0",
  "engineRevision": "7a9614bea49f8208f96d2126b29ef11ee2f2810b"
}
```

`node` says which Node runs and whether the emulators are tested on it.
`problems` lists what would stop a start, such as a Node older than 22 or a
missing engine package; when it lists any, `doctor` exits with code 1.
`doctor` itself runs on any Node from 20 up. Without a `firebase.json` it
says so and exits with code 1:

```console
$ npx firenook doctor
Firenook: No firebase.json at ~/demo-shop/firebase.json; run firenook init in the project directory or pass --config
```

## Start the emulators

In a project that already has a `firebase.json`:

```sh
npx firenook emulators:start
```

In a terminal you get a live screen: the start-up, the ready summary and a
line for every function call. Press `o` to open the console, `r` to reload
your functions, and `q` to stop, which saves the data first. The console is at
`http://127.0.0.1:4000/console`.

## Next

Starting from nothing? [Start a new project](https://firenook.dev/docs/get-started/new-project)
with `firenook init`. Already running the official emulator?
[Switch over](https://firenook.dev/docs/get-started/switch) in three steps.