FirebaseHow-ToBeginner · 4 min read

How to Use Firestore Emulator for Local Development

To use the Firestore emulator, install the Firebase CLI and start the emulator with firebase emulators:start --only firestore. Then, configure your app to connect to the local emulator instead of the live Firestore service by calling connectFirestoreEmulator(db, 'localhost', 8080) in your Firestore client setup.

📐

Syntax

The Firestore emulator is started using the Firebase CLI command. You specify which emulators to run with the --only flag. In your app code, you connect to the emulator by calling connectFirestoreEmulator(db, host, port) on your Firestore instance.

firebase emulators:start --only firestore: Starts only the Firestore emulator locally.
connectFirestoreEmulator(db, 'localhost', 8080): Connects your app's Firestore client to the local emulator running on port 8080.

bash and javascript

firebase emulators:start --only firestore

// In your app code (JavaScript example):
import { getFirestore, connectFirestoreEmulator } from 'firebase/firestore';

const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);

💻

Example

This example shows how to start the Firestore emulator and connect a simple JavaScript app to it. The app writes and reads a document locally without affecting your real Firestore database.

javascript

/* Start Firestore emulator in terminal */
firebase emulators:start --only firestore

/* JavaScript app code */
import { initializeApp } from 'firebase/app';
import { getFirestore, connectFirestoreEmulator, doc, setDoc, getDoc } from 'firebase/firestore';

const firebaseConfig = {
  apiKey: 'fake-api-key',
  authDomain: 'fake-auth-domain',
  projectId: 'demo-project',
};

const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

// Connect to local Firestore emulator
connectFirestoreEmulator(db, 'localhost', 8080);

async function runExample() {
  const docRef = doc(db, 'users', 'user1');
  await setDoc(docRef, { name: 'Alice', age: 30 });
  const docSnap = await getDoc(docRef);
  if (docSnap.exists()) {
    console.log('Document data:', docSnap.data());
  } else {
    console.log('No such document!');
  }
}

runExample();

Output

Document data: { name: 'Alice', age: 30 }

⚠️

Common Pitfalls

Common mistakes when using the Firestore emulator include:

Not starting the emulator before running your app, causing connection errors.
Forgetting to call connectFirestoreEmulator in your app, so it still connects to the live Firestore.
Using the wrong host or port in connectFirestoreEmulator.
Not updating security rules or indexes in the emulator environment.

javascript

/* Wrong: No emulator connection, app uses live Firestore */
const db = getFirestore(app);

/* Right: Connect to emulator on localhost port 8080 */
connectFirestoreEmulator(db, 'localhost', 8080);

📊

Quick Reference

Command / Code	Description
firebase emulators:start --only firestore	Start Firestore emulator locally
connectFirestoreEmulator(db, 'localhost', 8080)	Connect Firestore client to emulator
firebase.json	Configure emulator settings and ports
firebase emulators:exec	Run scripts with emulator environment
firebase emulators:stop	Stop running emulators

✅

Key Takeaways

Always start the Firestore emulator with the Firebase CLI before running your app locally.

Use connectFirestoreEmulator(db, 'localhost', 8080) in your app to connect to the local emulator.

Check that your app uses the emulator host and port, or it will connect to the live Firestore by default.

Update your security rules and indexes in the emulator environment for accurate testing.

Use firebase.json to customize emulator ports and settings for your project.