firebase-cloud-functions

# Firebase Cloud Functions Skill

This skill defines how to correctly call Firebase Cloud Functions from Flutter applications.

## When to Use

Use this skill when:

* Setting up and configuring Cloud Functions in a Flutter project.
* Calling callable functions and handling their results.
* Handling errors from function calls.
* Optimizing function call performance.
* Testing with the Firebase Emulator Suite.

---

## 1. Setup and Configuration

```
flutter pub add cloud_functions
```

```dart
import 'package:cloud_functions/cloud_functions.dart';

// After Firebase.initializeApp():
final functions = FirebaseFunctions.instance;
```

- Initialize Firebase before using any Cloud Functions features.
- For region-specific deployments, specify the region when getting the instance.
- Deploy callable functions to Firebase **before** attempting to call them from your Flutter app.
- Consider implementing **App Check** to prevent abuse of your Cloud Functions.

---

## 2. Calling Functions

Use `httpsCallable` to reference a function, then `call` to invoke it:

```dart
final result = await FirebaseFunctions.instance
  .httpsCallable('functionName')
  .call(data);
```

- Pass data as a `Map` — it is automatically serialized to JSON:

```dart
final result = await FirebaseFunctions.instance
  .httpsCallable('addMessage')
  .call({
    "text": messageText,
    "push": true,
  });
```

- Access the result via the `data` property — it is automatically deserialized from JSON:

```dart
final responseData = result.data;
// Cast to expected type if needed:
final responseString = result.data as String;
```

- **Do not** pass authentication tokens in function parameters — they are automatically included by the SDK.
- Keep function names consistent between client code and server-side implementations.

---

## 3. Error Handling

Always wrap function calls in `try-catch` and check for `FirebaseFunctionsException`:

```dart
try {
  final result = await FirebaseFunctions.instance
    .httpsCallable('functionName')
    .call(data);
  // Handle successful result
} catch (e) {
  if (e is FirebaseFunctionsException) {
    print('Error code: ${e.code}');
    print('Error message: ${e.message}');
    print('Error details: ${e.details}');
  } else {
    print('Error: $e');
  }
}
```

- Handle network connectivity issues and timeouts appropriately.
- Provide meaningful error messages to users when function calls fail.
- Consider implementing retry logic for transient errors.

---

## 4. Performance Optimization

Set a timeout appropriate to the expected execution time:

```dart
final callable = FirebaseFunctions.instance.httpsCallable(
  'functionName',
  options: HttpsCallableOptions(
    timeout: const Duration(seconds: 30),
  ),
);
```

- Minimize the amount of data passed to and from functions to reduce latency.
- Use batch operations when possible to reduce the number of function calls.
- Consider client-side caching for frequently used function results.
- Monitor function performance in the Firebase Console to identify bottlenecks.
- Account for **cold starts** for infrequently used functions.
- Implement proper loading states in the UI while waiting for function responses.

---

## 5. Testing and Development

Use the Firebase Emulator Suite for local development and testing:

```dart
FirebaseFunctions.instance.useFunctionsEmulator('localhost', 5001);
```

- Test functions with both valid and invalid inputs to ensure proper validation.
- Verify that functions handle authentication correctly.
- Test with different user roles and permissions to ensure proper access control.
- Implement unit tests for client-side function calling logic.
- Use integration tests to verify end-to-end function behavior.

---

## References

- [Cloud Functions for Firebase Flutter documentation](https://firebase.google.com/docs/functions/callable?platform=flutter)
- [Firebase Emulator Suite](https://firebase.google.com/docs/emulator-suite)