An opinionated starting point for a Flutter app intended to provide the boilerplate needed to create a large app and provides utilities to separate code generation into separate packages.
- Dart: 3.2.0
- Flutter SDK: 3.16.0
- Setup:
- Install Melos globally
- Run
melos bootstrap
to install dependencies andmelos run generate
to generate for all packages. - Rename App: Change App/Package Name
- Update Description: pubspec.yaml and README.md.
- Add Environment Variables: ENVied Environment Variables section for details.
- Change App Icon: flutter_launcher_icons
- Change Splash Screen: flutter_native_splash
- Setup the release build configuration, see the Building section.
- Setup Codecov for the repository, see the Codecov documentation. code provided in this template, but the licenses of the packages must still be followed.
-
Run the following command to change the package name, where
com.author.app_name
is the new name for the app.flutter pub run change_app_package_name:main com.author.app_name
-
Search for
erb_flutter_boilerplate
and replace it with your new package identifier -
Search for
Erb Flutter Boilerplate
and replace it with your new app name -
Search for
com.example.erb_flutter_boilerplate
and replace it with your new Android bundle identifier -
Search for
com.example.erb_flutter_boilerplate
and replace it with your new iOS bundle identifier
This project automatically builds for all platforms without code signing using GitHub Actions. To build the project locally, follow the instructions in the Flutter docs. Only Windows, Android, and iOS build files are currently uploaded to the CI action fragments.
Instructions for building for release are below:
By default, the app uses the "local" flavor. Run/build the app with --dart-define FLAVOR=<flavorname>
to change the flavor. The following flavors are supported:
local
- Local development. The text banner changes to "Debug" when in debug mode, "Local" in profile mode, and hidden in release mode.dev
- Development build not intended for release.beta
- Beta build intended for release to testers.staging
- Staging build intended for device integration testing.prod
- Production build intended for release to stores.
This project uses the Riverpod App Architecture in a feature-first manner where each feature is a separate package in the lib/features/ folder. Each feature has its own layers, which separate the business logic from the UI.
The repository pattern consists of Repositories, DTOs, and Data Sources. Their jobs are the following:
- isolate domain models (or entities) from the implementation details of the data sources in the data layer.
- convert data transfer objects to validated entities that are understood by the domain layer
- (optionally) perform operations such as data caching.
Repository pattern use cases:
- talking to REST APIs
- talking to local or remote databases (e.g. Sembast, Hive, Firestore, etc.)
Domain Models, which consist of entity and value objects. It should solve domain-related problems.
The domain models can contain logic for mutating them in an immutable manner, but they should not contain any serialization.
- Note: it is a simple data classes that doesn't have access to repositories, services, or other objects that belong outside the domain layer.
- holds business logic
- manage the widget state
- interact with repositories in the data layer
Implements application-specific logic by accessing the relevant repositories as needed. The service classes are not concerned about:
- managing and updating the widget state (that's the job of the controller)
- data parsing and serialization (that's the job of the repositories)
Environment variables are setup using ENVied in the env package. Environment variables need to be defined for debug, profile, and release modes.
- Copy the
*.env.example
files and remove the.example
extension from them. - Add the values for the environment variables in the respective
.env*
file.- Each key must be added to each
.env*
file, unless a non null default value is added to the@EnviedField
annotation. - It is recommended to use an empty string for the default and use
Env
's getter to access the value.
- Each key must be added to each
- Update packages/env/lib/src/env/env_fields.dart with the new environment variables.
- Add the new environment variables to the implementing
*Env
classes in the src/env directory.- It must be done for all even if only one
.env
file is planned to be used
- It must be done for all even if only one
- Enable
obfuscate
for API keys in the@EnviedField
annotation. (Note: still assume it is not secure) - Optionally, add a
defaultValue
to the@EnviedField
annotation for keys which are not required in all modes.
This project uses Melos to manage the monorepo.
flutter pub get
# Install melos globally
dart pub global activate melos
# Setup local dependency overrides for packages in the monorepo
melos bootstrap
# Or if dart executables are not on your path
dart pub global run melos bootstrap
Pub:
melos run pub
- Runpub get
in all packages.melos run dart:pkg
- Rundart pub get
in the selected dart package.melos run flutter:pkg
- Runflutter pub get
in the selected flutter package.melos run pub-outdated
- Runpub outdated
in all packages.melos run pub-upgrade
- Runpub upgrade
in the package.
Code Generation:
dart run build_runner watch -d
- Watch and generate code for the app, does not work with subpackagesmelos run generate
- Runbuild_runner build
generate in all packages that depend onbuild_runner
and i18n.melos run generate:pkg
- Runbuild_runner build
in all packages that depend onbuild_runner
.melos run generate:i18n
- Runbuild_runner build
generate i18n.melos run watch:pkg
- Runbuild_runner watch
for a specific package. It will not work if you choose "all" in the package selection prompt.melos run watch:i18n
- Runbuild_runner watch
for i18n.
This project uses Slang to Type-safe i18n.
-
Translating untranslated strings
- Run slang analyzer to check for missing translations
dart run slang analyze --outdir=i18n
-
Open i18n/_missing_translations.json and then translate your language of choice.
-
After editing the file, you can apply it to the actual json translation file by running:
dart run slang apply --outdir=i18n dart run slang analyze --outdir=i18n # update analyzation result files
- Run build_runner after editing some areas that needs a code generator such as entities and routing.
- Run slang after editing translation files (*.i18n.json).
- build_runner and slang has some features that will be helpful during development such as auto-rebuild and translation analysis, so it's highly recommended to check the documentations and familiarize yourself with it.
- reference vue specification (Angular)
feat
Add new featuresfix
Fix the problem/BUGstyle
The code style is related and does not affect the running resultperf
Optimization/performance improvementrefactor
Refactorrevert
Undo edittest
Test relateddocs
Documentation/noteschore
Dependency update/scaffolding configuration modification etc.workflow
Workflow improvementsci
Continuous integrationtypes
Type definition file changeswip
In development