first_app: Starter app for a Flutter production app

Maintainer: Greger Wedel, https://github.com/gregertw

Listed on:

Latest build and artifacts:

Latest update: Support for Flutter 3.29.2

There are lots of simple Flutter app examples out there, but very few show how to tie together the elements you need to put an app into production. In my process of evaluating Flutter maturity and readiness for production apps, I started to put together the various elements into a single app. It evolved over time to a starter app (and template on Github) that has been updated and following best practices and sound engineering practices.

The focus of this starter app is thus not on the UI or functionality, but rather to show how a set of typical app functionalities can be developed and supported in a sound code structure. The app structure has also been designed to support a development team through separation of concerns and sound abstractions, as well as support for all layers of testing (unit, widget, and integration).

This app has the following elements:

• Support for iOS, Android, and web
• Separation of business logic in models and providers, and UI in a separate folder structure
• Use of provider for app state management
• Authentication and authorization using OAuth2
• State management of login and login token including permanent storage for restarts
• Simple widget framework for handling logged-in, expired, and logged-out states
• Basic UI with sliding drawer menu and menu options
• Testing using unit test framework and mocking
• Integration tests
• Localization using i18n and the built-in Flutter support for generating boilerplate
• Use of a global UI theme
• Custom icons for both iOS and Android
• Use of Firebase Analytics for usage tracking
• Use of Firebase Crashlytics for crash reporting
• Use of Firebase Cloud Messaging for push notifications
• Use of a OS native capability (location tracking) using a published plugin (geolocator)
• Use of Google Maps to present a map of the current location
• Use of an independently defined new widget type called AnchoredOverlay to overlay a map widget

Here is a blog post about the value of using a starter app: https://stuff.greger.io/2021/08/why-and-how-you-should-use-a-flutter-starter-app.html

Also, see my blog post for a more detailed introduction to the various features: https://stuff.greger.io/2019/07/production-quality-flutter-starter-app.html.

Known issues

• firebase_crashlytics does not support web

Suggested improvements

I'm happy to accept pull requests for any improvements that will make this starter app even more complete from a production app point of view. Here are some possible improvements:

• How to use Oauth2 to grant access to a service like Firebase database (very close now with Google login)
• How to do A/B testing
• How to use deep links
• ...

CHANGELOG

See CHANGELOG.md

QUICKSTART

The easiest way to get started with this app is to get it running in your own browser locally. To do that, you need to configure a Google OAuth2 application at https://console.cloud.google.com/apis/credentials. You need to define your own application so you can use Google to log in, and you need to make sure that the app knows about the URL it is running from (i.e. localhost:port), so that it can present the URL to Google and the Google app is configured with the same URL as an allowed redirect URL. In addition, the app needs to present the secret for the Google app you have configured. If there is a mismatch in the URL your app is running under, what is configured in the app, and what is configured for the Google app, the login process will fail.

Here are the steps:

• Go to Google console as above and create a new OAuth client ID. Choose Web Application as type.
• Add an Authorized redirect URI to http://localhost:50000/
• Copy the client id and update clientIdGoogleApp in lib/environment.dart
• Copy the client secret and secretGoogleWebin the same file
• Start debugging with: flutter run --debug --web-port=50000 (this will allow the app to present the right redirect URL)

In Visual Studio Code, you can add an entry to launch.json in .vscode:

{
            "name": "Flutter: Debug web",
            "type": "dart",
            "request": "launch",
            "args": [
                "--web-port=50000"
            ],
            "flutterMode": "debug",
            "program": "lib/main.dart"
        },

How to get started

The app uses a Google Firebase project (though this is not a requirement if you drop analytics, messaging, and crashlytics). The currently configured test project is available for your testing, but obviously you will not be able to log into these projects, so the value of that is just that you can test the app without doing any code changes. To start tinkering, you will want to create your own Firebase project.

