Skip to content

docs: update documentation to support latest CLI release. #8448

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Parent: fix(cloud_firestore): properly export pigeon message file from interface
merged 4 commits into from
Apr 13, 2022
Merged

docs: update documentation to support latest CLI release. #8448

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
debc15c
docs: update flutterfire cli info
russellwheatley Apr 12, 2022
5fbdcf7
Update docs/cli.mdx
Salakar Apr 13, 2022
eeaef40
updates for new cli release
Salakar Apr 13, 2022
830a0fe
-
Salakar Apr 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 25 additions & 32 deletions docs/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ of FlutterFire across all supported platforms.
## Installation

The FlutterFire CLI depends on the underlying [Firebase CLI](https://firebase.google.com/docs/cli). If you haven't already done so, make sure you have the Firebase CLI installed on your machine.
If not, make sure you have [node.js](https://www.nodejs.org/) on your machine and Install the Firebase CLI via npm by running the following command :
If not, make sure you have [node.js](https://www.nodejs.org/) on your machine and Install the Firebase CLI via npm by running the following command:

```bash
npm install -g firebase-tools
Expand All @@ -27,32 +27,11 @@ Once installed, the `flutterfire` command will be globally available.
## Usage

:::note
Some plugins do not fully support Dart-only Firebase initialization, if you need to use these plugins then the [manual installation](./manual-installation.mdx) steps are recommended.
:::

The following table shows the current plugins with Dart-only Firebase initialization issues (**_plugins not shown here are fully supported_**):

| Plugin | iOS | Android | Web | macOS |
| ---------------------: | :-------------------------------------------------------------: | :-------------------------------------------------------------: | :-: | :-------------------------------------------------------------: |
| Analytics | ✔ | **?** | ✔ | ✔ |
| Crashlytics | [**?**](./crashlytics/overview#2-optional-platform-integration) | [**?**](./crashlytics/overview#2-optional-platform-integration) | N/A | [**?**](./crashlytics/overview#2-optional-platform-integration) |
| Performance Monitoring | ✔ | ❌ | ✔ | N/A |

- **?** Indicates your app will build and run but plugin behavior may be different.
- ❌ Indicates your app will crash on startup without manual Google services PLIST/JSON file setup.
- ✔ Indicates no known issues.

Additionally, if you use the [`google_sign_in` provider](./auth/social#google) for Authentication in `firebase_auth` then this also requires [manual installation](./manual-installation.mdx). There is an open issue to move `google_sign_in` to Dart initialization which you can [track here](https://github.com/flutter/flutter/issues/96391).

### Generating Firebase Options

:::note
If you initialize your Firebase app from Dart, you will likely receive warnings from the native Android & iOS Firebase SDKs indicating no Firebase app has been configured or
you don't have the relevant config file (i.e. `GoogleService-Info.plist` or `google-services.json`). You can safely ignore these warnings if
If you initialize your Firebase app from Dart, you may receive warning logs from the native iOS Firebase SDK indicating no Firebase app has been configured (i.e. `GoogleService-Info.plist`). You can safely ignore these logs if
you're initializing your Firebase app from Dart.
:::

FlutterFire can now be initialized from Dart on all platforms using `Firebase.initializeApp`, however
FlutterFire can be initialized from Dart on all platforms using `Firebase.initializeApp`, however
the options for different platforms can vary. The FlutterFire CLI can help, by generating a file
(by default called `firebase_options.dart`) which can be used when calling the initialization method.

Expand Down Expand Up @@ -88,6 +67,10 @@ await Firebase.initializeApp(
);
```

:::note
If you add support for a new platform in your Flutter app (e.g. adding Android when your app previously did not support Android), or if you introduce new Firebase services into your app (e.g. adding `firebase_database`) then you should reconfigure Firebase for your application again via the CLI (`flutterfire configure`).
:::

## Commands

### Configure
Expand All @@ -101,14 +84,15 @@ flutterfire configure

The command supports the following option arguments:

| Argument | Alias | Description |
| ----------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --project | -p | Sets the Firebase Project ID to use. By default, the CLI will attempt to fetch the project defined in the `.firebaserc` file, or prompt you to select the project from the Firebase Console. |
| --account | -e | Sets the email address which should be used to authenticate with Firebase against. By default, this will use the primary account defined on the Firebase CLI. |
| --out | -o | Specifies the path & file name for the generated file. Defaults to "lib/firebase_options.dart". |
| --ios-bundle-id | -i | The bundle identifier of your iOS app, e.g. "com.example.app". If no identifier is provided then an attempt will be made to automatically detect it from your "ios" folder (if it exists). |
| --macos-bundle-id | -m | The bundle identifier of your macOS app, e.g. "com.example.app". If no identifier is provided then an attempt will be made to automatically detect it from your "macos" folder (if it exists). |
| --android-app-id | -a | The application id of your Android app, e.g. "com.example.app". If no identifier is provided then an attempt will be made to automatically detect it from your "android" folder (if it exists). |
| Argument | Alias | Description |
| -------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --project | -p | Sets the Firebase Project ID to use. By default, the CLI will attempt to fetch the project defined in the `.firebaserc` file, or prompt you to select the project from the Firebase Console. |
| --account | -e | Sets the email address which should be used to authenticate with Firebase against. By default, this will use the primary account defined on the Firebase CLI. |
| --out | -o | Specifies the path & file name for the generated file. Defaults to "lib/firebase_options.dart". |
| --ios-bundle-id | -i | The bundle identifier of your iOS app, e.g. "com.example.app". If no identifier is provided, an attempt will be made to automatically detect it from your "ios" folder (if it exists). |
| --macos-bundle-id | -m | The bundle identifier of your macOS app, e.g. "com.example.app". If no identifier is provided, an attempt will be made to automatically detect it from your "macos" folder (if it exists). |
| --android-package-name | -a | The package name of your Android app, e.g. "com.example.app". If no package name is provided, an attempt will be made to automatically detect it from your "android" folder (if it exists). |
| --[no-]apply-gradle-plugin | -g | Whether to add the Firebase Gradle plugin to your Android app's build.gradle files and create the google-services.json file in your ./android/app folder. (defaults to on) |

## Version

Expand All @@ -118,6 +102,15 @@ To view the current version of the FlutterFire CLI, run:
flutterfire --version
```

### Updating the CLI

If your CLI version is no longer the latest published version then you will be prompted to automatically update your CLI to the latest version when you run `flutterfire --version`. Alternatively
you can manually trigger an update via the following command:

```bash
dart pub global activate flutterfire_cli
```

## Reporting an issue

If you have encountered any issues with the CLI, please report them
Expand Down
27 changes: 5 additions & 22 deletions docs/crashlytics/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,19 +23,16 @@ On the root of your Flutter project, run the following command to install the pl
flutter pub add firebase_crashlytics
```

### 2. (optional) Platform integration
### 2. (optional) Platform integration for Android

Dart-only Firebase initialization currently only supports reporting Dart exceptions. To report native Android & iOS exception
please follow the Android platform Setup section from the [manual installation guide](../manual-installation.mdx) and the steps below.
Dart-only Firebase initialization for Android currently only supports reporting Dart exceptions. To report native Android exceptions,
please follow the steps below.

#### a. Android

1. Add the following classpaths to your `android/build.gradle` file.
1. Add the following classpath to your `android/build.gradle` file.

```groovy {4} title="android/build.gradle"
dependencies {
// ... other dependencies
classpath 'com.google.gms:google-services:4.3.5'
// ... other dependencies such as 'com.google.gms:google-services'
classpath 'com.google.firebase:firebase-crashlytics-gradle:2.7.1'
}
```
Expand All @@ -54,23 +51,9 @@ dependencies {
}

// This must appear at the bottom of the file
apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.google.firebase.crashlytics'
```

#### b. iOS

1. From Xcode, select Runner from the project navigation.
2. Select the Build Phases tab, then click + > New Run Script Phase.
3. Add the following to the Type a script... text box underneath the Shell property:

```bash
$PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase --validate -ai <googleAppId>
$PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase -ai <googleAppId>
```

Retrieve your `<googleAppId>` from your generated `DefaultFirebaseOptions` file (`appId`) or from the Firebase Console -> Project Settings -> Your apps.

### 3. Rebuild your app

Once complete, rebuild your Flutter application:
Expand Down
23 changes: 10 additions & 13 deletions docs/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,18 +61,11 @@ Before any of the Firebase services can be used, FlutterFire needs to be initial
FlutterFire "bootstrapping" itself). The initialization step is asynchronous, meaning you'll need to prevent any FlutterFire
related usage until the initialization is completed.

:::tip

If you're using FlutterFire in an existing application, you can use Dart-only initialization for most plugins.
However, there are plugins that still require [manual-installation](./manual-installation.mdx) (i.e. using `google-services.json` or `GoogleService-Info.plist` files).
Please see this [usage guide](./cli.mdx#usage) to learn what plugins need manual installation.
:::

### Using the FlutterFire CLI

:::info

The FlutterFire CLI depends on the [Firebase CLI](https://firebase.google.com/docs/cli). If you haven't installed it yet, you can learn more about Firebase CLI in the [documentation](https://firebase.google.com/docs/cli).
The FlutterFire CLI depends on the [Firebase CLI](https://firebase.google.com/docs/cli). If you haven't installed it yet, you can learn more about Firebase CLI in the [documentation](https://firebase.google.com/docs/cli).

:::

Expand All @@ -88,10 +81,14 @@ flutterfire configure
```

Once configured, a `firebase_options.dart` file will be generated for you containing all the options
required for initialization.
required for initialization. Additionally, if your Flutter app supports Android then the [Android Google Services Gradle plugin](https://firebase.google.com/docs/android/setup#add-config-file) will automatically be applied for you.

**Learn more about the FlutterFire CLI in the [documentation](./cli.mdx)**.

:::note
If you add support for a new platform in your Flutter app (e.g. adding Android when your app previously did not support Android), or if you introduce new Firebase services into your app (e.g. adding `firebase_database`) then you should reconfigure Firebase for your application again via the CLI (`flutterfire configure`).
:::

### Initialization

Next the generated options need to be provided to the [`initializeApp`](!firebase_core.Firebase.initializeApp) method.
Expand All @@ -117,9 +114,9 @@ void main() async {
}
```

The `DefaultFirebaseOptions.currentPlatform` are imported from our generated `firebase_options.dart` file.
The `DefaultFirebaseOptions.currentPlatform` is imported from our generated `firebase_options.dart` file.

Once initialized, you're ready to get started using FlutterFire!
Once initialized, you're ready to start using FlutterFire!

## Manual Installation

Expand All @@ -129,7 +126,7 @@ required. If you wish to view the documentation for manual initialization, view

## Next Steps

On its own the [`firebase_core`](!firebase_core) plugin provides basic functionality for usage with Firebase. FlutterFire is broken down
into several individual installable plugins that allow you to integrate with a specific Firebase service.
On its own, the [`firebase_core`](!firebase_core) plugin provides basic functionality for usage with Firebase. FlutterFire is broken down
into individual, installable plugins that allow you to integrate with a specific Firebase service.

See the documentation for each plugin to learn more about them.