Cloud Firestore ODM Package for Flutter

The Cloud Firestore ODM package enables developers to build fully type-safe applications for Flutter using the FlutterFire Cloud Firestore plugin.

The Cloud Firestore ODM is currently in alpha. Expect breaking changes, API changes and more. The documentation is still a work in progress. See the discussion for more details.

What is an ODM?

The Object Document Mapper or ODM is an interface that treats a document as a tree structure wherein each node is an object representing a part of the document.
ODM methods allow programmatic access to the tree making it possible to change the structure, style or content of a document.

What does it do?

The Cloud Firestore ODM package enables developers to build fully type-safe applications for Flutter using the FlutterFire Cloud Firestore plugin.

The ODM allows data schemas to be defined which represent the data structure of your Cloud Firestore database. By defining schemas the ODM provides the following benefits:

• ↔️ Bi-directional data validation.
• 🔒 Type-safe data querying, supporting all Firestore query operations.
• 🔄 Flutter Widgets for simple data binding with your data.
• 🎯 Data selectors to help avoid unnecessary Widget rebuilds.
• 💻 Full API code completion.

Installation

1. Use a recent Dart version

The ODM relies on a recent Dart feature: generic annotations.
As such, to use the ODM you will need to upgrade your Dart SDK to enable this feature.

That is done by adding the following to your pubspec.yaml:

environment:
  sdk: ">=2.18.0 <4.0.0"

2. FlutterFire Initialization

Before getting started, Add Firebase to your Flutter app.

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(MyApp());
}

3. Install cloud_firestore plugin

The ODM depends on the cloud_firestore plugin, so first ensure you have it installed on your project.

4. Install dependency

To install the ODM, you'll need to install both the cloud_firestore_odm and json_annotation packages from pub:

flutter pub add cloud_firestore_odm
flutter pub add json_annotation

Next, install the build_runner, cloud_firestore_odm_generator & json_serializable packages as development dependencies:

flutter pub add --dev build_runner
flutter pub add --dev cloud_firestore_odm_generator
flutter pub add --dev json_serializable

5. Enable create_field_map and create_per_field_to_json of json_serializable

For the ODM to work, it is necessary to enable the create_field_map and create_per_field_to_json of json_serializable.
This can be done by creating a build.yaml file next to your pubspec.yaml and paste the following:

targets:
  $default:
    builders:
      json_serializable:
        options:
          create_field_map: true
          create_per_field_to_json: true

This will enable create_field_map and create_per_field_to_json for the entire project.

Alternatively, you can enable the option on a per-model basis using json_annotation's @JsonSerializable object:

@JsonSerializable(createFieldMap: true, createPerFieldToJson: true)
@Collection<Model>(...)
class MyModel {...}

Next Steps

Once installed, read the documentation on defining models.

Issues and feedback

Please file FlutterFire specific issues, bugs, or feature requests in our issue tracker.

Plugin issues that are not specific to FlutterFire can be filed in the Flutter issue tracker.

To contribute a change to this plugin, please review our contribution guide and open a pull request.