But, first of all, check out the actingweb_firstapp code base (it's a template!). You can use any editor.

Make sure you have available a device to run the app on, either a physical device or an emulator, then just run it on an emulator. You should be able to log into the app with your Google account (only on emulator, not web, see later). Github is not supported for web, and requires a secret that Google does not require, so it will not work until you register your own Github OAuth2 client.

lib/environment.dart contains the client values for Github and Google, here you can add your own client id and secrets when you register your app for authentication with each of these.

See further below for introductions on specific areas of the app's functionality.

Steps to make this your own app

Even if this app comes out of the box functionally working, you need to make it your own to build on it. As a minimum, you need to do the following:

• Replace io.actingweb.firstapp with your own URI scheme/bundle id in android/, ios/, and lib/
• Replace firebase_options.dart with configurations for your own Firebase project, see https://firebase.flutter.dev/docs/overview/
• Edit lib/environment.dart with your own Google and Github client ids (or supply them in env variables)
• Supply environment variables for the secrets in environment.dart. In Visual Studio Code, you can edit your launch.json and add the "env": {} section
• You need to edit android/app/src/main/AndroidManifest.xml and ios/Runner/AppDelegate.swift to update your API key for Google Maps (see https://cloud.google.com/maps-platform/)

That's all you need! The below sections give you more details on how each of the services have been integrated in the code base.

Integration pattern with various services

There are two integration needs in a Flutter app: integrate towards the underlying platform and integrating towards the various external services you may want to use. Examples of the first is location, mobile messaging services (which has support built into the iOS and Android platforms), persistence of data (i.e. shared_preferences), and registration of URI schemes for your application, so that your application can receive the authentication code necessary as part of authentication. The second category is how to use Google Firebase services (analytics, messaging, and crash reports), authentication using OAuth2 towards e.g. Github and Google, or Google Maps to show the map of where you are.

The most difficult is typically the integration towards the underlying platforms, but as Flutter has evolved with support for web and matured on iOS and Android, more and more of integration necessary can be done in the Dart code and the platform specific configuration has been reduced.

But still, you will need API keys or client ids or URLs for where to connect, and this must be configured somewhere. In /lib/environment.dart you will find a class that pickes configuration variables from the environment (which can be set in your CI/CD pipeline) and where you can set defaults. However, these can only be used in the Dart code, so where there are needs for underlying platform integration (in ios, android, and web directories), you will have to go in and edit the code and configs there directly. How is documented in the sections below.

Support for Web

NOTE!! This is only for the web version of the app

To build the web version, use flutter build web --base-href="/<some_path>/" or use just /if you deploy to the root of the domain. The web app should be deployed to https://my.domain.com/some_path/.

As of Flutter 2, web is supported on stable release, https://flutter.dev/web and a web version of app is available at https://gregertw.github.io/actingweb_firstapp_web. The support for packagaes has increased, and most of the functionality is now supported in the web version.

See https://flutter.dev/docs/get-started/web. If you get errors, do flutter clean.

Firebase has now better web support as well, but there are two areas where you need to configure in the web/ folder: for Firebase messaging to work and for Google Maps.

For Google Maps, see https://pub.dev/packages/google_maps_flutter_web. You need an API key and add a script to index.html.

Your Firebase project (google.com) must be configured with a web app (under General settings). The config script snippet you get from setting up the web must replace the Firebase app config in web/firebase-messaging-sw.js:

  var firebaseConfig = {
    apiKey: "AIzaSyDjVjlcUKYUBb62x4K8WUGI47mXXlfKTtI",
    authDomain: "actingweb-firstapp.firebaseapp.com",
    databaseURL: "https://actingweb-firstapp.firebaseio.com",
    projectId: "actingweb-firstapp",
    storageBucket: "actingweb-firstapp.appspot.com",
    messagingSenderId: "748007732162",
    appId: "1:748007732162:web:ff42373829ce3137785c5b",
    measurementId: "G-M7F2YR6FNW"
  };

If you have used the Firebase CLI tool to create a firebase_options.dart, you will find your Firebase web API key in apiKey attribute. Add it also in lib/environment.dart (you don't need manual configuration in index.html anymore). This is according to the documentation as it should be used in the getToken() method.

You can find all the details at https://firebase.flutter.dev/docs/messaging/overview, and you can find more details on Firebase and messaging below.

The kIsWeb global variable is used to detect if the app is running on web and made available in appstate.dart as a isWeb bool that can be used across the app. The variable is also used in appstate.dart to do the correct Firebase Messaging initialisation.

If you are doing debugging of the app on web, use Google login, you need to edit environment.dart with the client id and secret, and then (for local debugging) edit auth.dart and oauth.js with the localhost redirect URL with port number. In addition, the Google web app (credentials) also need the http://localhost:<portnumber>/ configured as a legal redirect URL. Configure Google web app at https://console.cloud.google.com/apis/credentials.

Note on Github! Github only supports clientid and secret, and does explicitly not support retrieving an access token from a web applications (it is blocked with no CORS headers). This is because it is not considered safe. This means that Github auth is disabled on web.

Authentication and Authorization

Evolution of auth in first_app

The authentication in first_app has been refactored three times. This last time, a package called oauth2_client has been used as it has support for iOS, Android, and web. Previously, flutter_appauth was used, but the mai