Flutter Advanced Boilerplate

A new (almost) fully featured flutter boilerplate project by using BLoC.

The Motivation • Key Features • Screenshots • How To Use • Folder Structure • Changelog
Good To Know • FAQ • Community • Packages • License

📝 The Motivation

There are several reasons why this boilerplate exists, these are in short to create clear, readable, reusable, scalable, testable, performant and maintainable projects but in long:

1. to allow people to deploy production-grade MVP products,
2. to make sure that I keep everything stupid simple (controversial but I tried my best),
3. to ensure that project can easily scale horizontally as application grows,
4. to save developers time by reducing boilerplate code by writing less and generating more,
5. to maintain code quality and platform standards in team projects with strictly linting rules,
6. to have bloc and golden tests to verify everything working as intended to be,
7. to ship the application quickly and efficiently by using CI & CD to automate the development process.

🔥 Key Features

• API System & Authentication
  Rest and graphql api support with token renewal and socket support using Dio, GraphQL, and Fresh.
• Performance
  Performance optimized for lag caused by builds, such as page switches or rapid scrolling of complex lists, through frame-splitting rendering via keframe.
• State Management & Architecture
  BLoC & Hydrated Bloc helps to separate Business Logic from UI by creating persistent and powerful state management.
• Advanced Linting
  Linting rules with detailed settings to keep the health of the code good and up to the dart standards.
• Type Safety
  The boilerplate uses type-safety first approach (languages, assets, etc.) to help you avoid problems by catching null errors during development rather than at runtime.
• Forms
  Creating and managing forms has never been so easy and fun. Reactive forms is a model-driven approach to handling forms inputs and validations.
• Testing
  The more features the app has, the harder it is to test manually. Automated tests help ensure that the app performs correctly before you publish it with Bloc Test, Golden Tookit, and Mocktail.
• Dependency Injection & Service Locator
  Reduce tight coupling between classes thus achieving greater reusability of your code with Injectable and GetIt.
• Code Generation
  Maximize productivity and improve code quality by generating data classes with Freezed, Artemis, and Build Runner.
• CI & CD Integration
  CI/CD is used to continuously deliver code into production, and ensure an ongoing flow of new features and bug fixes via the most efficient delivery method by using Codemagic.
• Easy & Clean Routing
  AutoRouter allows for strongly-typed arguments passing, effortless deep-linking, and code generation to simplify routes reduce code boilerplate.
• Desing Pattern
  Repository design pattern reduces the complexity of the data layer, isolates unstructured data from the rest of the app, and organizes project structure.
• Exception Handling
  It is not a very ideal solution to handle exceptions using try and catch at every function, Data Channel provides utility for handling exceptions and data routing.
• Encrypted Storage
  Encrypted storage allows you to keep token and user informations in platforms keychain securely using Secure Storage.
• Dynamic Theme
  With Android 12 and Material You, wallpaper colors can be extracted to create a ColorScheme that can be used to color the app.
• Localization
  Easily localize the app into other languages with the support of type-safe structured 'slang' language generator.
• Permission
  The boilerplate also provides a cross-platform (iOS, Android) API to request permissions and check their status with permission_handler.
• Env Variables
  Environmental variables allows to define global constants shared in the app, for things like API keys, base URLs, and such.
• Logging & Tracking
  A detailed logging and error tracking mechanism to monitor every action taking place in the application in real-time with Logging and Sentry.
• Native Splash
  Flutter Native Splash automatically generates iOS, Android, and Web-native code for customizing this native splash screen background color and splash image.
• Refresh Rate
  Support for high refresh rate displays with the flutter_displaymode package.

📷 Screenshots

Dynamic Theme on Mobile

iOS Light TR	Android System Dark EN

Dynamic Theme on Web

Web System Light TR	Web Dark EN

📚 How To Use

🔨 Build

To clone and run this boilerplate, you'll need Git and Flutter installed on your computer. From your command line:

# Clone this repository
$ git clone https://github.com/fikretsengul/flutter_advanced_boilerplate

# Go into the repository
$ cd flutter_advanced_boilerplate

# Install dependencies
$ flutter pub get

# Generate structured language files
$ flutter pub run slang

# Checks missing and unused translations
$ flutter pub run slang analyze

# Generate data classes & structured asset files
$ flutter packages pub run build_runner build -d

# Update goldens & Execute tests
$ flutter test --update-goldens

# Run the app
$ flutter run

# Run the app on web
$ flutter run -d chrome --web-renderer html (low performance, low download size)
$ flutter run -d chrome --web-renderer canvaskit (high performance, high download size)

# If you update your splash screen configuration you can regenerate it via
$ flutter pub run flutter_native_splash:create

Hide Generated Files

In order to hide generated files, navigate to 'VSCode' -> 'Preferences' -> 'Settings' and search for 'Files: Exclude' and add the following patterns by pressing the 'Add Pattern' button:

**/*.config.dart
**/*.freezed.dart
**/*.inject.summary
**/*.inject.dart
**/*.g.dart
**/*.gr.dart

In Android Studio, navigate to 'Android Studio' -> 'Preferences' -> 'Editor' -> 'File Types' and paste the below lines under ignore files and folders section:

