fireemu

An experimental local runtime for testing Firebase SDK and Functions code.

Some Firebase failures are easy to miss locally. A query may need a composite index in production even though it passes against the official emulator. Production limits may reject a request that looked fine during development. Finding those problems only after running against a real Firebase project makes the feedback loop slow and can leave test data behind.

fireemu was built for two jobs:

• catch selected production-facing problems earlier, including missing Firestore indexes and production limit violations;
• keep local test runs fast, with no JVM emulator to start and a single command that starts the services, runs the test command, and shuts everything down.

fireemu is experimental. It is not a replacement for the official Firebase Emulator Suite or for testing against a real Firebase project. Use it as an additional test target, keep the official emulator in your test matrix, and verify important flows against production before shipping.

The real firebase-admin, firebase (Node and browser) and firebase/firestore/lite SDKs run against it unchanged. Run npx fireemu capabilities before depending on a specific API: each capability records whether it is implemented, partial, validation-only, or unsupported. The full feature summary, the known gaps from production Firebase and from the official Emulator Suite, and the project status are in the repository README linked below.

Install

npm install -D fireemu
npx fireemu init
npx fireemu doctor

pnpm add -D fireemu        # or: pnpm dlx fireemu doctor
yarn add -D fireemu

Nothing is downloaded at install time and there is no install script. fireemu is a small Node launcher; the daemon for your platform arrives as an optional dependency (@fireemu/darwin-arm64 and friends), so npm installs exactly one binary and skips the rest. An install that resolved from a cache or a private registry is a complete, offline installation.

Initialize

npx fireemu init creates fireemu.json with the recommended strict profile. In a terminal, its wizard explains the production behavior supplied by strict, the pinned official emulator behavior selected by emulator, and how a referenced Firebase project configuration stays live. In CI or with redirected input it uses the strict defaults without prompting; use --interactive to force the wizard or --yes/--no-interactive to suppress it.

If the project already has firebase.json, init records it as a live firebaseJson reference so rules, indexes, Functions codebases and emulator ports are loaded again on every start. --profile emulator and --firebase-json <file> choose alternatives explicitly. Existing fireemu.json files are preserved unless --force is supplied, and a symbolic link is never overwritten.

npx fireemu init --yes
npx fireemu up --config fireemu.json

Use

npx fireemu up --config fireemu.json

exec is the firebase emulators:exec equivalent: it serves the same, runs a command with the emulator host variables once every listener is bound, stops everything when the command exits and exits with its status.

npx fireemu exec --firebase-json firebase.json --project my-app --only auth,firestore,storage -- vitest run

The command receives FIRESTORE_EMULATOR_HOST, FIREBASE_AUTH_EMULATOR_HOST, FIREBASE_STORAGE_EMULATOR_HOST / STORAGE_EMULATOR_HOST, GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT, and FIREEMU_CONTROL_TOKEN / FIREEMU_CONTROL_URL for the control API.

An Emulator UI is compiled into the binary and served at http://127.0.0.1:4000/ui (--ui-port 0 turns it off).

Supported platforms

| Package | OS | Arch | Built for | | --- | --- | --- | --- | | @fireemu/darwin-arm64 | macOS 13+ | Apple silicon | aarch64-apple-darwin | | @fireemu/darwin-x64 | macOS 13+ | Intel | x86_64-apple-darwin | | @fireemu/linux-x64 | Linux (any libc) | x86-64 | x86_64-unknown-linux-musl, static | | @fireemu/linux-arm64 | Linux (any libc) | arm64 | aarch64-unknown-linux-musl, static | | @fireemu/win32-x64 | Windows 10+ | x86-64 | x86_64-pc-windows-msvc |

The Linux builds are statically linked against musl, so they run on any distribution and inside distroless and Alpine containers.

Prerequisites

• Node 20 or newer to run the launcher, and to run a Functions codebase. Nothing else needs Node; Firestore, Auth, Storage and the UI are served by the binary itself.
• No Java. Unlike the Firebase Emulator Suite, fireemu runs no JVM emulator.
• For --functions <dir>: the codebase's own node_modules, with firebase-functions v6 or v7 and firebase-admin. npx fireemu doctor prints the range the bundled runner supports.

Check an installation

npx fireemu doctor

It reports the version and platform of the installed binary, whether the Emulator UI is compiled in, where the Node runner was found and which firebase-functions majors it instruments, the Node version, and that no JVM is required. Anything missing comes with a remediation line, and a broken installation exits non-zero so a setup script can gate on it. The report carries versions and paths only -- never tokens, keys, or the contents of a configuration file.

Upgrade, uninstall, offline

• Upgrade: npm install -D fireemu@<version>. The launcher pins its platform packages to its own exact version, so [email protected] can only resolve @fireemu/[email protected] -- an upgrade moves the binary and the launcher together, never one without the other.
• Uninstall: npm uninstall fireemu. Nothing is installed outside node_modules: no cache directory, no global binary, no downloaded component.
• Offline: npm install --offline works once the tarballs are in the npm cache, and so does installing from a private registry that mirrors the fireemu and @fireemu packages. Warm a cache with npm install on a machine of the same platform, or vendor the tarballs with npm pack.
• A vendored or self-built binary: set FIREEMU_BINARY_PATH to it and the launcher runs that instead of resolving a platform package.
• If the binary is missing: the launcher says which package it looked for and what is published. The usual cause is an install that skipped optional dependencies (--omit=optional, --no-optional, or a lockfile built on another platform).

Documentation and source

https://github.com/t-k/fireemu

License

Apache-2.0