0
# React Native Firebase - Cloud Firestore
1

2
React Native Firebase Cloud Firestore provides a complete NoSQL document database with real-time synchronization capabilities. It offers comprehensive APIs that mirror the Firebase Web SDK while leveraging native mobile SDKs for enhanced performance and offline capabilities. The library supports advanced querying with real-time listeners, batch operations, transaction support, and automatic data caching with offline persistence.
3

4
## Package Information
5

6
- **Package Name**: @react-native-firebase/firestore
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @react-native-firebase/firestore`
10
- **Dependencies**: Requires `@react-native-firebase/app` to be installed
11

12
## Core Imports
13

14
```typescript
15
import firestore from '@react-native-firebase/firestore';
16
```
17

18
Alternative imports:
19

20
```typescript
21
import { firebase } from '@react-native-firebase/firestore';
22
// firebase.firestore().X
23
```
24

25
For modular API (recommended):
26

27
```typescript
28
import { 
29
  getFirestore, 
30
  collection, 
31
  doc, 
32
  getDoc, 
33
  setDoc, 
34
  addDoc, 
35
  updateDoc, 
36
  deleteDoc,
37
  onSnapshot,
38
  query,
39
  where,
40
  orderBy,
41
  limit
42
} from '@react-native-firebase/firestore';
43
```
44

45
## Basic Usage
46

47
```typescript
48
import firestore from '@react-native-firebase/firestore';
49

50
// Get a reference to the users collection
51
const usersCollection = firestore().collection('users');
52

53
// Add a new user
54
await usersCollection.add({
55
  name: 'John Doe', 
56
  email: 'john@example.com',
57
  createdAt: firestore.FieldValue.serverTimestamp()
58
});
59

60
// Get a specific user document
61
const userDoc = await firestore().collection('users').doc('userId').get();
62
if (userDoc.exists) {
63
  console.log('User data:', userDoc.data());
64
}
65

66
// Listen to real-time updates
67
const unsubscribe = firestore()
68
  .collection('users')
69
  .onSnapshot(snapshot => {
70
    snapshot.forEach(doc => {
71
      console.log(doc.id, '=>', doc.data());
72
    });
73
  });
74

75
// Query with filters
76
const activeUsers = await firestore()
77
  .collection('users')
78
  .where('active', '==', true)
79
  .orderBy('createdAt', 'desc')
80
  .limit(10)
81
  .get();
82
```
83

84
## Architecture
85

86
React Native Firebase Firestore is built around several key components:
87

88
- **Firestore Module**: Main entry point providing database operations and configuration
89
- **References**: DocumentReference and CollectionReference for accessing and manipulating data
90
- **Queries**: Advanced filtering, ordering, and pagination capabilities with real-time listeners
91
- **Transactions & Batches**: Atomic operations for data consistency
92
- **Data Types**: Rich data model with Timestamps, GeoPoints, Blobs, and FieldValues
93
- **Offline Support**: Automatic caching with configurable persistence settings
94
- **Modular API**: Modern Firebase v9+ style functional API alongside traditional namespace API
95

96
## Capabilities
97

98
### Database Operations
99

100
Core database functionality for accessing collections and documents, with full CRUD operations and real-time synchronization.
101

102
```typescript { .api }
103
// Main Firestore instance
104
firestore(): FirebaseFirestoreTypes.Module;
105

106
// Collection and document references
107
collection(collectionPath: string): FirebaseFirestoreTypes.CollectionReference;
108
doc(documentPath: string): FirebaseFirestoreTypes.DocumentReference;
109
collectionGroup(collectionId: string): FirebaseFirestoreTypes.Query;
110
```
111

112
[Database Operations](./database-operations.md)
113

114
### Querying & Filtering
115

116
Advanced query capabilities with filtering, ordering, pagination, and aggregation. Supports both simple field queries and complex composite filters.
117

118
```typescript { .api }
119
// Query methods
120
where(fieldPath: string | FirebaseFirestoreTypes.FieldPath, opStr: FirebaseFirestoreTypes.WhereFilterOp, value: any): FirebaseFirestoreTypes.Query;
121
orderBy(fieldPath: string | FirebaseFirestoreTypes.FieldPath, directionStr?: 'asc' | 'desc'): FirebaseFirestoreTypes.Query;
122
limit(limit: number): FirebaseFirestoreTypes.Query;
123
startAt(...fieldValues: any[]): FirebaseFirestoreTypes.Query;
124
endAt(...fieldValues: any[]): FirebaseFirestoreTypes.Query;
125

