| name | firebase-storage |
| description | Use when setting up Storage, uploading/downloading files, managing metadata, handling errors, or applying security rules. |
Firebase Cloud Storage Skill
This skill defines how to correctly use Firebase Cloud Storage in Flutter applications.
When to Use
Use this skill when:
- Setting up Cloud Storage in a Flutter project.
- Uploading or downloading files.
- Managing file metadata.
- Handling Storage errors and monitoring upload progress.
1. Setup and Configuration
flutter pub add firebase_storage
import 'package:firebase_storage/firebase_storage.dart';
final storage = FirebaseStorage.instance;
// Or specify a bucket explicitly:
// final storage = FirebaseStorage.instanceFor(bucket: "gs://BUCKET_NAME");
- Firebase Storage requires the Blaze (pay-as-you-go) plan.
- Run
flutterfire configure to update your Firebase config with the default Storage bucket name.
Security note: By default, a Cloud Storage bucket requires Firebase Authentication for any action. Configuring public access may also make App Engine files publicly accessible — restrict access again when you set up Authentication.
2. File Operations
Create a reference:
final storageRef = FirebaseStorage.instance.ref();
final fileRef = storageRef.child("uploads/file.jpg");
Upload:
final uploadTask = fileRef.putFile(file);
final snapshot = await uploadTask;
final downloadUrl = await snapshot.ref.getDownloadURL();
Download (in-memory):
final data = await fileRef.getData();
Download URL:
final downloadUrl = await fileRef.getDownloadURL();
Delete:
await fileRef.delete();
3. Metadata Management
Get metadata:
final metadata = await fileRef.getMetadata();
print('Content type: ${metadata.contentType}');
print('Size: ${metadata.size}');
Update metadata:
final newMetadata = SettableMetadata(
contentType: "image/jpeg",
customMetadata: {'uploaded_by': 'user123'},
);
await fileRef.updateMetadata(newMetadata);
Use custom metadata to store additional key/value pairs with your files.
4. Error Handling
Use try-catch with FirebaseException. Key error codes:
| Code | Meaning |
|---|
storage/object-not-found | File doesn't exist at the reference |
storage/bucket-not-found | No bucket configured for Cloud Storage |
storage/project-not-found | No project configured for Cloud Storage |
storage/quota-exceeded | Storage quota exceeded |
storage/unauthenticated | User needs to authenticate |
storage/unauthorized | User lacks permission |
storage/retry-limit-exceeded | Operation timeout exceeded |
- For
quota-exceeded on the Spark plan, upgrade to Blaze.
- Implement retry logic for network-related errors and timeouts.
5. Performance and Best Practices
Monitor upload progress:
final uploadTask = fileRef.putFile(file);
uploadTask.snapshotEvents.listen((TaskSnapshot snapshot) {
print('Progress: ${(snapshot.bytesTransferred / snapshot.totalBytes) * 100}%');
});
- Cancel uploads with
uploadTask.cancel().
- Pause / resume with
uploadTask.pause() and uploadTask.resume().
- Optimize file sizes before upload to reduce costs and improve performance.
- Use Cloud Storage with Firestore for comprehensive data management.
- Use the Firebase Local Emulator Suite for local development and testing.
6. Security
- Use Firebase Security Rules to control access to files.
- Combine Storage rules with Firebase Authentication for user-based access control.
- Test security rules thoroughly before deploying to production.
References
