Firelite

Firelite is an experimental local emulator system for a small, tested subset of Firebase Emulator Suite-compatible workflows. It is focused on fast startup, fast reload, and low idle overhead for multi-checkout development.

The immediate goal is to discover local SDK/emulator contracts, capture them as fixtures, and implement only the compatibility surface needed for local tests and checkout-specific Cloud Functions workflows.

• Rust workspace and firelite CLI.
• Auth emulator state namespaced by Firebase project ID.
• Storage emulator state for common JSON API and /v0 object paths.
• Pub/Sub emulator state for HTTP/JSON topic, subscription, publish, pull, and acknowledge flows.
• Cloud Tasks emulator state for task create/list/delete and local task queue dispatch.
• Checkout-local Cloud Functions supervisor with Node handler discovery and reload.
• Contract tests and SDK harnesses for supported Auth and Storage flows.
• Architecture and compatibility notes in docs/.

• Rust 1.82 or newer to install or build Firelite with Cargo.
• Node.js to load and execute Cloud Functions.
• npm only for the optional SDK compatibility harness.

Install the CLI from crates.io:

cargo install firelite --locked

From the directory containing the compiled Functions package.json and entrypoint, start the combined local stack:

cd /path/to/your-project/functions
firelite emulators \
  --project demo-firelite \
  --host 127.0.0.1 \
  --watch .

Firelite loads the Functions worker before opening the listeners. A successful startup prints the discovered function names and the Auth, Storage, Pub/Sub, Cloud Tasks, and Functions listener addresses. TypeScript must already be compiled; Firelite loads the package entrypoint but does not run the application's build command.

Point local SDKs at the listeners:

export FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099
export FIREBASE_STORAGE_EMULATOR_HOST=127.0.0.1:9199
export PUBSUB_EMULATOR_HOST=127.0.0.1:8085
export CLOUD_TASKS_EMULATOR_HOST=127.0.0.1:9899
export GCLOUD_PROJECT=demo-firelite

Use firelite functions instead when only the checkout-local Functions worker is needed:

firelite functions --project demo-firelite --watch . --port 5001

HTTP functions are served at:

http://127.0.0.1:5001/{project}/{region}/{functionName}

The proxy preserves the function's response status and body. For example, a function that forwards an upstream 404 returns that 404; a Functions worker transport failure is reported separately as 502 Bad Gateway.

For Auth without a Functions worker, run the standalone daemon:

firelite daemon --project demo-firelite --host 127.0.0.1 --port 9099

To keep Auth users between runs, pass --persist .firelite/state.sqlite to daemon or emulators. Reset one project's persisted Auth users with:

firelite reset --project demo-firelite --persist .firelite/state.sqlite

Magic sign-in links, email-verification links, and phone verification codes are printed prominently in the emulator console. Interactive terminals use cyan, magenta, and yellow highlighting; redirected output and NO_COLOR remain plain text unless FORCE_COLOR is set. Pending values are also available from /emulator/v1/projects/{project}/oobCodes and /emulator/v1/projects/{project}/verificationCodes.

Example REST call:

curl -s 'http://127.0.0.1:9099/identitytoolkit.googleapis.com/v1/accounts:signUp?key=fake' \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.test","password":"secret123","returnSecureToken":true}'

firelite daemon
firelite reset --project demo-myrepo-agent-17 --persist .firelite/state.sqlite
firelite functions --project demo-myrepo-agent-17 --watch ./functions --port 5001
firelite emulators --project demo-myrepo-agent-17 --watch ./functions
firelite emulators --project demo-myrepo-agent-17 --watch ./functions --filter api
firelite emulators --project demo-myrepo-agent-17 --watch ./functions --no-reload

daemon runs the shared Auth-compatible backend. functions runs a checkout-local Node worker supervisor for HTTP/callable Cloud Functions exports and reloads it when watched files change. TypeScript functions should be built by the surrounding test/dev workflow before Firelite loads the functions directory. reset removes one project's Auth users from the SQLite database selected by --persist.

