Properly setting up a Flutter app

Create the app

The basic Flutter template is the best starting point. So, assuming you have a working Flutter installation, run this in your terminal:

flutter create coolapp

Additional parameters can be checked with flutter create -h, but the defaults are pretty solid.

Do a cd coolapp and open your preferred code editor inside our new app's folder. For example, code . to open Visual Studio Code.

Our app folder will look like this:

About each folder

The .dart_tool auto-generated folder is where Dart and Flutter build system stores project dependencies, configuration files, build artifacts and cache. It is safe to delete it and this is usually a last resort procedure when the app's build reports strange dependency errors. It must be not versioned.

The .idea folder is specific to the JetBrains IDEs, like Android Studio. This folder is useless for VS Code, but it is good practice to keep it in case we ever need to open our project in Android Studio. It must be not versioned also.

The lib folder is where our code lives and the test folder is where we challenge our code with tests.

And then, we have one folder for each Flutter supported platform: android, ios, linux, macos, web and windows.

Add a .gitignore

Add this basic .gitignore file to the root of the app folder for good practice. It will later prevent file versioning of non code files to our future Git repository.

Those folders we previously mentioned and almost all other possible files that may be written to our project folder and that should not be versioned, all those will be ignored by Git and just kept local.

# Miscellaneous
*.class
*.log
*.pyc
*.swp
.DS_Store
.atom/
.build/
.buildlog/
.history
.svn/
.swiftpm/
migrate_working_dir/

# IntelliJ related
*.iml
*.ipr
*.iws
.idea/

# The .vscode folder contains launch configuration and tasks you configure in
# VS Code which you may wish to be included in version control, so this line
# is commented out by default.
#.vscode/

# Flutter/Dart/Pub related
**/doc/api/
**/ios/Flutter/.last_build_id
.dart_tool/
.flutter-plugins
.flutter-plugins-dependencies
.pub-cache/
.pub/
/build/

# Symbolication related
app.*.symbols

# Obfuscation related
app.*.map.json

# Android Studio will place build artifacts here
/android/app/debug
/android/app/profile
/android/app/release

Edit pubspec.yaml

Add a description to your project and make sure to keep publish_to: "none" in order to not accidentally publish your app to pub.dev:

name: coolapp
description: "A very cool app!"

# The following line prevents the package from being accidentally published to
# pub.dev when using `flutter pub publish`.
# This is preferred for private packages.
# Only remove this line if you wish to publish to pub.dev
publish_to: "none" 

# ...

And don't change the app's name: parameter here. That is not the display name that we can see in our device's home screen. It is the name of the default root package of our code that we will use in import statements throughout our .dart files.

Properly change our app's display name

For the Android build, edit the file: android/app/src/main/AndroidManifest.xml

<application
    android:label="CoolApp"
    ... >

For the iOS build, edit the file: ios/Runner/Info.plist

<key>CFBundleDisplayName</key>
<string>CoolApp</string>

Avoid using the default README.md file in private projects

If your target app is private, avoid using README.md as a technical document. It can inadvertently go into a build package as an asset in some rare scenarios, or be packed in the Web version. It can happen, so it is good practice to avoid it.

The best approach here is to add a "dot" to the beginning of it, like .README.md. Or even better, to add a folder at the root of your project starting with a "dot", like /.mystuff and add all private files of your project there. This will ensure that files inside of it won't be build packed.

Files and folders starting with a "dot" are just packed if we explicitly add them as assets in your pubspec.yaml.

By "private files" here, I mean technical details we want to record and share with our teams. Versioning but not including them in the final delivered packages.

By the way, never store credentials or sensitive data in your versioning system.

Do a first run

Before adding some basic dependencies to our project, let's check if everything is in place running our app for the first time.

To run an Android app, previously set up your environment following these steps from Flutter docs.

To run an iOS app in a Mac, previously set up your environment following these steps.

Then open an emulator device in your environment.

And finally, at the root folder of our project run flutter run in your terminal. A list of available devices will be shown. Choose your device emulator. Bang!

If something did not go as planned, review the previous steps and check with AI to help you with any odd error.

No dark theme?

If you now change your simulator config to dark mode, there will be no theme change listener mechanism in our current default app to "react" to that change. In fact, there will be no dark theme code at all to handle that.

Architecting our codebase

In the next posts in these series we will change the default Flutter generated code example to create a great app skeleton for our apps to build upon.

We will make architectural additions like theming – dark, light and colored – localization (l10n), great navigation, persistence and state management patterns on top of production proof libraries.

That will turn our app into an organized, beautiful and efficient codebase for our functional features' code to grow solid upon.

The better our starting code is, the less we will need to do big refectories and more time will be available to work on what matters.