126
// Filter API
127
Filter(fieldPath: string | FirebaseFirestoreTypes.FieldPath, operator: FirebaseFirestoreTypes.WhereFilterOp, value: any): FirebaseFirestoreTypes.QueryFieldFilterConstraint;
128
Filter.and(...queries: FirebaseFirestoreTypes.QueryFilterConstraint[]): FirebaseFirestoreTypes.QueryCompositeFilterConstraint;
129
Filter.or(...queries: FirebaseFirestoreTypes.QueryFilterConstraint[]): FirebaseFirestoreTypes.QueryCompositeFilterConstraint;
130
```
131

132
[Querying & Filtering](./querying-filtering.md)
133

134
### Real-time Data Synchronization
135

136
Real-time listeners for documents and collections with configurable options for metadata changes and error handling.
137

138
```typescript { .api }
139
// Document snapshots
140
onSnapshot(
141
  observer: {
142
    next?: (snapshot: FirebaseFirestoreTypes.DocumentSnapshot) => void;
143
    error?: (error: Error) => void;
144
    complete?: () => void;
145
  }
146
): () => void;
147

148
// Query snapshots
149
onSnapshot(
150
  observer: {
151
    next?: (snapshot: FirebaseFirestoreTypes.QuerySnapshot) => void;
152
    error?: (error: Error) => void;
153
    complete?: () => void;
154
  }
155
): () => void;
156
```
157

158
[Real-time Data Synchronization](./realtime-sync.md)
159

160
### Transactions & Batches
161

162
Atomic operations for ensuring data consistency across multiple operations. Supports both read-write transactions and write-only batches.
163

164
```typescript { .api }
165
// Transactions
166
runTransaction(updateFunction: (transaction: FirebaseFirestoreTypes.Transaction) => Promise<any>): Promise<any>;
167

168
// Write batches
169
batch(): FirebaseFirestoreTypes.WriteBatch;
170

171
interface Transaction {
172
  get<T>(documentRef: FirebaseFirestoreTypes.DocumentReference<T>): Promise<FirebaseFirestoreTypes.DocumentSnapshot<T>>;
173
  set<T>(documentRef: FirebaseFirestoreTypes.DocumentReference<T>, data: T, options?: FirebaseFirestoreTypes.SetOptions): FirebaseFirestoreTypes.Transaction;
174
  update<T>(documentRef: FirebaseFirestoreTypes.DocumentReference<T>, data: Partial<T>): FirebaseFirestoreTypes.Transaction;
175
  delete(documentRef: FirebaseFirestoreTypes.DocumentReference): FirebaseFirestoreTypes.Transaction;
176
}
177

178
interface WriteBatch {
179
  set<T>(documentRef: FirebaseFirestoreTypes.DocumentReference<T>, data: T, options?: FirebaseFirestoreTypes.SetOptions): FirebaseFirestoreTypes.WriteBatch;
180
  update<T>(documentRef: FirebaseFirestoreTypes.DocumentReference<T>, data: Partial<T>): FirebaseFirestoreTypes.WriteBatch;
181
  delete(documentRef: FirebaseFirestoreTypes.DocumentReference): FirebaseFirestoreTypes.WriteBatch;
182
  commit(): Promise<void>;
183
}
184
```
185

186
[Transactions & Batches](./transactions-batches.md)
187

188
### Data Types & Field Values
189

190
Rich data model supporting various data types including custom Firestore types and special field operations.
191

192
```typescript { .api }
193
// Core data types
194
class Timestamp {
195
  static now(): FirebaseFirestoreTypes.Timestamp;
196
  static fromDate(date: Date): FirebaseFirestoreTypes.Timestamp;
197
  static fromMillis(milliseconds: number): FirebaseFirestoreTypes.Timestamp;
198
  toDate(): Date;
199
  toMillis(): number;
200
}
201

202
class GeoPoint {
203
  constructor(latitude: number, longitude: number);
204
  readonly latitude: number;
205
  readonly longitude: number;
206
}
207

208
class FieldValue {
209
  static serverTimestamp(): FirebaseFirestoreTypes.FieldValue;
210
  static delete(): FirebaseFirestoreTypes.FieldValue;
211
  static increment(n: number): FirebaseFirestoreTypes.FieldValue;
212
  static arrayUnion(...elements: any[]): FirebaseFirestoreTypes.FieldValue;
213
  static arrayRemove(...elements: any[]): FirebaseFirestoreTypes.FieldValue;
214
}
215

216
class Blob {
217
  static fromBase64String(base64: string): FirebaseFirestoreTypes.Blob;
218
  static fromUint8Array(array: Uint8Array): FirebaseFirestoreTypes.Blob;
219
  toBase64(): string;
220
  toUint8Array(): Uint8Array;
221
}
222
```
223

224
[Data Types & Field Values](./data-types.md)
225

226
### Offline & Network Management
227

228
Comprehensive offline support with configurable persistence, network management, cache control, and data bundle operations.
229

230
```typescript { .api }
231
// Network control
232
enableNetwork(): Promise<void>;
233
disableNetwork(): Promise<void>;
234

