Capacitor plugin for Firebase Cloud Firestore.
npm install @capacitor-firebase/firestoreUnofficial Capacitor plugin for Firebase Cloud Firestore.[^1]
- Announcing the Capacitor Firebase Cloud Firestore Plugin
| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | >=8.x.x | Active support |
| 7.x.x | 7.x.x | Deprecated |
| 6.x.x | 6.x.x | Deprecated |
``bash`
npm install @capacitor-firebase/firestore
npx cap sync
Add Firebase to your project if you haven't already (Android / iOS / Web).
#### Variables
If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:
- $firebaseFirestoreVersion version of com.google.firebase:firebase-firestore (default: 26.0.2)
This can be useful if you encounter dependency conflicts with other plugins in your project.
No configuration required for this plugin.
A working example can be found here: robingenz/capacitor-firebase-plugin-demo
The following starter templates are available:
`typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';
const addDocument = async () => {
await FirebaseFirestore.addDocument({
reference: 'users',
data: {
first: 'Alan',
last: 'Turing',
born: 1912
},
});
};
const setDocument = async () => {
await FirebaseFirestore.setDocument({
reference: 'users/Aorq09lkt1ynbR7xhTUx',
data: {
first: 'Alan',
last: 'Turing',
born: 1912
},
merge: true,
});
};
const getDocument = async () => {
const { snapshot } = await FirebaseFirestore.getDocument({
reference: 'users/Aorq09lkt1ynbR7xhTUx',
});
return snapshot;
};
const updateDocument = async () => {
await FirebaseFirestore.updateDocument({
reference: 'users/Aorq09lkt1ynbR7xhTUx',
data: {
first: 'Alan',
last: 'Turing',
born: 1912
},
});
};
const deleteDocument = async () => {
await FirebaseFirestore.deleteDocument({
reference: 'users/Aorq09lkt1ynbR7xhTUx',
});
};
const writeBatch = async () => {
await FirebaseFirestore.writeBatch({
operations: [
{
type: 'set',
reference: 'users/Aorq09lkt1ynbR7xhTUx',
data: {
first: 'Alan',
last: 'Turing',
born: 1912
},
options: { merge: true },
},
{
type: 'update',
reference: 'users/Aorq09lkt1ynbR7xhTUx',
data: {
first: 'Alan',
last: 'Turing',
born: 1912
},
},
{
type: 'delete',
reference: 'users/Aorq09lkt1ynbR7xhTUx',
},
],
});
};
const getCollection = async () => {
const { snapshots } = await FirebaseFirestore.getCollection({
reference: 'users',
compositeFilter: {
type: 'and',
queryConstraints: [
{
type: 'where',
fieldPath: 'born',
opStr: '==',
value: 1912,
},
],
},
queryConstraints: [
{
type: 'orderBy',
fieldPath: 'born',
directionStr: 'desc',
},
{
type: 'limit',
limit: 10,
},
],
});
return snapshots;
};
const getCollectionGroup = async () => {
const { snapshots } = await FirebaseFirestore.getCollectionGroup({
reference: 'users',
compositeFilter: {
type: 'and',
queryConstraints: [
{
type: 'where',
fieldPath: 'born',
opStr: '==',
value: 1912,
},
],
},
queryConstraints: [
{
type: 'orderBy',
fieldPath: 'born',
directionStr: 'desc',
},
{
type: 'limit',
limit: 10,
},
],
});
return snapshots;
};
const enableNetwork = async () => {
await FirebaseFirestore.enableNetwork();
};
const disableNetwork = async () => {
await FirebaseFirestore.disableNetwork();
};
const useEmulator = async () => {
await FirebaseFirestore.useEmulator({
host: '10.0.2.2',
port: 9001,
});
};
const addDocumentSnapshotListener = async () => {
const callbackId = await FirebaseFirestore.addDocumentSnapshotListener(
{
reference: 'users/Aorq09lkt1ynbR7xhTUx',
},
(event, error) => {
if (error) {
console.error(error);
} else {
console.log(event);
}
}
);
return callbackId;
};
const addCollectionSnapshotListener = async () => {
const callbackId = await FirebaseFirestore.addCollectionSnapshotListener(
{
reference: 'users',
compositeFilter: {
type: 'and',
queryConstraints: [
{
type: 'where',
fieldPath: 'born',
opStr: '==',
value: 1912,
},
],
},
queryConstraints: [
{
type: 'orderBy',
fieldPath: 'born',
directionStr: 'desc',
},
{
type: 'limit',
limit: 10,
},
],
},
(event, error) => {
if (error) {
console.error(error);
} else {
console.log(event);
}
}
);
return callbackId;
};
const addCollectionGroupSnapshotListener = async () => {
const callbackId = await FirebaseFirestore.addCollectionGroupSnapshotListener(
{
reference: 'users',
compositeFilter: {
type: 'and',
queryConstraints: [
{
type: 'where',
fieldPath: 'born',
opStr: '==',
value: 1912,
},
],
},
queryConstraints: [
{
type: 'orderBy',
fieldPath: 'born',
directionStr: 'desc',
},
{
type: 'limit',
limit: 10,
},
],
},
(event, error) => {
if (error) {
console.error(error);
} else {
console.log(event);
}
}
);
return callbackId;
};
const removeSnapshotListener = async (callbackId: string) => {
await FirebaseFirestore.removeSnapshotListener({
callbackId,
});
};
const removeAllListeners = async () => {
await FirebaseFirestore.removeAllListeners();
};
`
* addDocument(...)
* setDocument(...)
* getDocument(...)
* updateDocument(...)
* deleteDocument(...)
* writeBatch(...)
* getCollection(...)
* getCollectionGroup(...)
* getCountFromServer(...)
* clearPersistence()
* enableNetwork()
* disableNetwork()
* useEmulator(...)
* addDocumentSnapshotListener(...)
* addCollectionSnapshotListener(...)
* addCollectionGroupSnapshotListener(...)
* removeSnapshotListener(...)
* removeAllListeners()
* Interfaces
* Type Aliases
`typescript`
addDocument(options: AddDocumentOptions) => Promise
Adds a new document to a collection with the given data.
| Param | Type |
| ------------- | ----------------------------------------------------------------- |
| options | AddDocumentOptions |
Returns: Promise<AddDocumentResult>
Since: 5.2.0
--------------------
`typescript`
setDocument(options: SetDocumentOptions) => Promise
Writes to the document referred to by the specified reference.
If the document does not yet exist, it will be created.
| Param | Type |
| ------------- | ----------------------------------------------------------------- |
| options | SetDocumentOptions |
Since: 5.2.0
--------------------
`typescript`
getDocument
Reads the document referred to by the specified reference.
| Param | Type |
| ------------- | ----------------------------------------------------------------- |
| options | GetDocumentOptions |
Returns: Promise<GetDocumentResult<T>>
Since: 5.2.0
--------------------
`typescript`
updateDocument(options: UpdateDocumentOptions) => Promise
Updates fields in the document referred to by the specified reference.
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | UpdateDocumentOptions |
Since: 5.2.0
--------------------
`typescript`
deleteDocument(options: DeleteDocumentOptions) => Promise
Deletes the document referred to by the specified reference.
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | DeleteDocumentOptions |
Since: 5.2.0
--------------------
`typescript`
writeBatch(options: WriteBatchOptions) => Promise
Execute multiple write operations as a single batch.
| Param | Type |
| ------------- | --------------------------------------------------------------- |
| options | WriteBatchOptions |
Since: 6.1.0
--------------------
`typescript`
getCollection
Reads the collection referenced by the specified reference.
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | GetCollectionOptions |
Returns: Promise<GetCollectionResult<T>>
Since: 5.2.0
--------------------
`typescript`
getCollectionGroup
Reads the collection group referenced by the specified reference.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| options | GetCollectionGroupOptions |
Returns: Promise<GetCollectionGroupResult<T>>
--------------------
`typescript`
getCountFromServer(options: GetCountFromServerOptions) => Promise
Fetches the number of documents in a collection.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| options | GetCountFromServerOptions |
Returns: Promise<GetCountFromServerResult>
Since: 6.4.0
--------------------
`typescript`
clearPersistence() => Promise
Clears the persistent storage. This includes pending writes and cached documents.
Must be called after the app is shutdown or when the app is first initialized.
Since: 5.2.0
--------------------
`typescript`
enableNetwork() => Promise
Re-enables use of the network.
Since: 5.2.0
--------------------
`typescript`
disableNetwork() => Promise
Disables use of the network.
Since: 5.2.0
--------------------
`typescript`
useEmulator(options: UseEmulatorOptions) => Promise
Instrument your app to talk to the Firestore emulator.
| Param | Type |
| ------------- | ----------------------------------------------------------------- |
| options | UseEmulatorOptions |
Since: 6.1.0
--------------------
`typescript`
addDocumentSnapshotListener
Adds a listener for document snapshot events.
| Param | Type |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| options | AddDocumentSnapshotListenerOptions |
| callback | AddDocumentSnapshotListenerCallback<T> |
Returns: Promise<string>
Since: 5.2.0
--------------------
`typescript`
addCollectionSnapshotListener
Adds a listener for collection snapshot events.
| Param | Type |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| options | AddCollectionSnapshotListenerOptions |
| callback | AddCollectionSnapshotListenerCallback<T> |
Returns: Promise<string>
Since: 5.2.0
--------------------
`typescript`
addCollectionGroupSnapshotListener
Adds a listener for collection group snapshot events.
| Param | Type |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| options | AddCollectionGroupSnapshotListenerOptions |
| callback | AddCollectionGroupSnapshotListenerCallback<T> |
Returns: Promise<string>
Since: 6.1.0
--------------------
`typescript`
removeSnapshotListener(options: RemoveSnapshotListenerOptions) => Promise
Remove a listener for document or collection snapshot events.
| Param | Type |
| ------------- | --------------------------------------------------------------------------------------- |
| options | RemoveSnapshotListenerOptions |
Since: 5.2.0
--------------------
`typescript`
removeAllListeners() => Promise
Remove all listeners for this plugin.
Since: 5.2.0
--------------------
#### AddDocumentResult
| Prop | Type | Description | Since |
| --------------- | --------------------------------------------------------------- | ------------------------------------------ | ----- |
| reference | DocumentReference | The reference of the newly added document. | 5.2.0 |
#### DocumentReference
| Prop | Type | Description | Since |
| ---------- | ------------------- | ------------------------------------------------ | ----- |
| id | string | The document's identifier within its collection. | 5.2.0 |
| path | string | The path of the document. | 5.2.0 |
#### AddDocumentOptions
| Prop | Type | Description | Since |
| --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |data
| | DocumentData | An object containing the data for the new document. | 5.2.0 |
#### DocumentData
#### SetDocumentOptions
| Prop | Type | Description | Default | Since |
| --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------ | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | | 5.2.0 |data
| | mergeDocumentData | An object containing the data for the new document. | | 5.2.0 |
| | boolean | Whether to merge the provided data with an existing document. | false | 5.2.0 |
#### GetDocumentResult
| Prop | Type | Description | Since |
| -------------- | ---------------------------------------------------------------------- | ------------------------------ | ----- |
| snapshot | DocumentSnapshot<T> | The current document contents. | 5.2.0 |
#### DocumentSnapshot
| Prop | Type | Description | Since |
| -------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----- |
| id | string | The document's identifier within its collection. | 5.2.0 |
| path | string | The path of the document. | 5.2.0 |
| data | T \| null | An object containing the data for the document. Returns null if the document doesn't exist. | 5.2.0 |metadata
| | SnapshotMetadata | Metadata about the snapshot, concerning its source and if it has local modifications. | 6.2.0 |
#### SnapshotMetadata
| Prop | Type | Description | Since |
| ---------------------- | -------------------- | --------------------------------------------------------- | ----- |
| fromCache | boolean | True if the snapshot was created from cached data. | 6.2.0 |
| hasPendingWrites | boolean | True if the snapshot was created from pending write data. | 6.2.0 |
#### GetDocumentOptions
| Prop | Type | Description | Since |
| --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |
#### UpdateDocumentOptions
| Prop | Type | Description | Since |
| --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |data
| | DocumentData | An object containing the data for the new document. | 5.2.0 |
#### DeleteDocumentOptions
| Prop | Type | Description | Since |
| --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |
#### WriteBatchOptions
| Prop | Type | Description | Since |
| ---------------- | ---------------------------------- | --------------------------------------- | ----- |
| operations | WriteBatchOperation[] | The operations to execute in the batch. | 6.1.0 |
#### WriteBatchOperation
| Prop | Type | Description | Since |
| --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ----- |
| type | 'set' \| 'update' \| 'delete' | The type of operation. | 6.1.0 |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 6.1.0 |data
| | optionsDocumentData | An object containing the data for the new document. | 6.1.0 |
| | SetOptions | An object to configure the set behavior. | 7.3.0 |
#### SetOptions
| Prop | Type | Description | Default | Since |
| ----------- | -------------------- | -------------------------------------------------------------------------- | ------------------ | ----- |
| merge | boolean | Whether a merge should be performed or the document should be overwritten. | false | 7.3.0 |
#### GetCollectionResult
| Prop | Type | Description | Since |
| --------------- | ------------------------------------------------------------------------ | -------------------------------- | ----- |
| snapshots | DocumentSnapshot<T>[] | The documents in the collection. | 5.2.0 |
#### GetCollectionOptions
| Prop | Type | Description | Since |
| ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |compositeFilter
| | queryConstraintsQueryCompositeFilterConstraint | The filter to apply. | 5.2.0 |
| | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |
#### QueryCompositeFilterConstraint
| Prop | Type | Description | Since |
| ---------------------- | ------------------------------------ | --------------------------- | ----- |
| type | 'and' \| 'or' | The type of the constraint. | 5.2.0 |
| queryConstraints | QueryFilterConstraint[] | The filters to apply. | 5.2.0 |
#### QueryFieldFilterConstraint
| Prop | Type | Description | Since |
| --------------- | ------------------------------------------------------- | ------------------------------ | ----- |
| type | 'where' | The type of the constraint. | 5.2.0 |
| fieldPath | string | The path to compare. | 5.2.0 |
| opStr | QueryOperator | The operation string to apply. | 5.2.0 |
| value | any | The value for comparison. | 5.2.0 |
#### QueryOrderByConstraint
| Prop | Type | Description | Since |
| ------------------ | ------------------------------------------------------------- | --------------------------- | ----- |
| type | 'orderBy' | The type of the constraint. | 5.2.0 |
| fieldPath | string | The path to compare. | 5.2.0 |
| directionStr | OrderByDirection | The direction to sort by. | 5.2.0 |
#### QueryLimitConstraint
| Prop | Type | Description | Since |
| ----------- | ------------------------------------- | -------------------------------------- | ----- |
| type | 'limit' \| 'limitToLast' | The type of the constraint. | 5.2.0 |
| limit | number | The maximum number of items to return. | 5.2.0 |
#### QueryStartAtConstraint
| Prop | Type | Description | Since |
| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| type | 'startAt' \| 'startAfter' | The type of the constraint. | 5.2.0 |
| reference | string | The reference to start at or after as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read. | 5.2.0 |
#### QueryEndAtConstraint
| Prop | Type | Description | Since |
| --------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| type | 'endAt' \| 'endBefore' | The type of the constraint. | 5.2.0 |
| reference | string | The reference as to end at or before as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read. | 5.2.0 |
#### GetCollectionGroupResult
| Prop | Type | Description | Since |
| --------------- | ------------------------------------------------------------------------ | -------------------------------- | ----- |
| snapshots | DocumentSnapshot<T>[] | The documents in the collection. | 5.2.0 |
#### GetCollectionGroupOptions
| Prop | Type | Description | Since |
| ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |compositeFilter
| | queryConstraintsQueryCompositeFilterConstraint | The filter to apply. | 5.2.0 |
| | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |
#### GetCountFromServerResult
| Prop | Type | Description | Since |
| ----------- | ------------------- | ------------------------------------------ | ----- |
| count | number | The number of documents in the collection. | 6.4.0 |
#### GetCountFromServerOptions
| Prop | Type | Description | Since |
| --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 6.4.0 |
#### UseEmulatorOptions
| Prop | Type | Description | Default | Since |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- |
| host | string | The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer. | | 6.1.0 |
| port | number | The emulator port. | 8080 | 6.1.0 |
#### AddDocumentSnapshotListenerOptions
| Prop | Type | Description | Since |
| --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |
#### AddCollectionSnapshotListenerOptions
| Prop | Type | Description | Since |
| ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |compositeFilter
| | queryConstraintsQueryCompositeFilterConstraint | The filter to apply. | 5.2.0 |
| | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |
#### AddCollectionGroupSnapshotListenerOptions
| Prop | Type | Description | Since |
| ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |
| reference | string | The reference as a string, with path components separated by a forward slash (/). | 6.1.0 |compositeFilter
| | queryConstraintsQueryCompositeFilterConstraint | The filter to apply. | 6.1.0 |
| | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 6.1.0 |
#### RemoveSnapshotListenerOptions
| Prop | Type | Since |
| ---------------- | ------------------------------------------------- | ----- |
| callbackId | CallbackId | 5.2.0 |
#### QueryFilterConstraint
QueryFieldFilterConstraint | QueryCompositeFilterConstraint
#### QueryOperator
'<' | '<=' | '==' | '>=' | '>' | '!=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in'
#### QueryNonFilterConstraint
QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint
#### OrderByDirection
'desc' | 'asc'
#### AddDocumentSnapshotListenerCallback
(event: AddDocumentSnapshotListenerCallbackEvent<T> | null, error: any): void
#### AddDocumentSnapshotListenerCallbackEvent
#### CallbackId
string
#### AddCollectionSnapshotListenerCallback
(event: AddCollectionSnapshotListenerCallbackEvent<T> | null, error: any): void
#### AddCollectionSnapshotListenerCallbackEvent
#### AddCollectionGroupSnapshotListenerCallback
(event: AddCollectionGroupSnapshotListenerCallbackEvent<T> | null, error: any): void
#### AddCollectionGroupSnapshotListenerCallbackEvent
This plugin currently has the following limitations:
- The Timestamp data type is not yet supported (see https://github.com/capawesome-team/capacitor-firebase/issues/474). Use a number or a string instead.FieldValue` data type is not yet supported (see https://github.com/capawesome-team/capacitor-firebase/issues/443).
- The
See CHANGELOG.md.
See LICENSE.
[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.