Cloud Firestore

ShipFlutter uses Cloud Firestore as its database solution, providing a flexible, scalable NoSQL cloud database with offline support. The database module is part of the core Firebase integration, making it seamless to work with user data, settings, and app state.

Before starting, make sure you have completed the Firebase setup, including the Firestore setup steps.

Using FirebaseStore

The database functionality is implemented in the core/firebase/database module, providing a type-safe wrapper around Firestore operations through the FirebaseStore class:

final store = FirebaseStore<User>(
    root: "users",
    fromFirestore: (snapshot, options) {
        final data = snapshot.data()!;
        // You can add additional fields here if needed
        data["id"] = snapshot.id;
        return User.fromJson(data);
    },
    toFirestore: (value, options) => value.toJson(),
);

Configuration

1. root: The path to your collection (e.g., users or store/1234/purchases)
2. fromFirestore: Convert Firestore data to your model
3. toFirestore: Convert your model to Firestore data

Key Features

Observe Data

// Observe collection with filters
store.observeItems(
  filters: (query) => query.where('field', isEqualTo: 'value'),
  onlyChanges: true, // Skip initial cache data
).listen((items) {
  // Handle items
});

// Observe single document
store.observeItem('documentId').listen((item) {
  // Handle item updates
});

Read Data

// Get collection
final items = await store.getItems();

// Get single document
final item = await store.getItem('documentId');

// Check if document exists
final exists = await store.exists('documentId');

Write Data

// Create with auto-generated ID
final id = await store.createItem(newItem);

// Transform before creating
final id = await store.createItem(
  newItem,
  transform: (id) => newItem.copyWith(id: id),
);

// Create with custom ID
await store.createItem(newItem, id: 'custom-id');

// Update
await store.updateItem(
  id: 'documentId',
  item: updatedItem,
  merge: true,
);

// Update specific fields
await store.setItemFields(
  id: 'documentId',
  fields: {'status': 'active'},
);

// Delete
await store.deleteItem('documentId');

Batch Operations

await store.batch((collection, batch) {
  // Perform multiple operations atomically
  batch.set(...);
  batch.update(...);
  batch.delete(...);
});

Tip

The database module is already integrated with other core features like authentication and account management. Check the Account documentation for more details.

Security Rules

The firestore.rules file at the root of your project defines access control:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

Note

Check the official documentation for more complex security rules.

Best Practices

1. Data Structure

   • Keep documents small and flat
   • Use subcollections for scalable relationships
   • Follow the Firebase recommendations

2. Queries

   • Create indexes for complex queries
   • Use filters efficiently
   • Limit result size when possible
   • Cache frequently accessed data

3. Offline Support

   • Enable persistence for offline access
   • Handle offline/online state changes
   • Use onlyChanges parameter to skip cached data
   • Implement retry logic for failed operations

Troubleshooting

Here are some common issues you might encounter:

Tip

If you’re experiencing other issues, check the Firebase Flutter documentation or let us know.

iOS performance issues

For better performance on iOS, we use a pre-compiled version of Firestore by adding these lines to the Podfile:

target 'Runner' do
  # Other podfile lines...

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

  # Other podfile lines...
end

Caution

Make sure the Firestore version in your Podfile is compatible with the one in pubspec.yaml.

iOS build issues

Add these lines if you encounter iOS build issues:

target.build_configurations.each do |config|
  config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
  config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'i386'
end