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
```