Firebase Emulator

SaaSStinger Lite supports Firebase Emulator for local development and testing.

The emulator allows developers to test:

• Authentication flows
• Firestore operations
• Security rules
• Workspace permissions

without affecting production data.

Emulator Architecture

Local development uses:

Next.js Application

        ↓

Firebase SDK

        ↓

Firebase Emulator Suite

        ↓

Local Firebase Services

Starting the Emulator

Start Firebase services:

firebase emulators:start

The emulator starts configured Firebase services from:

firebase.json

Checking Emulator Status

When running successfully, the terminal displays:

✔ auth emulator
✔ firestore emulator
✔ emulator UI

Common Emulator Problems

Emulator Will Not Start

Symptoms

Examples:

Port already in use

or:

Failed to start emulator

Causes

Common causes:

• Another emulator process is running
• Required ports are occupied
• Firebase CLI version mismatch

Solution

Stop existing processes:

firebase emulators:stop

Then restart:

firebase emulators:start

Firebase CLI Problems

Symptoms

Example:

firebase: command not found

Solution

Verify installation:

firebase --version

Install Firebase CLI if required:

npm install -g firebase-tools

Authentication Emulator Issues

Symptoms

Examples:

• Users cannot register
• Login works against production unexpectedly
• Emulator users disappear

Check Firebase Client Configuration

During local testing, verify the application connects to the emulator.

The application should not accidentally use production Firebase services.

Testing Authentication

Recommended test flow:

Create Test User

        ↓

Verify Authentication

        ↓

Create Workspace

        ↓

Check Firestore Data

        ↓

Test Permissions

Firestore Emulator Issues

Symptoms

Examples:

PERMISSION_DENIED

or:

Missing document

Check Rules

The emulator uses:

firestore.rules

After changing rules:

restart the emulator.

Testing Firestore Rules

Test scenarios:

Authenticated User

Verify:

• Can access permitted data
• Cannot access unrelated workspaces

Workspace Isolation

Example:

User A

Workspace A

        ❌

Workspace B

User A should not access Workspace B.

Role Testing

Test:

OWNER

ADMIN

MEMBER

Each role should have expected permissions.

Emulator Data Persistence

Local emulator data can be exported.

Example:

firebase emulators:start \
--export-on-exit=./emulator-data

Importing Emulator Data

Start with existing data:

firebase emulators:start \
--import=./emulator-data

Resetting Emulator Data

If local data becomes inconsistent:

1. Stop emulator.
2. Remove exported data.
3. Restart emulator.

Example:

rm -rf emulator-data

Then:

firebase emulators:start

Debugging Firestore Data

Use:

Firebase Emulator UI

to inspect:

• Collections
• Documents
• Authentication users
• Rules behavior

Common Development Mistakes

Using Production Data Accidentally

Symptoms:

• Test users appear in production
• Real data changes unexpectedly

Solution:

Verify Firebase configuration before testing.

Assuming Emulator Data Is Production

Emulator data is local only.

Deleting emulator data does not affect production.

Forgetting Rule Changes

After modifying:

firestore.rules

restart the emulator.

Recommended Local Workflow

Daily development workflow:

Start Emulator

        ↓

Start Next.js

        ↓

Test Feature

        ↓

Check Firestore

        ↓

Run Type Check

        ↓

Run Build

Commands:

firebase emulators:start

and:

pnpm dev

Before Production Deployment

The emulator does not replace production testing.

Before release:

Verify:

• Production Firebase project
• Firestore rules
• Environment variables
• Authentication providers
• Build output

Support Information

When reporting emulator issues include:

• Firebase CLI version
• Node.js version
• Error output
• firebase.json configuration (remove secrets)
• Steps to reproduce

Related Documentation

• Firebase Setup
• Firestore Permissions
• Environment Variables
• Running the Development Server
• Common Issues