Create an Afib Project
Install Flutter
You will find instructions to install and setup Flutter on this page:
https://docs.flutter.dev/get-started/install
Before you procede further, make sure the 'flutter doctor' command reports no errors.
Create a new Flutter project
Start by creating a new flutter project using the flutter create command, and cd'ing into the root of your project folder.
Then, verify that you can run your project in an emulator (I'd start with iOS) using the flutter run command.
Prefer Visual Studio Code
Although it is not required, AFib currently provides an extension for VS Code which makes maintaining the identifiers (mostly widget IDs and test data IDs) used in AFib easy.
When you open an AFib project in VS code, it should automatically suggest downloading the AFib extension. If it does not, you can install the "AFib Project Helper" extension manually.
Choose a Project Style
If you run help for the afib_bootstrap create command:
You will see a list of project styles. Choose the one that applies to you:
app-starter-signin-firebase
If you plan to use Firebase Authentication in your app, start with this project. You will need to setup Firebase itself by running flutterfire configure, as described on the Firebase website, prior to applying this project style. This style provides UI and implementation for signin, registration, password reset, account settings, and the ability to delete your account out of the box.
Flutter Startup Issues on Android
Unfortunately, Flutter projects are currently generated to use an ancient version of Android. This causes two issues. First, if you are using Firebase you will get failures at startup saying your Android version is too old. If you fix that as it suggests, you may get error messages saying your app is to large and you need a "DEX" fix. Both of these errors are fixed by bumping your Android version in a gradle file to something more recent as described here..
In addition, Android studio makes the default emulator storage size too small for modern Android OSs. If you get a message that there is 'not enough internal storage', you can fix it by increasing the Emulator's storage size as described here.
I'm not sure why Google's Flutter runs more seamlessly out of the box on iOS than Android, but it does. You might want to start on iOS. The Android issues are easily resolved but an annoying way to start.
app-starter-signin
If you plan to have a signin workflow in your app, but don't plan to use Firebase. For example, if you are authenticating against a REST-based backend. This style provides UI for signin, registration, password reset, account settings, and the ability to delete your account out of the box. It defers the actions supporting these UIs (e.g. how to hit a REST API that resets a password) to you.
app-starter-minimal
If your app does not have a signin workflow, or you want to build everything yourself, start here. However, note that if your app is going to have a signin page, I would strongly suggest using one of the previous two styles. I am often tempted to 'start from scratch', with the idea that I will learn more or achieve a leaner result, but the two previous styles provide a lot of value that I think you are unlikely to realize by 'baking your own' signin to start.
app-eval-demo
If you'd like to play with the code used in the evaluation video above, use this project style. See the 'Transition to Coding in AFib' section for a walk through of understanding and manipulating this project style.
This product style does not have an introductory video, as the first half of the tutorial video serves that purpose.
Convert your new Flutter project into an AFib project
Decide on a 2-5 character code for your project
Ultimately, your project may incorporate third-party AFib-aware components. To disambiguate a variety of shared filenames, every AFib project has a 2-5 character project code prefix. Please choose one for your project.
For example, in the Todolist app in from the tutorial I used todo.
Set your own project code to display in this documentation
Throughout this guide, I will type commands and filenames as though your project code was 'xxx'. Once you choose a project code for your project, I'd recommend you click the button below to set it as the code displayed in this documentation.
Set character code used in this documentaton
If you do not set the code, and you see 'xxx' in a filename (e.g. the file xxx_config.g.dart) you will need to remember that you are looking for the file with your prefix (e.g todo_config.g.dart).
TODO is used in this guide to refer to a Todo List example
Note that in this guide, I will sometimes give example code that is inspired by the Todo List example from the tutorial. Often, assuming that example code is within a Todo list app makes the code easier to understand. In that case, I will use TODO as the prefix, which is a hint that the example code is not a general purpose example, and that it is meant to be thought of in a todo list context.
Run the afib_bootstrap command in your project folder
You use the afib_bootstrap command from within your Flutter project's root folder to convert a new Flutter project into an AFib project:
flutter pub global run afib:afib_bootstrap create app --packagename yourpackagename --package-code xxx --project-style choosen-project-style
For example, for a todolist app that plans to use Firebase Authentication, I might choose:
flutter pub global run afib:afib_bootstrap create app --packagename todolist --package-code todo --project-style app-starter-signin-firebase
Some project styles may require other packages
Please watch the output of your create command. It may prompt you to install additional dart packages. If AFib-bootstraps prompts you to install some packages, you should do so.
Upgrading an existing Flutter project is not recommended
I do not see any advantage in running this command in a pre-existing Flutter project. If you are attempting to convert an existing app to use AFib, I recommend creating a new, empty Flutter app, installing afib, and then migrating your code over manually. That said, AFib commands will refuse to overwrite existing files, or rename them with .old in a few cases, so running it on an existing project won't do any damage.
Verify that your custom AFib command is working
AFib provides a custom command line executable that exposes all of AFib's command line functionality for your project in bin/xxx_afib.dart.
This command is specific to your project, and can be used to run tests, generate code, and more. It is also extensible by both you and third parties. You can add your own subcommands, and third party packages can integrate their own subcommands for your use.
You must run this command from the root of your project folder. For example:
Please run this command, and verify that the help output is similar to that shown below.
$ dart bin/xxx_afib.dart help
Usage: afib help <command> [<subcommand>]
Available commands:
config - Set configuration values in initialization/xxx_config.g.dart
generate - Generate AFib source code for screens, queries, models, and more
test - Run tests, you can specify any prototype name, test name, or any of the values for afib.dart help config's --tests-enabled option
help - Show help for other commands
integrate - integrate a third-party library, or the second part of a project style
Note: to create a new afib project, use the afib_bootstrap command
If Applicable: Run Phase Two of Your Project Style
The project styles app-starter-signin and app-starter-signin-firebase both have a second phase to project setup. When the afib-bootstrap command completes, it gives you the command to run this second phase, similar to:
Verify that your app runs in an emulator
Now, use flutter run to start your app. Depending on the projects style you choose, you will see one of the following four screens on startup:
app-starter-signin-firebase startup screen
app-starter-signin startup screen
app-starter-minimal startup screen
app-eval-demo startup screen
Open your project in Visual Studio Code
Open Visual Studio Code, and open the project folder (or, add it to a new VS Code workspace).
Look in the bottom right hand corner of VS Code, and tap on the emulator you are using (it might be Android, iOS, web, macOS, etc). This displays a list at the top of VS Code which allows you to choose where you would like to debug your app.
If are developing multiple dart packages, load them all into a single VS Code Workspace
When I started using Flutter, for a variety of reasons I was used to having one VS Code window per-project. Because of how VS Code/Flutter detects and reloads code changes, if you are editing several Dart/Flutter packages at the same time, they must all be in the same VS Code window, loaded into a single VS Code workspace. Only then will the debugger detect and integrate changes to all the packages simultaneously.
Launch from the main.dart file.
Type Command-p to search files and the type in main.dart. Wait a second, and you will see a debug link appear just above the 'main' function.
Click on the 'debug' link. This will launch your app in the environment you specified, again showing the Afib Starter page.
What is next
You are now ready to begin developing your app. You would most likely start by using the dart bin/xxx_afib.dart generate command to generate a model, root state, or a screen, all of which are described in detail in this guide.