emulators runs Auth, Storage, Pub/Sub, Cloud Tasks, and Functions together. By default it listens on the local setup ports: Auth on 127.0.0.1:9099, Storage on 127.0.0.1:9199, Pub/Sub on 127.0.0.1:8085, Cloud Tasks on 127.0.0.1:9899, and Functions on 127.0.0.1:5001. The listeners share the same state. --persist <FILE> persists Auth users; other service state remains in memory.

Listener ports come from Firelite's CLI flags. Firelite does not read firebase.json or firebase.local.json, so a project wrapper should translate its configured ports into --auth-port, --storage-port, --pubsub-port, --tasks-port, and --functions-port explicitly.

For CI runs where function source does not change after startup, pass --no-reload to skip the file polling task. The combined runner loads and validates the initial Functions worker before opening the other emulator listeners. The Functions listener reports worker liveness at /__/health.

Terminal logs are intentionally compact: Firelite keeps timestamps but omits repeated level labels and per-line worker metadata. Known request-context dumps are reduced to path/type/status/duration summaries, while application stack traces retain their original shape. Interactive terminals color HTTP methods and response status fields; redirected CI logs remain free of ANSI escapes. Set RUST_LOG=debug or RUST_LOG=firelite=debug when deeper diagnostics are needed.

Example:

cargo run -p firelite -- \
  emulators \
  --project demo-myrepo-agent-17 \
  --host 127.0.0.1 \
  --auth-port 9099 \
  --storage-port 9199 \
  --pubsub-port 8085 \
  --tasks-port 9899 \
  --functions-port 5001 \
  --watch ./functions \
  --filter api

Pass --filter to run only selected Cloud Functions exports/names. It can be repeated, for example --filter api --filter e2e.

Pub/Sub accepts HTTP/JSON emulator calls at PUBSUB_EMULATOR_HOST=127.0.0.1:8085 for topic/subscription create, publish, pull, and acknowledge flows. In firelite emulators, publishing also asynchronously invokes matching Gen 1 and Gen 2 Pub/Sub functions; this background dispatch does not require a subscription.

Cloud Tasks accepts Firebase Admin SDK task queue createTask calls at CLOUD_TASKS_EMULATOR_HOST=127.0.0.1:9899. In firelite emulators, enqueued task queue requests are dispatched directly to the checkout-local functions worker when the filter matches the queue/function name. In the basic implementation, dispatch is synchronous and runs before the create-task response returns. Dispatch targets are intentionally limited to local http:// URLs so the runtime does not carry a TLS stack.

For a checkout with custom ports, run the installed binary from its Functions directory and pass those ports explicitly. This is the recommended shape for project-local development scripts and CI:

firelite emulators \
  --project bf-demo-a24dc \
  --host 127.0.0.1 \
  --auth-port 9099 \
  --storage-port 9199 \
  --pubsub-port 8085 \
  --tasks-port 9499 \
  --functions-port 5001 \
  --watch . \
  --filter api \
  --filter platformApi \
  --filter staticIpApiProxy \
  --filter e2e

Add --no-reload for immutable CI builds. During local development, keep the application's compiler/watch process running alongside Firelite so changes reach the compiled entrypoint before Firelite reloads the worker.

To run an unpublished Firelite checkout instead, replace firelite with:

cargo run --manifest-path /path/to/firelite/Cargo.toml -p firelite --

Run the Rust test suite:

cargo test

Run the optional Firebase SDK compatibility harness:

cd harness
npm install
npm run test:auth
npm run test:auth-admin-sdk
npm run test:functions
npm run test:pubsub-sdk
npm run test:storage-sdk

The harness starts Firelite on temporary loopback ports and verifies supported flows with the official Firebase Web and Admin SDK packages.

Firelite is intentionally incomplete. See:

• docs/compatibility-matrix.md for supported, planned, and unknown surfaces.
• docs/auth-emulator-api-surface.md for Auth compatibility notes.
• docs/architecture.md for the process model and compatibility strategy.

MIT.