Flutterprint

A starter app for building maintainable & scalable Flutter apps, streamlining development with commonly used features.

Usage 🚀

# Generate the flutterprint app template
mason make flutterprint

Flutterprint uses freezed to generate data-classes/unions, the generated codes *.freezed.dart are included in this template. However you may need to run the code generator command after creating new freezed classes.

flutter pub run build_runner build --delete-conflicting-outputs

Variables ✨

What's Included ✨

Out of the box, Flutterprint includes:

• ✅ Cross Platform Support - Built-in support for iOS, Android, and Web.
• ✅ Go Router - A declarative routing package that uses url-based API for navigating between different screens.
• ✅ Internationalization Support - Internationalization support using synthetic code generation to streamline the development process.
• ✅ Riverpod - A reactive caching and data-binding framework.
• ✅ Testing - Unit and Widget Tests
• ✅ Continuous Integration - Lint, format, test, and enforce code coverage using GitHub Actions
• ✅ Dependabot Integration

Features

• ✨Token-based Authentication Flow

  The app provides a demonstration of a token-based authentication flow, including sign in and refresh token strategy. It uses a fake authentication repository by default, but can easily be configured to use a backend for user authentication by modifying the configuration settings and using the REST API service that is provided by this template. The authentication flow allows users to securely access protected resources and maintain an authenticated state throughout the session.

• ✨Backend Environment Switching

  The app demonstrates a feature that allows the user to easily switch between different backend environments (such as release, demo, development, or even localhost) and configure the baseURL and API endpoints for each environment, which enables seamless testing and development.

• ✨Redirection Logic

  The app uses go_router combined with riverpod to handle redirect logic that automatically redirects the user to the appropriate pages based on the user's authenticated state. This feature is handled throughout the app and provides a seamless experience for the user by ensuring that they are always directed to the correct page. For instance, whether the user is authenticated or unauthenticated, they will be redirected to the home page or sign-in page, respectively.

• ✨REST API Service

  A service provides a simple interface for performing CRUD operations on a remote server, returning results in the form of Future<Either<ApiFailure, T>> indicating whether the request was successful or not. If the request is successful, T is the generic type of desired domain model deserialized from the json response, otherwise ApiFailure is the union class that provide a pattern-matching way to handle different types of errors.

Folder Structure

├── lib
│   ├── constant
│   ├── features
│   ├── l10n
│   ├── routing
│   ├── services
│   ├── utils
│   ├── widgets
│   └── main.dart

Please note that the folder structure presented here is limited to the lib directory, but the template also includes generated files and configurations in other directories such as android, ios, and .pubspec.yaml.

Development Guideline

Feature-first structure

The app template is structured in a feature-first(layers inside features) way to make it easy to add new features and maintain the codebase. This folder contains all the different features of the app, organized into subfolders by feature name. Each feature folder contains subfolders for data, domain, application and presentation layers.

├── lib
│   ├── features
│   │   ├── feature1 
│   │   │   ├── presentation
│   │   │   ├── application
│   │   │   ├── domain
│   │   │   └── data
│   │   └── feature2
│   │   │   ├── presentation
│   │   │   ├── application
│   │   │   ├── domain
│   │   │   └── data

Each layer has its own role for a given feature:

• The domain layer holds the models that are specific to the feature.
• The data layer holds the repositories that handle communication with remote or local data sources, providing domain data to the application layer.
• The application layer handles logic and state management, using data from the data layer to fulfill the app's requirements.
• The presentation layer contains the UI widgets that users interact with, rendered based on the state managed in the application layer.

Provider's life-cycle

It is a good practice to add the .autoDispose modifier to your providers, as it ensures that they are disposed as soon as all of their listeners are removed, avoiding unnecessary costs.

On the other hand, if you want to keep some state in memory and always have it available while the app is running, you can keep it alive. For example, when using Riverpod for dependency injection, you can create long-lived providers for objects that you want to instantiate just once (such as wrappers for third-party APIs like FirebaseAuth or SharedPreferences).

