@capacitor-firebase/firestore

Unofficial Capacitor plugin for Firebase Cloud Firestore.[^1]

Guides

- Announcing the Capacitor Firebase Cloud Firestore Plugin

Compatibility

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

Installation

``bash
npm install @capacitor-firebase/firestore
npx cap sync
`

Add Firebase to your project if you haven't already (Android / iOS / Web).

$3

#### 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.

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Starter templates

The following starter templates are available:

- Ionstarter Angular Firebase

Usage

`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();
};
`

API

* addDocument(...)
* setDocument(...)
* getDocument(...)
* updateDocument(...)
* deleteDocument(...)
* writeBatch(...)
* getCollection(...)
* getCollectionGroup(...)
* getCountFromServer(...)
* clearPersistence()
* enableNetwork()
* disableNetwork()
* useEmulator(...)
* addDocumentSnapshotListener(...)
* addCollectionSnapshotListener(...)
* addCollectionGroupSnapshotListener(...)
* removeSnapshotListener(...)
* removeAllListeners()
* Interfaces
* Type Aliases

$3

`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

--------------------

$3

`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

--------------------

$3

`typescript
getDocument(options: GetDocumentOptions) => Promise>
`

Reads the document referred to by the specified reference.

| Param | Type |
| ------------- | ----------------------------------------------------------------- |
| options | GetDocumentOptions |

Returns: Promise<GetDocumentResult<T>>

Since: 5.2.0

--------------------

$3

`typescript
updateDocument(options: UpdateDocumentOptions) => Promise
`

Updates fields in the document referred to by the specified reference.

| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | UpdateDocumentOptions |

Since: 5.2.0

--------------------

$3

`typescript
deleteDocument(options: DeleteDocumentOptions) => Promise
`

Deletes the document referred to by the specified reference.

| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | DeleteDocumentOptions |

Since: 5.2.0

--------------------

$3

`typescript
writeBatch(options: WriteBatchOptions) => Promise
`

Execute multiple write operations as a single batch.

| Param | Type |
| ------------- | --------------------------------------------------------------- |
| options | WriteBatchOptions |

Since: 6.1.0

--------------------

$3

`typescript
getCollection(options: GetCollectionOptions) => Promise>
`

Reads the collection referenced by the specified reference.

| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | GetCollectionOptions |

Returns: Promise<GetCollectionResult<T>>

Since: 5.2.0

--------------------

$3

`typescript
getCollectionGroup(options: GetCollectionGroupOptions) => Promise>
`

Reads the collection group referenced by the specified reference.

| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| options | GetCollectionGroupOptions |

Returns: Promise<GetCollectionGroupResult<T>>

--------------------

$3

`typescript
getCountFromServer(options: GetCountFromServerOptions) => Promise
`

Fetches the number of documents in a collection.

| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| options | GetCountFromServerOptions |

Returns: Promise<GetCountFromServerResult>

Since: 6.4.0

--------------------

$3

`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

--------------------

$3

`typescript
enableNetwork() => Promise
`

Re-enables use of the network.

Since: 5.2.0

--------------------

$3

`typescript
disableNetwork() => Promise
`

Disables use of the network.

Since: 5.2.0

--------------------

$3

`typescript
useEmulator(options: UseEmulatorOptions) => Promise
`

Instrument your app to talk to the Firestore emulator.

| Param | Type |
| ------------- | ----------------------------------------------------------------- |
| options | UseEmulatorOptions |

Since: 6.1.0

--------------------

$3

`typescript
addDocumentSnapshotListener(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback) => Promise
`

Adds a listener for document snapshot events.

| Param | Type |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| options | AddDocumentSnapshotListenerOptions |
| callback | AddDocumentSnapshotListenerCallback<T> |

Returns: Promise<string>

Since: 5.2.0

--------------------

$3

`typescript
addCollectionSnapshotListener(options: AddCollectionSnapshotListenerOptions, callback: AddCollectionSnapshotListenerCallback) => Promise
`

Adds a listener for collection snapshot events.

| Param | Type |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| options | AddCollectionSnapshotListenerOptions |
| callback | AddCollectionSnapshotListenerCallback<T> |

Returns: Promise<string>

Since: 5.2.0

--------------------

$3

`typescript
addCollectionGroupSnapshotListener(options: AddCollectionGroupSnapshotListenerOptions, callback: AddCollectionGroupSnapshotListenerCallback) => Promise
`

Adds a listener for collection group snapshot events.

| Param | Type |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| options | AddCollectionGroupSnapshotListenerOptions |
| callback | AddCollectionGroupSnapshotListenerCallback<T> |

Returns: Promise<string>

Since: 6.1.0

--------------------

$3

`typescript
removeSnapshotListener(options: RemoveSnapshotListenerOptions) => Promise
`

Remove a listener for document or collection snapshot events.

| Param | Type |
| ------------- | --------------------------------------------------------------------------------------- |
| options | RemoveSnapshotListenerOptions |

Since: 5.2.0

--------------------

$3

`typescript
removeAllListeners() => Promise
`

Remove all listeners for this plugin.

Since: 5.2.0

--------------------

$3


#### 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 | DocumentData | An object containing the data for the new document. | | 5.2.0 |
| merge | 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 | DocumentData | An object containing the data for the new document. | 6.1.0 |
| options | 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 | QueryCompositeFilterConstraint | The filter to apply. | 5.2.0 |
| queryConstraints | 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 | QueryCompositeFilterConstraint | The filter to apply. | 5.2.0 |
| queryConstraints | 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 | QueryCompositeFilterConstraint | The filter to apply. | 5.2.0 |
| queryConstraints | 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 | QueryCompositeFilterConstraint | The filter to apply. | 6.1.0 |
| queryConstraints | 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 |

$3


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

GetDocumentResult<T>


#### CallbackId

string


#### AddCollectionSnapshotListenerCallback

(event: AddCollectionSnapshotListenerCallbackEvent<T> | null, error: any): void


#### AddCollectionSnapshotListenerCallbackEvent

GetCollectionResult<T>


#### AddCollectionGroupSnapshotListenerCallback

(event: AddCollectionGroupSnapshotListenerCallbackEvent<T> | null, error: any): void


#### AddCollectionGroupSnapshotListenerCallbackEvent

GetCollectionGroupResult<T>

Limitations

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.
- The FieldValue` data type is not yet supported (see https://github.com/capawesome-team/capacitor-firebase/issues/443).

Changelog

See CHANGELOG.md.

License

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.