Setting up the Firebase Firestore

The store module integrates Firestore in your project. This enables a flexible, scalable NoSQL cloud database that also works offline!

Setup

1. Create the database from the Firebase console

   Tip

   Select a location close to your users and the same as Firebase Functions if you use them.

2. Open a terminal an run the following command from the root of the project:

   firebase init

   1. Select Firestore from the list of available Firebase services
   2. Select your project.
   3. (Optional) Use the existing firestore.rules and firestore.indexes.json files.

3. (Optional) Deploy the pre-configured rules and indexes:

   firebase deploy --only firestore

You should now be able to see the database in the Firebase console and use the store_view.dart.

Note

If you are getting errors on the setup, check the Troubleshooting section below.

The basics

To learn how to use Firestore, we recommend checking the official documentation, we will only cover ShipFlutter specifics here.

• Directorylib/modules/store

  • store.dart
  • store_service.dart
  • store_controller.dart
  • store_item.dart
  • store_view.dart
  • store_route.dart
  • json_converters.dart

The main class is FirebaseStore located in store.dart. Use this class to wrap a document or collection and retrieve data via its methods, and converting them to your data model.

FirebaseStore<StoreItem>(
    root: path,
    fromFirestore: (snapshot, options) {
        final data = snapshot.data()!;
        data["id"] = snapshot.id;
        return StoreItem.fromJson(data);
    },
    toFirestore: (value, options) {
        return value
            .copyWith(
                updatedAt: DateTime.now(),
            )
            .toJson()
            ..remove("id");
    },
);

The root is the path to the collection (e.g users or store/1234/purchases). The fromFirestore and toFirestore methods are used to convert the data from and to the database into the provided data model (StoreItem). It allows to add some custom logic to the conversion.

It offers methods to observer changes in the collections document or in a specific document. Additionally, you can use the get* methods to just get the data without observing.

The rest of the methods are self-explanatory and you can check the comments there.

Tip

You can see a full example on how to use this class in the store_service.dart.

Firestore Rules

The firestore.rules at the root of the project, defines the rules for the database. Those are really important to ensure the data is protected and only available to authorized users.

Note

You can find a list of all the rules in the official documentation

The tipical rules is to check if the user is authorized to allow access. In addition you can check if the request comes from a specific user or query collections in the databsase to enable more complex logic.

You can also modify the rules from the Firebase Dashboard but we highly recommend using the firestore.rules file.

To deploy the firestore.rules and firestore.indexes.json files, use:

firebase deploy --only firestore

Caution

When you deploy index or rules using the Firebase CLI, the rules defined in your project directory overwrite any existing rules in the Firebase console.

Firestore Indexes

The firestore.indexes.json file defines the indexes for the database. These indexes are requires to perform complex queries.

Note

You can find a list of all the rules in the official documentation

There are two main ways to create indexes:

1. Passive: whenever you perform a complex query that requires and index, the Firestore SDK will output a warning with a URL. Click on the URL to let the Dashboard create the index for you.

2. Active: modify the firestore.indexes.json file yourself adding the indexes you need and deploy them with firebase deploy --only firestore.

   Caution

   When you deploy index or rules using the Firebase CLI, the rules defined in your project directory overwrite any existing rules in the Firebase console.

Troubleshooting

There is an issue with Firestore for iOS that requires to add this lines in the Podfile

pod 'FirebaseFirestore',
    :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
    :tag => '10.29.0'

Whenever you update firebase dependency. You must update the tag here and run pod update from the app/ios folder.