Flutter Template

A Flutter template application showcasing - Clean architecture, Responsive design, State management, Decoupled widgets using the connector pattern, Dependency Injection, Widget and Unit testing, Navigation, Localization, Material 3 dynamic theming, Continuous Integration and Continuous Deployment.

Expert teams of digital product strategists, developers, and designers.

We’re always looking for people who value their work, so come and join us. We are hiring!

Check out the multi-package branch for a multi package flutter architecture.

Getting Started

Clone the repo and follow these steps to setup the project.

App Secrets

Sensitive information like api keys, credentials, etc should not be checked into git repos, especially public ones. To keep such data safe the template uses app_secrets.dart file. If you want to run the app locally, you will need to create a new file app_secrets.dart under lib/secrets. To help with setting up the secrets file, the template inclued a skeleton secrets file. Copy all the content from app_secrets.skeleton.dart to the app_secrets.dart file you just created. Uncomment the code and replace the the placeholders with your secret data.

You can get your Open Weather API key from here.

Get Dependencies

flutter pub get

Run Code Generation

bash scripts/generate-all.sh

Read the scripts documentation to learn about all the scrips used in the project.

Architecture

The architecture of the template facilitates separation of concerns and avoids tight coupling between it's various layers. The goal is to have the ability to make changes to individual layers without affecting the entire app. This architecture is an adaptation of concepts from The Clean Architecture.

Layers

The architecture is separated into the following layers

lib/presentation: All UI and state management elements like widgets, pages and view models.
lib/navigation: navigators to navigate between destinations.
lib/interactor: provides feature specific functionality.
lib/domain: use cases for individual pieces of work.
lib/repository: repositories to manage various data sources.
lib/services: services provide access to external elements such as databases, apis, etc.

Each layer has a di directory to manage Dependency Injection for that layer.

Entities

The layers presentation, domain and services each have an entity directory.

lib/presentation/entity: Classes that model the visual elements used by the widgets.
lib/domain/entity: Model classes for performing business logic manipulations. They act as an abstraction to hide the local and remote data models.
lib/services/entity: Contains local models (data classes for the database) and remote models (data classes for the api).

Entity Naming Convention

Presentation entities are prefixed with UI (eg: UICity).
Domain entities do not have any prefix. (eg: City).
Service entities are of 2 types:
- Local / Database entities are prefixed with Local (eg: LocalCity).
- Remote / API entities are prefixed with Remote (eg: RemoteCity).

Other Directories

Apart from the main layers, the template has

lib/foundation: Extensions on primitive data types, loggers, global type alias etc.
lib/flavors: Flavor i.e. Environment related classes.
lib/entrypoints: Target files for flutter to run for each flavor.
lib/app.dart: App initialization code.

Understanding the Presentation Layer

The presentation layer houses all the visual components and state management logic.

The base directory has all the reusable and common elements used as building blocks for the UI like common widgets, app theme data, exceptions, base view models etc.

View Model

State Management is done using the riverpod along with state_notifier. The class that manages state is called the View Model.

Each View Model is a subclass of the BaseViewModel. The BaseViewModel is a StateNotifier of ScreenState. Along with the ScreenState it also exposes a stream of Effect.

Implementations of the BaseViewModel can also choose to handle Intents.

Screen State

ScreenState encapsulates all the state required by a Page. State is any data that represents the current situation of a Page.

For example, the HomeScreenState holds the state required by the HomePage.

Effect

Effects are events that take place on a page that are not part of the state of the screen. These usually deal with UI elements that are not part of the widget tree.

Showing a snackbar or hiding the keyboard are examples of an effect.

Intent

Intent is any action that takes place on a page. It may or may not be user initiated.

SearchScreenIntent has the actions that can happen on the SearchPage.

Page

A page is a widget that the navigator can navigate to. It should return the BasePage widget.

The BasePage creates the structure for the page, initialises the ViewModel and provides the view model in the widget tree so that all the children have access to it. It also listens to the effects from the view model and notifies the page about it.

Each page accepts the Screen object as input.

Widgets

Each destination has a widgets directory. It holds all the widgets that appear on a Page excluding the page itself.

Each widget the requires access to data from the view model it split into two dart files. The connector widget communicates with the view model, and the content widget has the actual UI. The connector widget passes all the required data to the content widget. Thus the content widget never depends on the state managent solution used. This helps in easy replacement of state management solution if needed and also makes it easier to test widgets.

Screen

A Screen is a class that represents a Page in the context of navigation. It holds the path used by the navigator to navigate to a Page and also holds any arguments required to navigate to that Page.

Flavors

The template comes with built-in support for 3 flavors. Each flavor uses a different main.dart file.

You can setup any environment specific values in the respective main.dart files.

To run a specific flavor you need to specify the flavor and target file.

 flutter run --flavor qa -t lib/entrypoints/main_qa.dart

To avoid specifying all the flags every time, use the run.sh script

Read the scripts documentation to learn about all the scrips used in the project.

Content

The Flutter Template contains:

A Flutter application.
Built-in support for 3 flavors - dev, qa and prod.
A reactive base architecture for your application.
Riverpod along with state_notifier for state management.
Drift as local database for storage.
Dio for making API calls.
Freezed for data class functionality.
Get It for dependency injection.
Flutter Lints for linting.

The template contains an example (displaying weather data) with responsive widgets, reactive state management, offline storage and api calls.

Requirements

The template was build using dart null safety. Dart 2.12 or greater and Flutter 2 or greater is required.

