---
title: Cloud Firestore Emulator
description: >-
  Connect to and test against the Cloud Firestore emulator for local
  development.
next: /firestore/usage-with-flatlists
previous: /firestore/usage
---
> ## Documentation Index
> Fetch the complete documentation index at: https://rnfirebase.io/llms.txt
> Use this file to discover all available pages before exploring further.

## Prerequisites

- `@react-native-firebase/app` installed and native config completed per [Getting Started](/) (Android `google-services.json`, iOS `GoogleService-Info.plist`, Expo config plugin, or React Native CLI setup). From v26, New Architecture is required for packages with a native bridge.
- `@react-native-firebase/firestore` installed: `npm install --save @react-native-firebase/firestore` or `yarn add @react-native-firebase/firestore`, then rebuild native apps (`cd ios && pod install` on iOS).
- [Firebase CLI](https://firebase.google.com/docs/cli) available so you can run `firebase emulators:start`.
- Call `connectFirestoreEmulator` before any Firestore reads, writes, or `onSnapshot` listeners in that process (typically at app startup, gated behind `__DEV__`).

You can test your app and its Firestore implementation with an emulator which is built to mimic the behavior of Cloud Firestore. This means you can connect your app directly to the emulator to perform integration testing or QA without touching production data.

For example, you can connect your app to the emulator to safely read and write documents in testing.

## Running the emulator

To be able to mimic the behavior of Cloud Firestore, you need to run the emulator. This is effectively a server that will receive and send requests in lieu of Cloud Firestore. This is achieved by running the following commands:

```bash
# Install the Firebase CLI which will run the emulator.
curl -sL firebase.tools | bash

# Start the emulator. It will also install the Firestore emulator binary on first run.
firebase emulators:start --only firestore
```

You should see a `firestore-debug.log` file in the directory you ran the command which will have a log of all the requests.

# Connect to emulator from your app

Configure the host and port as early as possible in the startup of your application, before any read, write, or `onSnapshot` listener:

```jsx
import { Platform } from 'react-native';
import '@react-native-firebase/app';
import { connectFirestoreEmulator, getFirestore } from '@react-native-firebase/firestore';

// Set the host and the port before any read, write, or onSnapshot listener so production data is not affected.
if (__DEV__) {
  const host = Platform.OS === 'android' ? '10.0.2.2' : '127.0.0.1';
  connectFirestoreEmulator(getFirestore(), host, 8080);
}

const db = getFirestore();
console.log('Firestore instance ready:', Boolean(db));
```

Notes on `connectFirestoreEmulator`:

- It takes a non-empty host and a numeric port, and throws otherwise.
- On Android, `localhost` and `127.0.0.1` are rewritten to `10.0.2.2` and a message is logged. Set `android_bypass_emulator_url_remap` to `true` in `firebase.json` to keep the host you pass (see [JSON Config](/app/json-config)). Use your machine's IP address when running on a physical device.
- It applies once per app and database. A second call for the same instance is ignored by the native layer, so choose the host before the first call.
- The optional fourth `options` argument (`mockUserToken`, typed with `EmulatorMockTokenOptions`) exists for web SDK signature parity and is ignored at runtime. The emulator does not receive a mock user token from this call.
- After `terminate()` the native instance is discarded together with its emulator registration, so call `connectFirestoreEmulator` again before using Firestore.

# Clear locally stored emulator data

Run the following command to clear the data accumulated locally from using the emulator. Replace `[INSERT YOUR PROJECT ID HERE]` with your Firebase project id:

```bash
curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/[INSERT YOUR PROJECT ID HERE]/databases/(default)/documents"
```

There are more things that can be achieved with the emulator such as using local rules to test the integrity and security of your database. For further information, follow the Firebase emulator documentation [here](https://firebase.google.com/docs/emulator-suite).