235
// Persistence management
236
clearPersistence(): Promise<void>;
237
waitForPendingWrites(): Promise<void>;
238
terminate(): Promise<void>;
239

240
// Bundle operations
241
loadBundle(bundle: string): Promise<FirebaseFirestoreTypes.LoadBundleTaskProgress>;
242
namedQuery(queryName: string): FirebaseFirestoreTypes.Query | null;
243

244
// Settings configuration
245
settings(settings: FirebaseFirestoreTypes.Settings): Promise<void>;
246

247
// Emulator support
248
useEmulator(host: string, port: number): void;
249

250
interface Settings {
251
  persistence?: boolean;
252
  cacheSizeBytes?: number;
253
  host?: string;
254
  ssl?: boolean;
255
  ignoreUndefinedProperties?: boolean;
256
  serverTimestampBehavior?: 'estimate' | 'previous' | 'none';
257
}
258
```
259

260
[Offline & Network Management](./offline-network.md)
261

262
### Modular API
263

264
Modern Firebase v9+ style functional API providing tree-shakable imports and improved developer experience.
265

266
```typescript { .api }
267
// Core functions
268
function getFirestore(app?: FirebaseAppTypes.Module, databaseId?: string): FirebaseFirestoreTypes.Firestore;
269
function doc(firestore: FirebaseFirestoreTypes.Firestore, path: string, ...pathSegments: string[]): FirebaseFirestoreTypes.DocumentReference;
270
function collection(firestore: FirebaseFirestoreTypes.Firestore, path: string, ...pathSegments: string[]): FirebaseFirestoreTypes.CollectionReference;
271

272
// Document operations
273
function getDoc<T>(reference: FirebaseFirestoreTypes.DocumentReference<T>): Promise<FirebaseFirestoreTypes.DocumentSnapshot<T>>;
274
function setDoc<T>(reference: FirebaseFirestoreTypes.DocumentReference<T>, data: T): Promise<void>;
275
function updateDoc<T>(reference: FirebaseFirestoreTypes.DocumentReference<T>, data: Partial<T>): Promise<void>;
276
function deleteDoc(reference: FirebaseFirestoreTypes.DocumentReference): Promise<void>;
277
function addDoc<T>(reference: FirebaseFirestoreTypes.CollectionReference<T>, data: T): Promise<FirebaseFirestoreTypes.DocumentReference<T>>;
278
```
279

280
[Modular API](./modular-api.md)
281

282
## Types
283

284
### Core Interfaces
285

286
```typescript { .api }
287
interface DocumentData {
288
  [field: string]: any;
289
}
290

291
interface GetOptions {
292
  source: 'default' | 'server' | 'cache';
293
}
294

295
interface SetOptions {
296
  merge?: boolean;
297
  mergeFields?: (string | FirebaseFirestoreTypes.FieldPath)[];
298
}
299

300
interface SnapshotListenOptions {
301
  includeMetadataChanges: boolean;
302
}
303

304
interface SnapshotMetadata {
305
  fromCache: boolean;
306
  hasPendingWrites: boolean;
307
}
308
```
309

310
### Type Definitions
311

312
```typescript { .api }
313
type WhereFilterOp = '<' | '<=' | '==' | '>' | '>=' | '!=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in';
314
type DocumentChangeType = 'added' | 'removed' | 'modified';
315
type OrderByDirection = 'desc' | 'asc';
316
type LogLevel = 'debug' | 'error' | 'silent';
317

318
interface DocumentSnapshot<T = DocumentData> {
319
  data(options?: SnapshotOptions): T | undefined;
320
  get(fieldPath: keyof T | FirebaseFirestoreTypes.FieldPath, options?: SnapshotOptions): any;
321
  exists: boolean;
322
  id: string;
323
  metadata: FirebaseFirestoreTypes.SnapshotMetadata;
324
  ref: FirebaseFirestoreTypes.DocumentReference<T>;
325
}
326

327
interface QuerySnapshot<T = DocumentData> {
328
  docs: FirebaseFirestoreTypes.QueryDocumentSnapshot<T>[];
329
  empty: boolean;
330
  metadata: FirebaseFirestoreTypes.SnapshotMetadata;
331
  query: FirebaseFirestoreTypes.Query<T>;
332
  size: number;
333
  docChanges(options?: SnapshotListenOptions): FirebaseFirestoreTypes.DocumentChange<T>[];
334
}
335
```