Firestorm for Dart & Flutter

An object-oriented data access API and ODM for Firebase's Firestore and Realtime Database

Firestorm for Flutter is a data access and ODM (Object-Document Mapping) tool for Firebase's Firestore and Realtime Database. It is designed to enable the rapid development of cross-platform Flutter applications using these two datastores, by providing a simple object-oriented API for interacting with data with minimal to no overheads.

Firestorm is designed to be used with Dart and Flutter, and is built on top of the official Firebase packages for Dart:

• firebase_core
• firebase_database
• cloud_firestore

The primary aim of Firestorm is to reduce development effort and time by providing an easy to use API for interacting with these datastores in an object-oriented way, and with minimal to no overheads in terms of performance or flexibility.

Developed by Dr Nicos Kasenides (developer alias RayLabz) at UCLan Cyprus.

Features

1. An easy-to-use data access API.
2. Object-oriented data access with support for custom classes and inheritance.
3. Built-in datastore type safety.
4. Automatic serialization and deserialization of data from/to objects.
5. Easy access to advanced features such as real-time updates, offline persistence, transactions, batch writes, and more.
6. Support for both Firestore and Real-Time Database.
7. Support for both plain Dart and Flutter projects.

Getting started

Installation

Install/import Firestorm by running the following commands in your project folder terminal:

Flutter projects:

flutter pub add firestorm

Plain Dart projects:

dart pub add firestorm

--- OR ---

By adding it to your pubspec.yaml file:

dependencies:
  firestorm: ^0.1.0

Getting started with Firestorm for Flutter

After importing Firestorm in your project, you can start using it by following these steps:

1. Configure the google-services.json file to your project.

   • For Android, place it in android/app/.
   • For iOS, place it in ios/Runner/.
   • For web, place it in web/.
   • For desktop, place it in linux/, macos/, or windows/ as appropriate.
   • For more information on how to generate this file, refer to the official Firebase documentation for Android, iOS, and Web.

2. Create your custom data classes

   • Follow the guide on how to define custom classes.

3. Run build_runner to perform checks and generate firestorm_models.dart:

   • For Flutter, run:

     flutter pub run build_runner build --delete-conflicting-outputs
     

   • For plain Dart, run:

     dart run build_runner build --delete-conflicting-outputs
     

     This will generate a file called firestorm_models.dart in the lib/generated/ directory of your project. This file contains the generated code for your custom classes and is required for Firestorm to work with them.

4. Initialize Firestorm in your application.

   • For Flutter, you can do this in the main() function:

     import 'package:firebase_core/firebase_core.dart';
     import 'package:firestorm/firestorm.dart';
     
     void main() async {
       WidgetsFlutterBinding.ensureInitialized(); //Ensures Flutter is initialized before Firebase
       await FS.init(); //Initialize Firestorm to use Firestore
       await RDB.init(); //Initialize Firestorm to use Realtime Database
       registerClasses(); //Registers custom classes. Imported from generated file [firestorm_models.dart].
            
       runApp(MyApp()); //Run your app normally here.
     }
     

   • For plain Dart, you can do this in the main() function:

     import 'package:firebase_core/firebase_core.dart';
     import 'package:firestorm/firestorm.dart';
     
     void main() async {
       await FS.init(); //Initialize Firestorm to use Firestore
       await RDB.init(); //Initialize Firestorm to use Realtime Database
       registerClasses(); //Registers custom classes. Imported from generated file [firestorm_models.dart].
            
       // Run your code here...
     }
     

5. Import the generated firestorm_models.dart file in your code (main.dart):
   • This file contains the generated code for your custom classes and is required for Firestorm to work with them.
   • You can import it like this:

     import '<your_project>/generated/firestorm_models.dart';
     

6. Start using Firestorm in your code
   • You can now start using Firestorm to interact with Firestore or Realtime Database.
   • For example, you can create, read, update, and delete documents in Firestore or Realtime Database using your custom classes.
   • For more information on how to use Firestorm, refer to the API Guide.

Summary

API Guide

For a detailed guide on how to use Firestorm, refer to the API Guide. The guide covers the following topics:

• How to create, read, update, and delete documents in Firestore and Realtime Database.
• How to use real-time updates with Firestorm.
• How to use transactions and batch writes for Firestore.
• How to use advanced features such as offline persistence, queries, and more.
• How to use Firestorm with custom classes and inheritance.

Feature support

Even though Firestorm provides a unified API for both Firestore and Realtime Database, it is important to note that the two databases have different capabilities and limitations. Firestorm aims to provide a consistent interface while respecting the unique features of each database.

• Firestore: A NoSQL document database that allows for complex queries, offline support, and real-time updates.
• Realtime Database: A cloud-hosted NoSQL database that provides real-time synchronization and is optimized for low-latency data access.

Platform support

Information

Requirements

• Dart 3.2 or higher

Known issues

No known issues.

Bug reports and feature requests

If you find a bug or have a feature request, please report it on our GitHub repository.

View the change log for the latest updates and changes to Firestorm.

License

Firestorm is open-source and is released under the Apache 2.0 License. See the LICENSE file for more information.