You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+240Lines changed: 240 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,10 +33,250 @@ flutterfire --help
33
33
34
34
## Install
35
35
36
+
The general release is available for installation by running the following command:
37
+
36
38
```bash
37
39
dart pub global activate flutterfire_cli
38
40
```
39
41
42
+
We recommend installing the dev version which has been in use for some time, has become fairly stable and will soon be part of the general release:
43
+
44
+
```bash
45
+
dart pub global activate flutterfire_cli 0.3.0-dev.19 --overwrite
46
+
```
47
+
48
+
- FlutterFire CLI requires the Firebase CLI (`firebase-tools`) to be installed on your local machine, [follow these instructions](https://firebase.google.com/docs/cli) for installation.
49
+
- If you're running on a windows machine, we highly recommend you install via npm (i.e. `npm install -g firebase-tools`). The standalone
50
+
`firebase-tools` version can cause problems which you can read about [here](https://github.com/invertase/flutterfire_cli/issues/55#issuecomment-1316201478).
51
+
52
+
## Documentation for `v0.3.0-dev.19`
53
+
54
+
### Default setup
55
+
56
+
You may run the following command to configure your Flutter application with Firebase.
57
+
58
+
```bash
59
+
flutterfire configure
60
+
```
61
+
This method, at a minimum, will invoke two prompts of the user. A request to specify your Firebase project and
62
+
the platforms you wish to configure (i.e. android, iOS, macOS, web & windows).
63
+
64
+
If you don't want any prompts, you can use the following command:
FlutterFire CLI will auto detect the bundle ID for apple platforms via the `project.pbxproj` file, if there is no existing app associated with the bundle ID in your Firebase console, it will create one, and subsequently write the relevant `GoogleService-Info.plist` file to your project in the default location `ios/Runner/GoogleService-Info.plist` or `macos/Runner/GoogleService-Info.plist`. A similar process occurs on android, FlutterFire CLI uses the application ID in your `app/build.gradle` file and will generate a service file at the default location `android/app/google-services.json`.
71
+
72
+
Web is slightly different. It will create a web app in your Firebase console if one is not already present, otherwise, it will select the first one available from your Firebase console. If you prefer a specific web app, you can use the `--web-app-id` flag:
FlutterFire CLI now supports Windows applications. The Firebase console does not allow you to create an application for Windows, FlutterFire CLI will create a **web app** if you specify windows as a platform you want to configure:
- auto-detects the platforms from the project directory.
104
+
- prevents a prompt for rewriting the Dart Firebase configuration file (default name - `firebase_options.dart`) should you already have one in your project. It will auto rewrite the specific parts of your Firebase app configuration that you have requested (e.g. choosing `--platforms=web,android` will update web and android configurations in the `firebase_options.dart` file and leave the other app configurations within the file intact).
105
+
106
+
#### `--project` flag
107
+
- selects the Firebase project and negates the command prompt to choose which Firebase project you wish to use.
108
+
109
+
110
+
### Multi build configuration setup
111
+
112
+
**important**: You need to run `flutterfire configure` for every configuration type. E.g. if you have `Debug` & `Release` configurations, you need to run `flutterfire configure` twice with the relevant arguments documented below.
113
+
114
+
#### Android
115
+
116
+
[Android Firebase setup](https://firebase.google.com/docs/projects/multiprojects#support_multiple_environments_in_your_android_application) is fairly straight forward. It requires the application ID and the file path where you want to place your `google-services.json` file. Imagine you want to setup you Flutter project's android release build configuration with its own Firebase app. Here is how it would look:
As we are using the `google-services` gradle plugin to package the `google-services.json` file with your app, you can create as many build types & build flavors you require by following this documentation on [adding the JSON file](https://developers.google.com/android/guides/google-services-plugin#adding_the_json_file). It is simply a case of matching the correct application ID you've associated with a Firebase app in your Firebase console with the correct file path.
123
+
124
+
**important**: Use the '--android-package-name' flag otherwise the FlutterFire CLI will auto-detect from your `build.gradle` file.
125
+
126
+
#### Apple (iOS & macOS)
127
+
128
+
Apple has a couple of different options depending on your project setup. You can configure your Firebase app with Apple platform using either a target or build configuration.
129
+
130
+
**important**: Use the `--ios-bundle-id` and/or `--macos-bundle-id` flag otherwise the FlutterFire CLI will auto-detect from your `project.pbxproj` file.
131
+
132
+
##### build configuration
133
+
134
+
Most developers will likely configure with build configuration. As default, a Flutter app comes with three different build configurations: `Debug`, `Profile` & `Release` (**important**: FlutterFire CLI does not yet support renaming the target from `Runner` for **build configuration** which was a feature [released in Flutter 3.13.0](https://docs.flutter.dev/release/release-notes/release-notes-3.13.0)). Unlike android, it does not matter where you write the `GoogleService-Info.plist` file. Here is how to setup your Flutter Apple platform with build configuration:
A more advanced configuration for developers more experienced with Xcode development would be to utilize multiple targets for their Flutter Apple platform setup. By default, a Flutter app comes with only one target - `Runner`. You would have to set up multiple targets yourself for your different build variations. Once again, it does not matter where you write the `GoogleService-Info.plist` for target configuration. Let's imagine you have created a target for release and called it `ReleaseRunner`. Here is how to setup your Flutter Apple platform with target configuration:
Configuration for your Flutter web app occurs via the Dart Firebase configuration file. It is different in the sense that it requires the user to implement the relevant conditions (e.g, debug, release, etc) upon app start up to determine what type of build should use which Firebase app configuration. For example, if you wish to create a Firebase app for your production app, you might do the following:
**IMPORTANT**: The FlutterFire CLI will create only one Firebase web app. If you wish to create more (e.g. For different build environments), you will have to manually create a web app on the Firebase console, and use the Firebase web app ID created to associate with that build type (e.g. debug, release, etc).
169
+
170
+
In your application code, you might set it up as the following:
171
+
172
+
```dart
173
+
import 'package:flutter/foundation.dart' show kDebugMode;
174
+
// Assuming you've previously generated another `firebase_options.dart` file
175
+
import 'firebase_options.dart';
176
+
import 'firebase_release.dart' as firebase_release;
177
+
178
+
Future<void> main() async {
179
+
WidgetsFlutterBinding.ensureInitialized();
180
+
if (kDebugMode) {
181
+
await Firebase.initializeApp(
182
+
options: DefaultFirebaseOptions.currentPlatform,
183
+
);
184
+
} else {
185
+
// Use the Firebase app options from the generated `firebase_release.dart` file
A default Flutter app out of the box has three different build modes; debug, profile and release. If you wish, you can create a Firebase app for each one.
198
+
199
+
Imagine you want a debug Firebase app configured for iOS, macOS, android & web, you could run the following:
**Important things to note with multi-environment set up**
238
+
239
+
#### Android
240
+
- The android gradle plugin will try to match the path `google-services.json` to the correct build type. For instance, debug build will find the service file in the following locations: `android/app/src/debug/google-services.json` or `android/app/google-services.json`.
241
+
- Required to configure the application ID for release build in your android `build.gradle`. This might look like the following:
242
+
243
+
```gradle
244
+
buildTypes {
245
+
release {
246
+
signingConfig signingConfigs.debug
247
+
// This will effectively add the suffix to your applicationId. e.g. "com.example.myapp.release"
248
+
applicationIdSuffix ".release"
249
+
}
250
+
}
251
+
```
252
+
253
+
#### Apple
254
+
- Required to configure the bundle ID for release build configuration in Xcode for macOS & iOS under "Signings and Capabilities" tab. Below is an image of where you can update the release build configuration bundle ID:
- Required to manually create a Firebase web app for release and use the Firebase web App ID as an argument for `--web-app-id`.
259
+
- Required to implement your own logic for configuring build types for your Flutter web app as mentioned above.
260
+
261
+
If you require further granular builds i.e. build flavors, you can refer to [this article](https://codewithandrea.com/articles/flutter-flavors-for-firebase-apps/) which demonstrates how to configure different build flavors using [VGV CLI](https://github.com/VeryGoodOpenSource/very_good_cli) to create a Flutter app that has build flavors out of the box.
262
+
263
+
### Flutterfire reconfigure
264
+
265
+
There is another command that you might want to run each time you configure your project with another Firebase product. For example, if you configure Real time database for your Firebase project, you will be required to reinstall every service file for each platform. By running:
266
+
267
+
```bash
268
+
flutterfire reconfigure
269
+
```
270
+
271
+
It will rewrite all your service files in place and your Dart initialization file. It does this by using the `firebase.json` to track each of your configurations to update the service file at the correct location.
272
+
273
+
**important**: This command will also add the debug symbol upload script for Apple projects if you have updated your project to use Firebase Crashlytics. It will also update your `build.gradle` files as appropriate depending on what Firebase products your project requires (e.g. The command will write the required Firebase Performance and Crashlytics dependencies in your android `build.gradle` files if your Flutter project has `firebase_performance` & `firebase_crashlytics` dependencies).
274
+
275
+
### Caveats
276
+
- Use the Firebase service files for android (`google-services.json`), iOS & macOS (`GoogleService-Info.plist`). [See this comment](https://github.com/invertase/flutterfire_cli/issues/14#issuecomment-1270781026) for further information why we don't recommend Dart initialization for these platforms.
277
+
- Do not update your `Runner` target name for Apple platform when using `build configuration` set up. We do not currently support it.
278
+
- Apple configuration will only apply if you're configuring from a macOS environment. For example, configuring an iOS app on a Windows machine will not work.
0 commit comments