cloud_firestore 0.12.5

  • Readme
  • Changelog
  • Example
  • Installing
  • 95

Cloud Firestore Plugin for Flutter #

A Flutter plugin to use the Cloud Firestore API.

pub package

For Flutter plugins for other Firebase products, see

Note: This plugin is still under development, and some APIs might not be available yet. Feedback and Pull Requests are most welcome!

Setup #

To use this plugin:

  1. Using the Firebase Console, add an Android app to your project: Follow the assistant, download the generated google-services.json file and place it inside android/app. Next, modify the android/build.gradle file and the android/app/build.gradle file to add the Google services plugin as described by the Firebase assistant. Ensure that your android/build.gradle file contains the as described here.
  2. Using the Firebase Console, add an iOS app to your project: Follow the assistant, download the generated GoogleService-Info.plist file, open ios/Runner.xcworkspace with Xcode, and within Xcode place the file inside ios/Runner. Don't follow the steps named "Add Firebase SDK" and "Add initialization code" in the Firebase assistant.
  3. Add cloud_firestore as a dependency in your pubspec.yaml file.

Usage #

import 'package:cloud_firestore/cloud_firestore.dart';

Adding a new DocumentReference:

  .setData({ 'title': 'title', 'author': 'author' });

Binding a CollectionReference to a ListView:

class BookList extends StatelessWidget {
  Widget build(BuildContext context) {
    return StreamBuilder<QuerySnapshot>(
      stream: Firestore.instance.collection('books').snapshots(),
      builder: (BuildContext context, AsyncSnapshot<QuerySnapshot> snapshot) {
        if (snapshot.hasError)
          return new Text('Error: ${snapshot.error}');
        switch (snapshot.connectionState) {
          case ConnectionState.waiting: return new Text('Loading...');
            return new ListView(
              children: document) {
                return new ListTile(
                  title: new Text(document['title']),
                  subtitle: new Text(document['author']),

Performing a query:

    .where("topic", isEqualTo: "flutter")
    .listen((data) =>
        data.documents.forEach((doc) => print(doc["title"])));

Get a specific document:

        .then((DocumentSnapshot ds) {
      // use ds as a snapshot

Running a transaction:

final DocumentReference postRef = Firestore.instance.document('posts/123');
Firestore.instance.runTransaction((Transaction tx) async {
  DocumentSnapshot postSnapshot = await tx.get(postRef);
  if (postSnapshot.exists) {
    await tx.update(postRef, <String, dynamic>{'likesCount':['likesCount'] + 1});

Getting Started #

See the example directory for a complete sample app using Cloud Firestore.

0.12.5 #

  • Makes startAtDocument, startAfterDocument, endAtDocument and endBeforeDocument work with Query.collectionGroup queries.
  • Fixes startAtDocument, startAfterDocument, endAtDocument and endBeforeDocument to also work with a descending order as the last explicit sort order.
  • Fixed an integration test by increasing the value of cacheSizeBytes to a valid value.

0.12.4 #

  • Added support for Query.collectionGroup.

0.12.3 #

  • Added support for cacheSizeBytes to Firestore.settings.

0.12.2 #

  • Ensure that all channel calls to the Dart side from the Java side are done on the UI thread. This change allows Transactions to work with upcoming Engine restrictions, which require channel calls be made on the UI thread. Note this is an Android only change, the iOS implementation was not impacted.
  • Updated the Firebase reporting string to flutter-fire-fst to be consistent with other reporting libraries.

0.12.1 #

  • Added support for Source to Query.getDocuments() and DocumentReference.get().

0.12.0+2 #

  • Bump the minimum Flutter version to 1.5.
  • Replace invokeMethod with invokeMapMethod wherever necessary.

0.12.0+1 #

  • Send user agent to Firebase.

0.12.0 #

  • Breaking change. Fixed CollectionReference.parent to correctly return a DocumentReference. If you were using the method previously to obtain the parent document's id via collectionReference.parent().id, you will have to use collectionReference.parent().documentID now.
  • Added DocumentReference.parent.

0.11.0+2 #

  • Remove iOS dependency on Firebase/Database and Firebase/Auth CocoaPods.

0.11.0+1 #

  • Update iOS CocoaPod dependencies to '~> 6.0' to ensure support for FieldValue.increment.

0.11.0 #

  • Update Android dependencies to latest.

0.10.1 #

  • Support for startAtDocument, startAfterDocument, endAtDocument, endBeforeDocument.
  • Added additional unit and integration tests.

0.10.0 #

  • Support for FieldValue.increment.
  • Remove FieldValue.type and FieldValue.value from public API.
  • Additional integration testing.

0.9.13+1 #

  • Added an integration test for transactions.

0.9.13 #

  • Remove Gradle BoM to avoid Gradle version issues.

0.9.12 #

  • Move Android dependency to Gradle BoM to help maintain compatibility with other FlutterFire plugins.

0.9.11 #

  • Bump Android dependencies to latest.

0.9.10 #

  • Support for cloud_firestore running in the background on Android.
  • Fixed a bug in cleanup for DocumentReference.snapshots().
  • Additional integration testing.

0.9.9 #

  • Remove invokeMapMethod calls to prevent crash.

0.9.8 #

  • Add metadata field to DocumentSnapshot.

0.9.7+2 #

  • Bump the minimum Flutter version to 1.2.0.
  • Add template type parameter to invokeMethod calls.

0.9.7+1 #

  • Update README with example of getting a document.

0.9.7 #

  • Fixes a NoSuchMethodError when using getDocuments on iOS (introduced in 0.9.6).
  • Adds a driver test for getDocuments.

0.9.6 #

  • On iOS, update null checking to match the recommended pattern usage in the Firebase documentation.
  • Fixes a case where snapshot errors might result in plugin crash.

0.9.5+2 #

  • Fixing PlatformException(Error 0, null, null) which happened when a successful operation was performed.

0.9.5+1 #

  • Log messages about automatic configuration of the default app are now less confusing.

0.9.5 #

  • Fix an issue on some iOS devices that results in reading incorrect dates.

0.9.4 #

  • No longer sends empty snapshot events on iOS when encountering errors.

0.9.3 #

  • Fix transactions on iOS when getting snapshot that doesn't exist.

0.9.2 #

  • Fix IllegalStateException errors when using transactions on Android.

0.9.1 #

  • Fixed Firebase multiple app support in transactions and document snapshots.

0.9.0+2 #

  • Remove categories.

0.9.0+1 #

  • Log a more detailed warning at build time about the previous AndroidX migration.

0.9.0 #

  • Breaking change. Migrate from the deprecated original Android Support Library to AndroidX. This shouldn't result in any functional changes, but it requires any Android apps using this plugin to also migrate if they're using the original support library.

0.8.2+3 #

  • Resolved "explicit self reference" and "loses accuracy" compiler warnings.

0.8.2+2 #

  • Clean up Android build logs. @SuppressWarnings("unchecked")

0.8.2+1 #

  • Avoid crash in document snapshot callback.

0.8.2 #

  • Added Firestore.settings
  • Added Timestamp class

0.8.1+1 #

  • Bump Android dependencies to latest.

0.8.1 #

  • Fixed bug where updating arrays in with FieldValue always throws an Exception on Android.

0.8.0 #

Note: this version depends on features available in iOS SDK versions 5.5.0 or later. To update iOS SDK in existing projects run pod update Firebase/Firestore.

  • Added Firestore.enablePersistence
  • Added FieldValue with all currently supported values: arrayUnion, arrayRemove, delete and serverTimestamp.
  • Added arrayContains argument in Query.where method.

0.7.4 #

  • Bump Android and Firebase dependency versions.

0.7.3 #

  • Updated Gradle tooling to match Android Studio 3.1.2.

0.7.2 #

  • Fixes crash on Android if a FirebaseFirestoreException happened.

0.7.1 #

  • Updated iOS implementation to reflect Firebase API changes.
  • Fixed bug in Transaction.get that would fail on no data.
  • Fixed error in code sample.

0.7.0+2 #

  • Update transactions example in README to add await.

0.7.0+1 #

  • Add transactions example to README.

0.7.0 #

  • Breaking change. snapshots is now a method instead of a getter.
  • Breaking change. setData uses named arguments instead of SetOptions.

0.6.3 #

  • Updated Google Play Services dependencies to version 15.0.0.

0.6.2 #

  • Support for BLOB data type.

0.6.1 #

  • Simplified podspec for Cocoapods 1.5.0, avoiding link issues in app archives.

0.6.0 #

  • Breaking change. Renamed 'getCollection()' to 'collection().'

0.5.1 #

  • Expose the Firebase app corresponding to a Firestore
  • Expose a constructor for a Firestore with a non-default Firebase app

0.5.0 #

  • Breaking change. Move path getter to CollectionReference
  • Add id getter to CollectionReference

0.4.0 #

  • Breaking change. Hide Firestore codec class from public API.
  • Adjusted Flutter SDK constraint to match Flutter release with extensible platform message codec, required already by version 0.3.1.
  • Move each class into separate files

0.3.2 #

  • Support for batched writes.

0.3.1 #

  • Add GeoPoint class
  • Allow for reading and writing DocumentReference, DateTime, and GeoPoint values from and to Documents.

0.3.0 #

  • Breaking change. Set SDK constraints to match the Flutter beta release.

0.2.12 #

  • Fix handling of null document snapshots (document not exists).
  • Add DocumentSnapshot.exists.

0.2.11 #

  • Fix Dart 2 type errors.

0.2.10 #

  • Fix Dart 2 type errors.

0.2.9 #

  • Relax sdk upper bound constraint to '<2.0.0' to allow 'edge' dart sdk use.

0.2.8 #

  • Support for Query.getDocuments

0.2.7 #

  • Add transaction support.

0.2.6 #

  • Build fixes for iOS
  • Null checking in newly added Query methods

0.2.5 #

  • Query can now have more than one orderBy field.
  • startAt, startAfter, endAt, and endBefore support
  • limit support

0.2.4 #

  • Support for DocumentReference.documentID
  • Support for CollectionReference.add

0.2.3 #

  • Simplified and upgraded Android project template to Android SDK 27.
  • Updated package description.

0.2.2 #

  • Add get to DocumentReference.

0.2.1 #

  • Fix bug on Android where removeListener is sometimes called without a handle

0.2.0 #

  • Breaking change. Upgraded to Gradle 4.1 and Android Studio Gradle plugin 3.0.1. Older Flutter projects need to upgrade their Gradle setup as well in order to use this version of the plugin. Instructions can be found here.
  • Relaxed GMS dependency to [11.4.0,12.0[

0.1.2 #

  • Support for DocumentReference update and merge writes
  • Suppress unchecked warnings and package name warnings on Android

0.1.1 #

  • Added FLT prefix to iOS types.

0.1.0 #

  • Added reference to DocumentSnapshot
  • Breaking: removed path from DocumentSnapshot
  • Additional test coverage for reading collections and documents
  • Fixed typo in DocumentChange documentation

0.0.6 #

  • Support for getCollection

0.0.5 #

  • Support isNull filtering in Query.where
  • Fixed DocumentChange.oldIndex and DocumentChange.newIndex to be signed integers (iOS)

0.0.4 #

  • Support for where clauses
  • Support for deletion

0.0.3 #

  • Renamed package to cloud_firestore

0.0.2 #

  • Add path property to DocumentSnapshot

0.0.1+1 #

  • Update project homepage

0.0.1 #

  • Initial Release


// Copyright 2017, the Chromium project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:cloud_firestore/cloud_firestore.dart';

Future<void> main() async {
  final FirebaseApp app = await FirebaseApp.configure(
    name: 'test',
    options: const FirebaseOptions(
      googleAppID: '1:79601577497:ios:5f2bcc6ba8cecddd',
      gcmSenderID: '79601577497',
      apiKey: 'AIzaSyArgmRGfB5kiQT6CunAOmKRVKEsxKmy6YI-G72PVU',
      projectID: 'flutter-firestore',
  final Firestore firestore = Firestore(app: app);
  await firestore.settings(timestampsInSnapshotsEnabled: true);

      title: 'Firestore Example', home: MyHomePage(firestore: firestore)));

class MessageList extends StatelessWidget {

  final Firestore firestore;

  Widget build(BuildContext context) {
    return StreamBuilder<QuerySnapshot>(
      stream: firestore.collection('messages').snapshots(),
      builder: (BuildContext context, AsyncSnapshot<QuerySnapshot> snapshot) {
        if (!snapshot.hasData) return const Text('Loading...');
        final int messageCount =;
        return ListView.builder(
          itemCount: messageCount,
          itemBuilder: (_, int index) {
            final DocumentSnapshot document =[index];
            return ListTile(
              title: Text(document['message'] ?? '<No message retrieved>'),
              subtitle: Text('Message ${index + 1} of $messageCount'),

class MyHomePage extends StatelessWidget {
  final Firestore firestore;
  CollectionReference get messages => firestore.collection('messages');

  Future<void> _addMessage() async {
    await messages.add(<String, dynamic>{
      'message': 'Hello world!',
      'created_at': FieldValue.serverTimestamp(),

  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Firestore Example'),
      body: MessageList(firestore: firestore),
      floatingActionButton: FloatingActionButton(
        onPressed: _addMessage,
        tooltip: 'Increment',
        child: const Icon(Icons.add),

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  cloud_firestore: ^0.12.5

2. Install it

You can install packages from the command line:

with Flutter:

$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:cloud_firestore/cloud_firestore.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Jun 13, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.9+1
  • Flutter: 1.17.3

Analysis suggestions

Package does not support Flutter platform linux

Because of import path [package:cloud_firestore/cloud_firestore.dart]

Package does not support Flutter platform macos

Because of import path [package:cloud_firestore/cloud_firestore.dart]

Package does not support Flutter platform web

Because of import path [package:cloud_firestore/cloud_firestore.dart]

Package does not support Flutter platform windows

Because of import path [package:cloud_firestore/cloud_firestore.dart]

Package not compatible with SDK dart

because of import path [cloud_firestore]

Health suggestions

Fix lib/src/document_change.dart. (-0.50 points)

Analysis of lib/src/document_change.dart reported 1 hint:

line 40 col 19: The value of the field '_firestore' isn't used.

Fix lib/src/query_snapshot.dart. (-0.50 points)

Analysis of lib/src/query_snapshot.dart reported 1 hint:

line 37 col 19: The value of the field '_firestore' isn't used.

Maintenance issues and suggestions

Homepage URL doesn't exist. (-20 points)

At the time of the analysis the homepage field was unreachable.

Package is getting outdated. (-0.82 points)

The package was last published 52 weeks ago.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.28.0 <3.0.0
collection ^1.14.3 1.14.12
firebase_core ^0.4.0 0.4.5
flutter 0.0.0
meta ^1.0.5 1.1.8
Transitive dependencies
charcode 1.1.3
firebase 7.3.0
firebase_core_platform_interface 1.0.4
firebase_core_web 0.1.1+2
flutter_web_plugins 0.0.0
http 0.12.1
http_parser 3.1.4
js 0.6.2
matcher 0.12.6
path 1.7.0
pedantic 1.9.0
plugin_platform_interface 1.0.2
quiver 2.1.3
sky_engine 0.0.99
source_span 1.7.0
stack_trace 1.9.3
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
test any