Install Firenook

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 install --save-dev firenook

pnpm add --save-dev firenook

yarn add --dev firenook

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:

$ 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:

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:

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:

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 and 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:

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

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:

.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:

$ 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:

$ 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:

$ 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:

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.

Starting from nothing? Start a new project with firenook init. Already running the official emulator? Switch over in three steps.