Dart 2.15 or greater and Flutter 2.10 or greater is recommended.

Follow this guide to setup your flutter environment based on your platform.

Continuous Integration and Deployment

The Flutter template comes with built-in support for CI/CD using Github Actions.

CI

The CI workflow performs the following checks on every pull request:

Lints the code with flutter analyze.
Runs tests using flutter test.
Build the android app.
Build the ios app.

CD

The CD workflow performs the following actions:

Bump the build number by 1.
Build a signed release apk.
Upload apk to the app center.
Upload apk as artifact to release tag.
Build a signed iOS app.
Upload ipa to testflight.
Upload the ipa as an artifact to release the tag.
Commit the updated version to git.

Android CD setup

For the android CD workflow to run, we need to perform the following setup steps:

Follow these instructions to generate an upload keystore. Note down the store password, key alias and key password. You will need these in later steps.
Use openssl to convert the jks file to Base64.

openssl base64 < flutter_template_keystore.jks | tr -d '\n' | tee flutter_template_keystore_encoded.txt

Store the base64 output on Github Secrets with the key name KEYSTORE.
Save the store password in github secrets with the key name RELEASE_STORE_PASSWORD.
Save the key alias in github secrets with the key name RELEASE_KEY_ALIAS.
Save the key password in github secrets with the key name RELEASE_KEY_PASSWORD.
Create a distribution on app center and get the upload key. You can get it from appcenter.ms/settings.
Save the app center upload key on github secrets with key name APP_CENTER_TOKEN.

IOS CD Setup

For the IOS job in the cd.yml to run, you first need to have a valid Apple Developer Account.If you don't have it yet, please create one before proceeding further

We will divide the guide into steps so that it is easier to understand

Step 1: Setup on the AppStore

CAUTION: Apple doesn't allow underscore in the bundle identifier. Read about valid identifiers here

Create an application on the AppStore Connect Portal. Check out the official guide here

Step 2: Getting a Distribution Certificate and Provisioning Profile

Create a Distribution Certificate for your machine locally once. You can refer to this guide. Download the .p12 file for use later. Remember the password used to create this certificate as we will need this later
Create a Provisioning Profile for your Bundle ID you registered above. You can refer to this guide. Download the profile for use later.

Step 3: Getting the options.plist

In the following template
- Replace BUNDLE ID with your Bundle Identifier (You got that already from Step 1)
- Replace PROVISIONING PROFILE NAME with your Provisioning Profile Name (You already created one in Step 2, use that)
- Replace TEAM_ID with your team id. Look at this answer on "How to find your Team ID"

Click to View Template

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>generateAppStoreInformation</key>
	<false/>
	<key>manageAppVersionAndBuildNumber</key>
	<true/>
	<key>method</key>
	<string>app-store</string>
	<key>provisioningProfiles</key>
	<dict>
		<key>BUNDLE-ID</key>
		<string>PROVISION PROFILE NAME</string>
	</dict>
	<key>signingCertificate</key>
	<string>Apple Distribution</string>
	<key>signingStyle</key>
	<string>manual</string>
	<key>stripSwiftSymbols</key>
	<true/>
	<key>teamID</key>
	<string>TEAM_ID</string>
	<key>uploadBitcode</key>
	<false/>
	<key>uploadSymbols</key>
	<true/>
</dict>
</plist>

Create a new file called options.plist and save the above contents in that file

Step 4: Making an app specific password

Read the official guide to create an app specific password and remember it(;P)
The pipeline uses this password to upload an ipa to testflight

Step 5: Bringing it all together

Add the following keys to Github Secrets
- BUILD_CERTIFICATE_BASE64 : The base64 of the p12 file we generated(Step 2)
- P12_PASSWORD: The password of the p12 certificate generated above in Step 2
- BUILD_PROVISION_PROFILE_BASE64: The provisioning profile in base64(Step 2)
- KEYCHAIN_PASSWORD : The password used to store the keychain in the local keystore of the Github Runner(Any random value)
- IOS_PLIST: The options.plist file needed to make an ipa out of the xcarchive generated by flutter(Step 3)
- APPSTORE_PASSWORD: The password passed to altool to upload the ipa to the store(Step 4)
To generate a base64 string, use the following command, replacing FILENAME with your filename

openssl base64 < FILENAME | tr -d '\n' | tee ENCODED_FILENAME.txt

Pushing to protected branches

If the branches that you will be running CD on are protected, you will need to use a Personal Access Token (PAT) to commit the version changes.
After creating the PAT, exclude the account that the token belongs to from the branch protection rules.
Save the token in github secrets and update the key name in the cd.yml file under each checkout action.
Since our CD workflow is triggered on a push, and we create a new commit in the workflow itself, the commit message created by the CD workflow includes [skip ci] tag so that the workflow does not end up in an infinite loop.Read more about this here

If you do not plan to use the CD workflow on protected branches, you can remove the token part from the checkout actions.

Gotchas

Flutter apps might have issues on some android devices with variable refresh rate where the app is locked at 60fps instead of running at the highest refresh rate. This might make your app look like it is running slower than other apps on the device. To fix this the template uses the flutter_displaymode package. The template sets the highest refresh rate available. If you don't want this behaviour you can remove the lines 40 to 46 in app.dart. Link to frame rate issue on flutter.

Issues

Additionally look into the Issues for the repository for some commonly faced problems while setup. They are marked with the label documentation and are mostly closed

twi-star/flutter_template