Skip to main content

Firebase CLI

Firebase CLI is used to launch Firebase emulators for local development, including the Realtime Database, Firestore, Authentication, and other Firebase services.

Installation for Apple ARM (M1/M2/M3) Chips​

IMPORTANT: If you are developing on an Apple ARM chip (M1, M2, M3, etc.), DO NOT install the standalone binary version of Firebase CLI from the Firebase website.

Why the Binary Version Fails​

The Firebase CLI binary automatically launches under Rosetta with x86 emulation. Our project uses the canvas module, which relies on native binaries compiled for ARM architecture. When Firebase CLI runs under Rosetta (x86), it attempts to load the ARM-compiled canvas library, causing an architecture mismatch that results in the canvas module failing to load and emulators crashing.

The project includes Firebase CLI as a dependency. Use the project's version via npm scripts:

# Run Firebase emulators using the project's Firebase CLI
npm run firebase -- emulators:start

Option 2: Install via npm​

Install Firebase CLI globally using npm:

npm install -g firebase-tools

Then use it normally:

firebase emulators:start

Using Firebase Emulators​

Firebase emulators allow you to develop and test locally without connecting to production Firebase services.

Starting Emulators​

# Using project's Firebase CLI
npm run firebase -- emulators:start

# Or if installed globally via npm
firebase emulators:start

Available Emulators​

  • Realtime Database: Local database instance for testing
  • Firestore: Cloud Firestore emulator
  • Authentication: Auth emulator for testing user flows
  • Functions: Test Cloud Functions locally
  • Storage: Firebase Storage emulator

Emulator UI​

When emulators are running, you can access the Emulator UI at:

http://localhost:4000

The UI provides:

  • Visual interface for viewing and modifying data
  • Request logs for Functions
  • User management for Authentication
  • Storage browser

Troubleshooting​

Canvas module errors on ARM Mac​

If you see errors like "Canvas module failed to load" or architecture mismatch errors when starting emulators:

  1. Uninstall the standalone binary Firebase CLI
  2. Use one of the recommended options above (project's version or npm install)
  3. Clear any cached emulator data: firebase emulators:exec --clear-data
  4. Restart your terminal to ensure no environment variables point to the old binary

Common error messages:

  • Error: Cannot find module 'canvas'
  • Error loading shared library
  • Architecture-related errors mentioning x86_64 vs arm64

Port conflicts​

If emulators fail due to port conflicts, you can configure custom ports in firebase.json:

{
  "emulators": {
    "database": {
      "port": 9000
    },
    "firestore": {
      "port": 8080
    }
  }
}