very_good_core.md

Very Good Core 🦄

Developed with 💙 by Very Good Ventures 🦄

A Very Good Flutter Starter Project created by the Very Good Ventures Team.

Getting Started 🚀

❗ In order to start using Very Good Core you must have the Flutter SDK installed on your machine.

Installation 💻

For first time users, start by installing the Very Good CLI from pub.dev.

dart pub global activate very_good_cli

Create a new Flutter Project 🆕

Then, you can use the very_good create command just like you would flutter create

💡 Upon first use, you will be prompted about anonymous usage statistics. You can adjust these settings at any time via the --analytics flag

# opt into anonymous usage statistics
very_good --analytics true

# opt out of anonymous usage statistics
very_good --analytics false

Running the Project ⚡

Once you have finished running very_good create with the project directory of your choice, you can change directories into the new project directory and install the dependencies

cd my_app
flutter packages get

This project contains 3 flavors:

• development
• staging
• production

Each flavor has dedicated entry point (main_development.dart, main_staging.dart, main_production.dart) which can be used to setup, instantiate, and/or inject flavor-specific dependencies into the application.

For example:

• In development we might want to output logs to the console but in staging and production we might want to upload logs to sentry.io or firebase analytics.
• We might want to configure an ApiClient or DatabaseClient to point to a different endpoint for each flavor.

To run the desired flavor either use the launch configuration in VSCode/Android Studio or use the following commands:

# Development
flutter run --flavor development --target lib/main_development.dart

# Staging
flutter run --flavor staging --target lib/main_staging.dart

# Production
flutter run --flavor production --target lib/main_production.dart

*Very Good Core works on iOS, Android, and Web.

Now your app is running 🎉

---

Why Very Good Core? 🤔

We liked the simplicity and developer experience of running flutter create when getting started on a new project. We wanted to provide a similar experience with very_good create which built on top of flutter create and includes the core standards and best practices we use at Very Good Ventures.

We built the CLI to be extensible so it could potentially support multiple commands and templates in the future.

Project Structure and Architecture 🏗️

Although Very Good Core is fairly basic in terms of functionality, the architecture and project structure is intended to scale from a simple hobby project to a large production ready application.

A folder-by-feature project structure is used to maintain a modular project structure which helps the project scale as the number of features and/or developers increase. In Very Good Core there is only a single feature (counter) to start but that will quickly change as you build out your project. Each feature usually consists of a view and a cubit (or bloc). The view is responsible for holding the UI (Widgets) which the user sees and interacts with and the cubit/bloc is responsible for containing the business logic needed to manage the state of the feature. For more details read our best practices for building scalable apps.

---

Testing 🧪

Very Good Core ships with 100% code coverage. To learn more about why we believe 100% code coverage is important and other testing best practices read our guide to Flutter testing.

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",
    "counterAppBarTitle": "Counter",
    "@counterAppBarTitle": {
        "description": "Text shown in the AppBar of the Counter Page"
    }
}

2. Then add a new key/value and description

{
    "@@locale": "en",
    "counterAppBarTitle": "Counter",
    "@counterAppBarTitle": {
        "description": "Text shown in the AppBar of the Counter Page"
    },
    "helloWorld": "Hello World",
    "@helloWorld": {
        "description": "Hello World Text"
    }
}

3. Use the new string

import 'package:very_good_core/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>es</string>
	</array>

    ...

Adding Translations

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

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

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

app_en.arb

{
    "@@locale": "en",
    "counterAppBarTitle": "Counter",
    "@counterAppBarTitle": {
        "description": "Text shown in the AppBar of the Counter Page"
    }
}

app_es.arb

{
    "@@locale": "es",
    "counterAppBarTitle": "Contador",
    "@counterAppBarTitle": {
        "description": "Texto mostrado en la AppBar de la página del contador"
    }
}

---

Continuous Integration 🤖

Very Good Core comes with a built-in GitHub Actions workflow but you can also add your preferred CI/CD solution.

Out of the box, on each pull request and push, the CI formats, lints, and tests the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses Very Good Analysis for a strict set of analysis options used by our team. Code coverage is enforced using the Very Good Coverage GitHub Action.

---

Updating App Icons 📱

When you create a new project, it has a default launcher icon. To customize this icon, you can do it by using the following steps for each platform.

Android

1. Review the Material Design product icons guidelines for icon design.

2. In the [project]/android/app/src/main/res/ directory, place your icon files in folders named using configuration qualifiers. The default mipmap- folders demonstrate the correct naming convention.

3. In AndroidManifest.xml, update the application tag’s android:icon attribute to reference icons from the previous step (for example, <application android:icon="@mipmap/ic_launcher" ...).

4. To verify that the icon has been replaced, run your app and inspect the app icon in the Launcher.

iOS

1. Review the iOS App Icon guidelines.

2. In the Xcode project navigator, select Assets.xcassets in the Runner folder. Update the placeholder icons with your own app icons.

3. Verify the icon has been replaced by running your app using flutter run.