Configurations 🔧

• Authentication Repository

  The AuthRepository provider uses a fake repository by default for demonstration purpose. To use a real implementation, replace the fake repository with your own implementation in the auth_repository.dart located in the lib/features/authentication/data directory.

• Backend baseURL and API endpoints

  You can configure the backend base environment in the backend_env.dart and API endpoints in the endpoints.dart that are located in the lib/features/backend_environment/domain directory.

• Routes

  The routes for the app are defined and declared in the app_router.dart, which is located in the lib/routing directory. For more information, please refer to go_router.

Running Tests 🧪

To run all unit and widget tests use the following command:

$ flutter test --coverage --test-randomize-ordering-seed random

To view the generated coverage report you can use lcov.

# Generate Coverage Report
$ genhtml coverage/lcov.info -o coverage/

# Open Coverage Report
$ open coverage/index.html

Working with Translations 🌐

This project relies on flutter_localizations and follows the official internationalization guide for Flutter.

Adding Strings

1. To add a new localizable string, open the app_en.arb file at lib/l10n/arb/app_en.arb.

{
    "@@locale": "en",
    "account": "Account",
    "@account": {
        "description": "Text shown in the title of account text field"
    },
}

2. Then add a new key/value and description

{
    "@@locale": "en",
    "account": "Account",
    "@account": {
        "description": "Text shown in the title of account text field"
    },
    "helloWorld": "Hello World",
    "@helloWorld": {
        "description": "Hello World Text"
    }
}

3. Use the new string

import 'package:flutterprint/l10n/l10n.dart';

@override
Widget build(BuildContext context) {
  final l10n = context.l10n;
  return Text(l10n.helloWorld);
}

Adding Supported Locales

Update the CFBundleLocalizations array in the Info.plist at ios/Runner/Info.plist to include the new locale.

    ...

    <key>CFBundleLocalizations</key>
	<array>
		<string>en</string>
		<string>zh</string>
	</array>

    ...

Adding Translations

1. For each supported locale, add a new ARB file in lib/l10n/arb.

├── l10n
│   ├── arb
│   │   ├── app_en.arb
│   │   └── app_zh.arb

2. Add the translated strings to each .arb file:

app_en.arb

{
    "@@locale": "en",
    "account": "Account",
    "@account": {
        "description": "Text shown in the title of account text field"
    },
}

app_zh.arb

{
    "@@locale": "zh",
    "account": "帳號",
    "@account": {
        "description": "用於帳號欄位的標題文字"
    },
}

Credits and Acknowledgments

This project was originally developed by Very Good Ventures 🦄. It has been forked and adapted for creating different App templates by Danny Chuang.

Some of the project's structure and test flow were inspired by Andrea Bizzotto. I would like to acknowledge and thank him for the inspiration he provided through his work.

Setup 🧑‍💻

Ensure you have the mason_cli installed.

# 🎯 Activate from https://pub.dev
dart pub global activate mason_cli

# 🍺 Or install from https://brew.sh
brew tap felangel/mason
brew install mason

Installation ☁️

# Install locally
mason add flutterprint

# Install globally
mason add -g flutterprint

Usage 🚀

mason make flutterprint

Variables ✨

Hooks 🪝

• ✅   Pre-Gen
• ✅   Post-Gen

Environment 🌎

mason: ">=0.1.0-dev.40 <0.1.0"

0.1.5

• feat: upgrade to Flutter 3.7.2
• fix: debug error log not caught

0.1.4

• feat: upgrade to Flutter 3.7.0

0.1.3

• chore(brick): upgrade to mason v0.1.0-dev.40
• feat: run flutter pub get on template generated

0.1.2

• chore: remove git ignored files in brick

0.1.1

• docs: update readme

0.1.0

• feat: add startup feature
• feat: upgrade to Flutter 3.3.10
• refactor: move snackbar under services
• refactor: rename router to routing

0.0.1

• feat: initial release 🎉

MIT License

Copyright (c) 2022 Danny Chuang

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.