*.config.dart;*.freezed.dart;*.inject.summary;*.inject.dart;*.g.dart;*.gr.dart;

📁 Folder Structure

Assets Folder

assets folder is located above the lib folder. The assets that is used in the application, environmental settings, fonts, images, translations and more are found here.

.
└── assets
    ├── animations                          -> put your animated files here eg. lottie
    ├── configs                             -> put your env files here
    │   ├── dev.json                           -> env that is used for dev
    │   ├── prod.json                          -> env that is used for prod
    │   └── test.json                          -> env that is used for tes
    ├── fonts                               -> put your custom font files here
    ├── images                              -> put your image files here
    └── translations                        -> put your translation files here
        ├── en.json
        └── tr.json

Features Folder

The features folder, which is the backbone of the application, was designed using the feature-first structure instead of layer-first because it doesn't scale very well as the app grows and repository design pattern. The feature-first approach demands that we create a new folder for every new feature that we add to our app. And inside that folder, we can add the repository pattern layers themselves as sub-folders.

.
└── lib
    └── features                            -> stands for FEATURE FIRST STRUCTURE
        └── feature_x                          -> seperate and put your features here
            ├── blocs                          -> stands for APPLICATION LAYER
            │   ├── x_cubit.dart                  -> seperate and put your logics here
            │   └── x_state.dart
            ├── models                         -> stands for DOMAIN LAYER
            │   └── x_model.dart                  -> seperate and put your models here
            ├── networking                     -> stands for DATA LAYER
            │   └── x_repository.dart             -> seperate and put your repos here
            └── presentation                   -> stands for PRESENTATION LAYER
                ├── widgets                       -> seperate and put your widgets here
                │   └── x_header_widget.dart
                └── x_screen.dart

Modules Folder

In the modules folder, there are dependency injection registration and initialization processes of third-party modules to ensure that they can be easily accessed and used from within the application.

.
└── lib
    └── modules
        ├── dependency_injection               -> add your modules injection here
        │   ├── di.dart                           -> must initialize di first
        │   └── x_module_di.dart                  -> example module injection
        └── x_module                           -> create folder for your modules
            └── init_x.dart                       -> create initialization files here

Theme Folder

The theme folder contains the necessary theme configuration and settings.

.
└── lib
    └── theme
        ├── color
        │   └── app_color_scheme.dart
        ├── text
        │   └── app_typography.dart
        └── app_theme_creator.dart             -> theme creation configuration here

Utils Folder

Apart from the above, constants, helper classes, and methods, shortcuts and many more used throughout the application are located in the utils folder.

.
└── lib
    └── utils
        ├── helpers                            -> put your helpers here
        │   ├── bar_helper.dart                   -> bar helper to show alert
        │   ├── logging_helper.dart               -> logging helper to show fancy log in console
        │   └── permission_helper.dart            -> permission helper to handle permission requests
        ├── methods                            -> put your methods here
        │   └── aliases.dart                      -> create alias variables here
        │   └── shorcuts.dart                     -> add shortcut methods here
        ├── constants.dart                     -> configure app constants here
        ├── navigation.dart                    -> add navigation destinations here
        ├── r.dart                             -> generated type-safe asset classes here (don't modify)
        └── router.dart                        -> add new screens here

🌟 Good To Know

Resources I Highly Recommend you to Read & Watch

1. Code with Andrea Tutorials • Blog • YouTube
2. Reso Coder Tutorials • Blog • YouTube
3. Flutter • YouTube
4. Marcus Ng • YouTube
5. Flutter Mapp • YouTube
6. Max on Flutter • YouTube

VSCode Extensions

📦 Packages

This repository makes use of the following pub packages:

*Recommended to keep regardless of your project.

❓ FAQ

🌸 Community

🔥 Contribution

If you want to say thank you you can;

• add a GitHub Star to the project,
• tweet about project on your Twitter,
• buy me a coffee

Also code contributions are always welcome and appreciated.

1. Report a bug
   If you think you have encountered a bug, and I should know about it, feel free to report it and I will take care of it.
2. Request a feature
   You can also request for a feature, and if it will viable, it will be picked for development.
3. Create a pull request
   It can't get better then this, your pull request will be appreciated by the community. You can get started by picking up any open issues and make a pull request.

If you are new to open-source, make sure to check read more about it here and learn more about creating a pull request here.

🌵 Branches

1. stage is the development branch.

2. master is the production branch.

3. No other permanent branches should be created in the main repository, you can create feature branches but they should get merged with the master.

Steps to work with feature branch

1. To start working on a new feature, create a new branch prefixed with feat and followed by feature name. (ie. feat-FEATURE-NAME)
2. Once you are done with your changes, you can raise PR.

Steps to create a pull request

1. Make a PR to stage branch.
2. Comply with the best practices and guidelines e.g. where the PR concerns visual elements it should have an image showing the effect.
3. It must pass all continuous integration checks and get positive reviews.

After this, changes will be merged.

Together, we can make this project better every day! 😘

🔒 License

MIT © Fikret Şengül