Forem: C💙demagic

Java Heap Space error and how Codemagic helps to remediate it

C💙demagic — Thu, 12 Sep 2024 11:15:42 +0000

Overcoming issues related to Java Heap Space while building Android projects can be quite challenging and frustrating. Understanding the concept of heap memory in Java is crucial, as well as being aware of the available solutions.

This article will provide a brief explanation of the reasons behind the occurrence of the Java Heap Space issue and present Codemagic’s recommended solutions for addressing it.

I recently added some gradle tasks to my Android project, which stuffed my project with memory-hungry gradle tasks, e.g. DexGuard and ProGuard, that ended up requiring more heap space memory and the machine fell short of providing it. To put more context into it, while executing tasks, it was either exiting Daemon by shutting it down prematurely or throwing java.lang.OutOfMemoryError :

ERROR:: R8: java.lang.OutOfMemoryError: Java heap space
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':app:minifyReleaseWithR8'.
> com.android.tools.r8.CompilationFailedException: Compilation failed to complete

During the project’s construction, I found it unexpected that running DexGuard demanded a significantly larger amount of memory than what some machines could manage. This was already impacting the release pipelines that had to be tested and deployed to the Google Play Store.

The limitation does not specifically apply only to DexGuard or ProGuard, but any other gradle tasks might restrict build pipelines by requiring more memory. There are some suggestions out there to get the issue resolved:

Consider updating the gradle-wrapper.properties file to the latest version of Gradle and the android/build.gradle file to the latest version of the Android Gradle plugin as this may resolve the issue. However, working with their Java version compatibility can be tricky by keeping in mind that projects do not support the latest versions of Gradle and AGP.
Increasing the -Xmx heap size without confirmation of sufficient available memory from the machine is uncertain. If the assigned heap size exceeds the machine’s capacity, the value will be disregarded.

Codemagic to the rescue

Codemagic as a CI/CD platform did the team a huge favour by speeding up workflow pipelines along with automatically conducting tests, creating builds, and releasing team apps on the Play Store, on top of addressing the Java Heap Space issue. Codemagic’s robust machines have made building, testing, and publishing not just Android but iOS applications incredibly easy. Struggles with not only the Java Heap Space error but also other related issues can be relieved through the powerful machines provided by Codemagic:

macOS with Apple M2, M2 Pro, Max and Ultra chips
Linux with arm64 and x64 architectures
Windows

Conclusion

Contact here if your Android builds are affected by OOM (out of memory) error or similar issues, and you are interested in trying any of these machines with extended specifications.

100% Flakiness-free UI test automation with Kaspresso and Allure TestOps

C💙demagic — Wed, 22 Nov 2023 08:17:00 +0000

This article was written by Nihal Agazade and originally posted to the Codemagic blog.

UI testing in mobile app development is a challenging task due to multiple factors such as flaky tests, saving screenshots, printing useful logs and readability of test codes. We will be talking about a new UI testing framework Kaspresso for Android apps and how it is different from other frameworks when it comes down to solving these challenges.

What is Kaspresso and why should it be chosen?

Kaspresso is based on Espresso and Kakao DSL which helps it have a great readability of test codes and comes with many built-in features:

Kakao DSL based test code readability. For our better understanding, let’s quickly check how Kaspresso Kakao DSL wrappers differ from Espresso:

Espresso:

@Test
fun LoginActivity() {
    onView(withId(R.id.login_button))
        .check(ViewAssertions.matches(
               ViewMatchers.withEffectiveVisibility(
                       ViewMatchers.Visibility.VISIBLE)))
    onView(withId(R.id.login_button)).perform(click())
}

Kaspresso:

@Test
fun LoginActivity() {
    MainScreen {
        LoginButton {
            isVisible()
            click()
        }
    }
}

100% flaky test protection, thanks to its built-in protection rules.
Allure Test Ops support

To learn more about what else Kasspresso offers, feel free to check the official documentation.

How to get started with Kaspresso?

First and foremost, mavenCentral() needs to be declared inside the root build.gradle. Make sure that jcenter() is removed from the project along with the dependencies that require jcenter().

Note: Recent native android projects have it defined inside settings.gradle instead:

pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

Open app/build.gradle and integrate Kaspresso into your project by adding the following line:

dependencies {
    androidTestImplementation("com.kaspersky.android-components:kaspresso:1.5.3")
}

By this, we are good to go with Kaspresso unless Allure Testops needs to be integrated which requires additional steps to be followed, and we will be talking about it in the next section.

We briefly talked about what features Kaspresso introduces and what makes Kaspresso different from other frameworks. Let’s go through some of the key features for further clarification.

Painful flaky tests

Test flakiness is something we can hardly avoid considering that our code constantly changes, adding new screens, new functionalities etc. There are multiple reasons that could be the actual cause of flaky tests, such as:

Real devices or emulators
Test code
Production code
General infrastructure
Or even instability with the testing framework you are using

Kaspresso has it reduced to the very minimum with its DSL wrappers and Interceptors. Interceptors are built-in and help achieve many useful things, e.g:

add custom actions to each framework operation like writing a log or taking a screenshot;
overcome flaky operations by re-running failed actions, scrolling the parent layout or closing the android system dialog;

For an example, ScreenshotStepWatcherInterceptor is utilised to take pictures whether tests fail or pass and it is part of TestCase() constructor:

class SimpleLoginActivity : TestCase(
    kaspressoBuilder = Kaspresso.Builder.simple().apply {
        stepWatcherInterceptors.add(ScreenshotStepWatcherInterceptor(screenshots))
    }
)

TestCase() is a class inherited from com.kaspersky.kaspresso.testcases.api.testcase.TestCase which is out of the box ready for use.

Screenshots

Kaspresso has made the process of taking screenshots much easier via its interceptors. It is possible to take snapshots of every screen while tests are executed and save these screenshots under a desired file name through the device.screenshots.take("desired_file_name") method:

   @Before
   @Test
   fun test() {
       run {
           step ("Products dropdown is available") {
           device.screenshots.take("screenshot_file_name")
           ProductsScreen {
               testActivityButton {
                   isVisible()
                   isClickable()
               }
             }
           }
       }
   }

Permissions must be granted for screenshots to be taken by importing androidx.test.rule.GrantPermissionRule, otherwise there will be no READ_EXTERNAL_STORAGE nor WRITE_EXTERNAL_STORAGE in place. So, at the top of the Kotlin Class/File where the kotlin test code is stored, GrantPermissionRuleneeds needs to be imported:

import androidx.test.rule.GrantPermissionRule

and then, within the same file, @Rule must be declared which is inherited from org.junit.Rule:

@get:Rule
    val grantPermissionRule: GrantPermissionRule = GrantPermissionRule.grant(
        android.Manifest.permission.READ_EXTERNAL_STORAGE,
        android.Manifest.permission.WRITE_EXTERNAL_STORAGE
    )

Besides these changes, AndroidManifest.xml needs to be configured for a complete permission cycle:

<manifest>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> 
    <application>
    </application>
</manifest>

Kaspresso device.screenshots.take object is similar to device.uiDevice.takeScreenshotfrom the uiautomator library, however the key difference would be custom file names that can be easily managed through device.screenshots.take, especially when there are lots of snapshots and it can be tricky to find the appropriate ones.

Note: A video mp4 file is saved to sdcard/Documents along with screenshots and you can find an exact file path in the logs which is explained in the following section.

Logging

Custom notes can be added to the logs, and for that purpose testLoggerobject can be used with the i method:

fun test() {
       run {
           testLogger.i("Either hardcoded or dynamic values through env vars $VALUE")
           MainScreen {}

However, there is another challenge at this point and it is about splitting test internals into different steps, so that which tests fail and which ones pass can be observed easier.

What we can do is to wrap our code in try catch block along with adding manual logs to the output. Something like:

@Test
    fun sampleTest() {
        try {
            Log.i("Step 1:")
            MainScreen {
                loginActivityButton {
                    isVisible()
                }
            }
            Log.i("Step 1: Succeeded")
        } catch (e: Throwable) {
            Log.i("Step 1: Failed")
            throw e
        }
     anotherTest(){
      try {
       ...
       Log.i("Step 1:")
     } catch(e: Throwable){
      Log.i("Step 2: Failed")
    }
}

Works! Though with all the try catch blocks, the code will lose its readability and potentially, lead to flakiness.

In the Kaspresso world, Steps can be added in order to simplify code readability and more importantly, by keeping its flaky reduction rules. Steps can be used by declaring the run{} method:

fun test() {
       run {
           step ("Testing user registration auth") { ... }
           step ("Testing user login auth") { ... }
           ...
       }
   }

and then we can observe our crafted logs:

Complete automation with Codemagic CI/CD and uploading results to Allure Testops

We can further automate the process and upload test results to Allure Testops.

Thanks to Codemagic, we can automatically run UI tests, collect logs, and deploy results to Allure Testops on every change or daily.

Allure Testops is a DevOps ready test reporting platform where we can analyse test results through graphical reports and gathering results from servers in real-time while the build job is being executed. In order to achieve it with Codemagic, we will be utilising allurectl which is a command line wrapper of Allure Testops API. Allure Testops functions in two modes:

CI mode
Non-CI mode

allurectl detects automatically which one is in use through finding the required environment variables specified in Codemagic as explained below. So, let’s get the steps together for an easy flow of the process:

Sign up with Allure Testops.
Go to your profile, and create a secret token

As soon as your request for registration is approved by the Allure Testops team, you will receive an active endpoint to your work environment.
Create a project and fetch its ID.

The very vital step not to miss is to enable Allure support in our test code via withForcedAllureSupport. In order to enable it, we need to go through a couple of steps in our code:

Import com.kaspersky.components.alluresupport.withForcedAllureSupport
Add withForcedAllureSupportto TestCase() constructor which will look like:

class YOUR_ACTIVITY_TEST : TestCase(
    kaspressoBuilder = Kaspresso.Builder.withForcedAllureSupport()
)

After this, as soon as our tests are executed, there will be a directory created (sdcard/Documents/allure-results) and they will be pulled out of the device and uploaded to Allure Testops by Codemagic.

If you have not signed up with Codemagic and yet added your repo, you can follow the steps as explained in the Codemagic documentation here.

Go to your repo settings in the UI and you will find the Environment variables tab right next to codemagic.yaml and add your Allure secrets that we went through how to create them above.
Add the following lines in codemagic.yaml:

workflows:
  run-android-ui-test:
    name: Upload test results to Allue Testops
    instance_type: linux
    environment:
      groups:
        - allure_credentials
    scripts:
      - name: Set Android SDK location
        script: |
                        echo "sdk.dir=$ANDROID_SDK_ROOT" > "$CM_BUILD_DIR/local.properties"
      - name: Launch Emulator
        script: |
            cd $ANDROID_HOME/tools
            emulator -avd emulator &
            adb wait-for-device            
      - name: Install Allure CLI
        script: | 
            set -e
       wget https://github.com/allure-framework/allurectl/releases/download/2.2.1/allurectl_linux_amd64 -O ./allurectl
            chmod +x ./allurectl
      - name: Execute tests
        script: |
                        ./gradlew :app:connectedDebugAndroidTest
      - name: Pull test files from the device and upload to Allure Testops
        script: |
            set -e
            adb pull sdcard/Documents/allure-results
            ./allurectl upload allure-results

Note: When installing Allure CLI and building with a Mac machine, the platform must be changed in the command line to allurectl_darwin_amd64 for Mac Pro machines. In order to switch the machine type from Linux to Mac Pro in codemagic.yaml, changing instance_type value to mac_pro suffices.

Note: As the Apple Virtualization Framework does not support nested virtualization, Android emulators are not available with Apple silicon (M1 or M2) machines.

From this point on, Codemagic will start its automation process and print out the build/test logs:

A link to the Allure Testops environment where the test results can be accessed will be printed in the logs:

Worth pointing out that Codemagic has a possibility to schedule builds. It means that your tests will be run at a certain time you set up and you will already have had the test results in hand, and ready for review in Allue Testops. Let’s see how we can schedule a build:

Open your application in Codemagic.
Switch to the Scheduled builds tab and click the Add new schedule button.
Select the Branch and the Workflow to run.
In the Schedule for field, select the days you want to run the build.
Specify the start time (UTC) of the build by selecting a value from the At field. Note that the build may be delayed up to 15 minutes during peak hours.
Click Add schedule to save the schedule.

Checking test results in Allure Testops

Now, we can observe screenshots, videos, and customised test logs in the Allure Testops UI along with a graphical report of the test results.

Here Allure UI indicates how many tests passed, which ones failed:

In the screenshot below, we will find our passing tests along with the test logs, screenshots, and videos:

You will also have a chance to check failing test logs and which steps the issues occurred with:

Summary

We have gone through the steps regarding how Kaspresso manages to overcome the key issues of UI testing environments by allowing us to automate Android UI tests with flakiness protection and providing test results to Allure Testops platform to better control our manual, and automated testing through graphical analysis of test results including screenshots, videos, and all the logs. Codemagic took the code over, added an extra layer of automation, and completed the whole cycle of the automation process.

How to Test Native Features in Flutter Apps with Patrol and Codemagic

C💙demagic — Sun, 05 Nov 2023 13:03:36 +0000

This article was written by Kevin Suhajda and originally posted to the Codemagic blog.

"It's no use! I can't run an end-to-end test with Flutter's integration tests", exclaimed one of our customers about 9 months ago. I asked what the problem was and they explained that they were using Google Authentication for logging in and used the google_sign_in package but it wasn't possible to use Flutter's integration tests to interact with the login screens. I still didn't quite understand what the problem was, and then it clicked: this plugin uses native UI components which the integration tests don't work with.

I was quite disappointed that I couldn't offer a solution at the time and had to leave it at that. However, fast forward to today and an awesome new solution has presented itself called "Patrol" by LeanCode. I'm going to tell you all about it, but before we dive in let's just recap why it's important to run tests, what tools you had available until now, and then talk about how to get started with Patrol.

Why test Flutter apps anyway?

One of the main reasons development teams use Continuous Integration (CI) services like Codemagic is to get immediate feedback on the code they are committing to their repo. Tests can be run automatically as part of your pipeline to ensure a level of both quality and stability because bugs or issues can be caught early and rectified straight away. We always encourage customers to implement testing when setting up their workflows, but it's not uncommon to hear "We haven't got time to write tests". Hopefully, you're not in that boat, and use testing as part of your app development cycle to deliver great quality and bug-free apps!

What are the main automated ways to test Flutter apps?

There are four main testing methods that can be automated as part of your CI workflow. Testing is a topic unto itself, so I'll keep it brief, but using a combination of these testing methods will help you improve the quality of your app and catch problems sooner rather than later.

Firstly, there is "Unit testing" which is commonly used for testing your functions and methods in isolation to make sure they work as expected. Unit tests can also be written to make sure your business logic works in different scenarios without any unexpected results.

Next, we have Flutter "Widget tests" which allows you to test your UI components and make sure they render correctly and work as you expect.

Then there is "Integration testing" which is where you test if the units and components of your application work together as expected.

Finally, there is "End-to-End UI testing" where you test the application as if it were being used by a real user. In a CI workflow, this is usually automated using simulators or emulators to test different pathways through your app to make sure there aren't any issues after you make changes to your code.

This is where the customer I was talking about at the beginning was stuck because they couldn't run their End-to-End UI tests because it wasn't possible to log in to the app. At the time they tested a 'dev' version that bypassed the log-in part.

However, that's no longer required now that "Patrol" is available!

Enter, stage left, Patrol!

So first of all, what is Patrol? Well, I think the docs say it best:

Patrol is a new and open-source UI testing framework for Flutter developed by LeanCode. It builds on top of Flutter's existing test tooling to let you do things which were previously impossible. Patrol lets you access native features of the platform that the Flutter app is running on.

The most important part here is that it lets you access the native features of the platform your Flutter app is running on.

This means that you can now do things such as:

Interact with Permission Request dialogs to dismiss or accept requests.
Interact with WebViews.
Minimize and maximize your app.
Interact with authentication flows like Google or Apple authentication.
Interact with other native features such as opening the Notifications tray, pressing the Home button, turning Wi-Fi connectivity on or off, or changing the device to dark mode, etc.

Okay, this sounds great, but what's the catch?

Well, there isn't one! And what's more, it's not only free but also open source!

Moreover, Patrol also introduces 'custom finders' which gives you a more concise syntax for writing your tests. You can read more about them here.

Installing and setting up Patrol

To get started with Patrol you will need to install the CLI, add the Patrol dependency to your pubspec.yaml and set up some configurations in your iOS and Android projects.

LeanCode has created some great documentation here which takes you through the process for each platform which you can find here. Their step-by-step guide will take you through the setup for both iOS and Android.

If you run into any problems, the best place to get help is in the Patrol Community Discord server which you can join here.

If you find any bugs, then you can raise an issue here.

Writing native feature tests with Patrol

Now you are all set up, let's start testing some native features. To try it myself, I set up a simple Flutter app with an elevated button that when clicked opens a native alert dialog.

Clicking "OK" or "Cancel" simply dismisses the dialog.

Again, I would recommend using Patrol's own documentation which you can find here to get your first test file added.

So for my test, I wanted to click on the elevated button that has the text "Click me!". It's a standard Flutter widget so it can be tapped using the following Patrol finder:

await $('Click me!').tap();

The native dialog should then be displayed, so we can now start interacting with a native UI component. So let's add the native finder that will allow us to tap the "OK" button:

await $('Click me!').tap();
await $.native.tap(Selector(text: 'OK'));

That was easy! I also want to test the "Cancel" button, so let's tap on the "Click me!" button again and then tap on the native dialog's "Cancel" button by adding a couple more lines as follows:

await $('Click me!').tap();
await $.native.tap(Selector(text: 'OK'));

await $('Click me!').tap();
await $.native.tap(Selector(text: 'Cancel'));

Your completed test file should look like this:

import 'package:cmpatrol/main.dart';
import 'package:patrol/patrol.dart';

void main() {
  patrolTest(
    'Native tests',
    nativeAutomation: true,
    ($) async {
      await $.pumpWidgetAndSettle(const MyApp());

      await $('Click me!').tap();
      await $.native.tap(Selector(text: 'OK'));

      await $('Click me!').tap();
      await $.native.tap(Selector(text: 'Cancel'));

      await $('Click me!').tap();
      await $.native.tap(Selector(text: 'NO'));
    },
  );
}

You should now be able to run that test on your emulator or a real device using the command to launch the test. My integration test file was called "button_test" so I started the tests from Terminal as follows:

patrol test -t integration_test/button_test.dart

You'll see if your tests pass or fail directly in the Terminal. If the tests fail you will get a link to the full test report. Alternatively, If you are running your tests on Android like I did then this should you can access the report by clicking the index.html in the following directory:

./build/app/reports/androidTest/connected

You can experiment further with other native features such as opening the notifications tray, disabling the wifi, enabling dark mode, minimizing and maximizing the app:

// minimize app
await $.native.pressHome();

await $.native.openNotifications();

await $.native.disableWifi();

await $.native.enableDarkMode();

// maximize app
await $.native.openApp();

⚠️ Note that it is not possible to completely close your app and then re-open it because doing so would end the whole test and, therefore, make it fail.

Consult the Patrol documentation for more examples.

Using Patrol in your Codemagic workflows

To incorporate Patrol into your workflows, you'll first have to install the Patrol CLI on the build machine. This only takes a few seconds and once that's done, you can run your test script. Below is an example of how you would add these steps to the "scripts" section of your codemagic.yaml configuration file. I would recommend running the script to install the Patrol CLI as one of the first script steps and then you can run your Patrol tests either immediately after that or after any other tests you might also want to run beforehand.

Before running your Patrol tests you will need to start the emulator so we'll add a script to launch the emulator and wait for it to be fully booted. Note that the Android emulators are not available on machines using Apple Silicon M1 or M2 machines due to the Apple Virtualization Framework not supporting nested virtualization. Therefore, I would recommend using a linux instance when testing Android apps.

The scripts section of your codemagic.yaml should look something like this:

scripts:
  ...
  - name: Install Patrol CLI
    script: dart pub global activate patrol_cli
  - name: Launch Android emulator
    script: |
      cd $ANDROID_HOME/tools
      emulator -avd emulator &
      adb wait-for-device
  - name: Run tests with Patrol
    script: patrol test -t integration_test/your_test.dart
    ignore_failure: true
  ...

Showing Patrol test results in the Codemagic build logs

The Patrol test results are also available in JUnit XML format, which means they can be displayed in the build logs on the Codemagic build overview screen. You just need to add the test_report property pass in the path to the JUnit XML file that is generated. You can use the ignore_failure property with a boolean to control whether you want the rest of the workflow to continue running or not. If you want to upload your results to a test management system as described in the next section, you should set this to true.

Here's an example of what your script should look like:

scripts:
  ...
  - name: Run tests with Patrol
    script: |
      patrol test -t integration_test/your_test.dart
      test_report: build/app/outputs/androidTest-results/connected/*.xml
      ignore_failure: true
  ...

A failing test might look something like this:

Gathering the Patrol test report as a build artifact

One additional thing you might want to do is gather the test report output as a build artifact so you can view the full report should any errors occur. Doing this will make the report available for download as a zip file on the build overview screen in the "Artifacts" section on the left-hand side. The easiest way to do this is to copy the directory the report files are in to the directory Codemagic uses to export artifacts. There's a built-in environment variable called $CM_EXPORT_DIR that references this directory which you can use in your script.

The script to do this should be like this:

scripts:
  ... 
  - name: Export Patrol test report
    script: | 
      cp  -r build/app/reports/androidTests/connected $CM_EXPORT_DIR/report
  ...

Conclusion

Patrol has finally overcome the problem of running UI and integration tests that involve native features. It's now possible to test native features and interact with authentication flows, native dialogs, and even toggle native features like wifi, cellular, dark mode, and even minimize your app and maximize it. Additionally, it's both free and open source and provides a solution to a real problem that's been around since Flutter was launched. What's more, it's straightforward to add and use it in your Codemagic workflows. If you want to support the great work LeanCode is doing, give Patrol a like on pub.dev here and give the Patrol GitHub repository a star here.

This article is written by Kevin Suhajda, Head of Solutions Engineering at Codemagic. You can find Kevin on X, GitHub, and LinkedIn.

Introducing the official Codemagic integration for Runway

C💙demagic — Tue, 31 Jan 2023 13:15:23 +0000

This post is written by Gabriel Savit and originally posted to Codemagic blog.

Codemagic is now officially integrated with Runway, the DevOps platform for mobile. But wait, you might be wondering, isn't Codemagic already that as a CI/CD for mobile? Aren't the two services interchangeable? In fact, it's quite the opposite --- they're powerfully complementary.

By pairing the flexibility and ease that Codemagic brings to your build pipeline with Runway's ability to pull the rest of your toolchain and team into a unified control center, you'll be set up for success as you scale your mobile practice. Let's take a look at how it works.

Codemagic: An easy way to automate building and distribution

Say you have an app and you're tired of manually building, code signing, and releasing it. Naturally, you look for a CI/CD solution and end up building a Codemagic pipeline that effortlessly churns out signed builds of your app across any and all platforms you support -- Android, iOS, macOS, Windows, etc.

Maybe you have different flavors configured, from dev builds to poke at while you work on new features to release candidates that your team can run regression on and prepare for release. You may even be taking advantage of Codemagic features that allow you to not only build and sign your artifacts but even distribute new builds automatically to App Store Connect and Play Console. You can literally release app updates to users with a single click --- CI/CD at its finest!

If you're new to CI/CD, check out this guide on getting started with CI/CD for mobile

Now imagine you're on a team of more than one person. Can you ship updates with a click of a button? You have other engineers around you who might need to finalize their work for the release. You have QA engineers who need to complete testing and sign off on a final RC. OK, that's still possible with Codemagic and some good practices around working with pull requests, but it's already become more complicated.

Add to the mix PMs who need to plan ahead and understand what will be shipping and when. You have customer service and ops folks who need to know about new versions before they start receiving a flood of feedback from users about it. You have security and compliance reviewers who need to apply their rubber stamp. You have managers and other stakeholders who care about what you're up to and need to weigh in. The list goes on. As your team and product grow, the number of parties involved --- and the number of steps from build to release (and post-release) --- increase. And that's where Runway comes in.

Runway: A home to get your entire mobile org on the same page

Runway integrates with your build pipeline (Codemagic, in this case) and the rest of your toolchain to give your entire mobile org a home. By keeping everyone --- and we mean all stakeholders, not only the technical ones --- on the same page and automating all sorts of tasks that exist outside the realm of CI, Runway ensures your releases stay as streamlined as possible, even as your team and product grow. Instead of bouncing between your Codemagic dashboard and 10 other browser tabs and endlessly pinging people back and forth over Slack, everyone can leverage Runway to see exactly where things stand during your release cycles and collaborate on releases together.

For maximum visibility across the team, Runway surfaces build data alongside info on feature work from version control and project management tools, stability and health metrics from crash reporting and product analytics, and even info on the state of your feature flags.

Runway allows you to release hands-free from kickoff to submission to release --- but not without the input and signoffs needed from various team members. Combine scheduled automations for branch cuts, version bumps, rollouts, and much more with a robust and customizable system of checklist items and approval gates to ensure you don't sacrifice quality even as you move to a level of automation you haven't been able to achieve before.

Runway's deep integrations with App Store Connect and Play Console allow for a saner --- and safer --- publishing experience. Instead of constant roundtrips between engineers, PMs, and marketing folks just to get store copy updated, you can give responsible parties scoped access within Runway to update and validate metadata. For cross-platform teams, this is an especially big win --- similar to how keeping your different platforms' build pipelines nicely consolidated in Codemagic reduces overhead, Runway's unified and platform-agnostic treatment of the stores will save your team context switching and make things more approachable for non-technical folks.

Your team's job isn't over once a build lands in the store: Running a successful rollout is a demanding and critical part of the process, and Runway helps with this stage too. With disparate signals of health pulled together from across your stack --- including crash reporting, product analytics, and even user reviews --- your team gets a single source of truth to refer to when making the call to halt or continue a rollout. You can configure granular thresholds that define what "healthy" looks like for your team, then tie those to alerting or even "halt" and "accelerate" automations.

How to integrate Codemagic with Runway

It takes minutes to integrate Codemagic with Runway. After heading to runway.team to sign up for free, you'll be guided through a simple onboarding flow. When you're on the CI/CD integration step, select the Codemagic option and drop your Personal Access Token in there. (To generate a token, in your Codemagic account, navigate to Teams > Personal Account > Integrations.) Runway is SOC 2 Type 2 certified --- your secrets are safe with them! You'll be prompted to select the Codemagic workflows that correspond to your different flavors of builds (where applicable: dev builds, RCs, and release builds), and that's it! You're ready to streamline and democratize releases and rollouts with the combined power of Codemagic and Runway.

Once Runway and Codemagic are integrated, you get to decide how you want them to work together. You can continue triggering builds from Codemagic or take advantage of Runway's scheduled release automations to kick off timed RCs for you. Alternatively, you can trigger builds in Runway manually along with extra context from the rest of your toolchain. Everything to do with building artifacts stays in Codemagic, and you don't have to touch anything in your workflows; Runway will plug and play with your current processes and practices.

However streamlined and powerful your Codemagic pipelines are, you may find the dream of one-click deployment slipping away as your team and product grow and your overall release process gets more complex. By integrating Codemagic in Runway, you can get everyone back on the same page and keep shipping smoothly.

And there's more good news: Codemagic and Runway are both free to start with. So, if you haven't done so already, sign up for Codemagic and head to runway.team to get started for free -- and use both services to create a fully integrated DevOps home for your apps.

Creating WebView Content Blockers with Flutter InAppWebView

C💙demagic — Mon, 09 Jan 2023 11:32:10 +0000

Written by Lorenzo Pichilli and originally posted to Codemagic blog

In this article, we are going to learn how to create a custom Content Blocker for our WebView instances using the flutter_inappwebview plugin.

Read this article to get started with Flutter InAppWebView

Content Blockers are usually used for blocking ads, but you can also use them to block any other content. Blocking behaviors include hiding elements, blocking loads, and, on iOS and macOS, stripping cookies from WebView requests.

Keep in mind that, in general, Content Blockers cannot achieve the same level of functionality as specialized extensions such as AdBlock or AdBlock Plus. Content Blockers are a set of rules that never receive any callbacks or notifications back from the WebView when it finds content it needs to block.

Through the contentBlockers property of the InAppWebViewSettings class, we can define a list of ContentBlocker instances that the WebView will use.

The ContentBlocker class

We define content-blocking behavior in the ContentBlocker class. Each one contains an action property and a trigger property. The action tells the WebView what to do when it encounters a match for the trigger. The trigger tells the WebView when to perform the corresponding action.

Here is a basic example:

initialSettings: InAppWebViewSettings(contentBlockers: [
 ContentBlocker(
   trigger: ContentBlockerTrigger(
     urlFilter: ".*",
     resourceType: [
       ContentBlockerTriggerResourceType.IMAGE,
       ContentBlockerTriggerResourceType.STYLE_SHEET
     ]
   ),
   action: ContentBlockerAction(
     type: ContentBlockerActionType.BLOCK
   )
 )
]),

In this example, the ContentBlocker blocks the loading of every image and stylesheet for every URL.

Add triggers to your Content Blocker

A trigger must define the required urlFilter property, which specifies a regular expression as a string to match the URL against. The other properties are optional --- they modify the behavior of the trigger. For example, you can limit the trigger to specific domains or have it not apply when the WebView finds a match for a specific domain.

Here is an example of a Content Blocker with a trigger for image and style sheet resources that the WebView finds on any domain except those specified:

initialSettings: InAppWebViewSettings(contentBlockers: [
 ContentBlocker(
   trigger: ContentBlockerTrigger(
     urlFilter: ".*",
     resourceType: [
       ContentBlockerTriggerResourceType.IMAGE,
       ContentBlockerTriggerResourceType.STYLE_SHEET
     ],
     unlessDomain: ["example.com", "github.com", "pub.dev"]
   ),
   action: ContentBlockerAction(
     type: ContentBlockerActionType.BLOCK
   )
 )
]),

For deeper trigger customization, you can use the other properties of ContentBlockerTrigger:

urlFilterIsCaseSensitive: If the URL matching should be case-sensitive. By default, it is case insensitive.
resourceType: A list of "ContentBlockerTriggerResourceType" representing the resource types (how the browser intends to use the resource) that the rule should match. If it is not specified, the rule matches all resource types.
ifDomain: A list of strings matched to a URL's domain; it limits action to a list of specific domains. Values must be lowercase ASCII or Punycode for non-ASCII characters. Add ` in front to match the domain and subdomains. It can't be used with unlessDomain`.*
unlessDomain: A list of strings matched to a URL's domain; acts on any site except domains in a provided list. Values must be lowercase ASCII or Punycode for non-ASCII. Add ` in front to match the domain and subdomains. It can't be used with ifDomain`.*
loadType: A list of ContentBlockerTriggerLoadType that can include one of two mutually exclusive values. If not specified, the rule matches all load types. ContentBlockerTriggerLoadType.FIRST_PARTY triggers only if the resource has the same scheme, domain, and port as the main page resource. ContentBlockerTriggerLoadType.THIRD_PARTY triggers if the resource isn't from the same domain as the main page resource.
ifTopUrl: A list of strings matched to the entire main document URL; it limits the action to a specific list of URL patterns. Values must be lowercase ASCII or Punycode for non-ASCII characters. It can't be used with unlessTopUrl.
unlessTopUrl: An array of strings matched to the entire main document URL; it acts on any site except URL patterns in the provided list. Values must be lowercase ASCII or Punycode for non-ASCII characters. It can't be used with ifTopUrl.
loadContext: An array of strings that specify loading contexts.
ifFrameUrl: A list of regular expressions to match iframes' URL against.

Check the code documentation for each specific property to find out which platform supports that feature.

Add actions to your Content Blocker

When a trigger matches a resource, the WebView evaluates all the triggers and executes the actions in order.

Group the rules with similar actions together to improve performance. For example, first specify rules that block content loading followed by rules that block cookies.

There are only two valid properties for actions: type and selector. An action type is required.

If the type is ContentBlockerActionType.CSS_DISPLAY_NONE, a selector is required as well; otherwise, the selector is optional.

Here is a simple example:

initialSettings: InAppWebViewSettings(contentBlockers: [
 ContentBlocker(
   trigger: ContentBlockerTrigger(
     urlFilter: "https://flutter.dev/.*",
   ),
   action: ContentBlockerAction(
     type: ContentBlockerActionType.CSS_DISPLAY_NONE,
     selector: '.notification, .media, #developer-story'
   )
 )
]),

Valid types are:

BLOCK: Stops the loading of the resource. If the resource was cached, the cache is ignored.
BLOCK_COOKIES: Strips cookies from the header before sending it to the server. This only blocks cookies that are otherwise acceptable to WebView's privacy policy. Combining BLOCK_COOKIES with IGNORE_PREVIOUS_RULES doesn't override the browser's privacy settings.
CSS_DISPLAY_NONE: Hides elements of the page based on a CSS selector. A selector field contains the selector list. Any matching element has its display property set to none, which hides it.
MAKE_HTTPS: Changes a URL from http to https. URLs with a specified (nondefault) port and links using other protocols are unaffected.
IGNORE_PREVIOUS_RULES: Ignores previously triggered actions.

Check the code documentation for each specific type to find out which platform supports it.

Creating a simple ad blocker

Let's create a simple ad blocker using what we have learned.

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_inappwebview/flutter_inappwebview.dart';

Future main() async {
 WidgetsFlutterBinding.ensureInitialized();
 if (!kIsWeb &&
     kDebugMode &&
     defaultTargetPlatform == TargetPlatform.android) {
   await InAppWebViewController.setWebContentsDebuggingEnabled(kDebugMode);
 }
 runApp(const MaterialApp(home: MyApp()));
}

class MyApp extends StatefulWidget {
 const MyApp({Key? key}) : super(key: key);

 @override
 State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
 final GlobalKey webViewKey = GlobalKey();

 // list of ad URL filters to be used to block ads from loading
 final adUrlFilters = [
   ".*.doubleclick.net/.*",
   ".*.ads.pubmatic.com/.*",
   ".*.googlesyndication.com/.*",
   ".*.google-analytics.com/.*",
   ".*.adservice.google.*/.*",
   ".*.adbrite.com/.*",
   ".*.exponential.com/.*",
   ".*.quantserve.com/.*",
   ".*.scorecardresearch.com/.*",
   ".*.zedo.com/.*",
   ".*.adsafeprotected.com/.*",
   ".*.teads.tv/.*",
   ".*.outbrain.com/.*"
 ];

 final List<ContentBlocker> contentBlockers = [];
 var contentBlockerEnabled = true;

 InAppWebViewController? webViewController;

 @override
 void initState() {
   super.initState();

   // for each ad URL filter, add a Content Blocker to block its loading
   for (final adUrlFilter in adUrlFilters) {
     contentBlockers.add(ContentBlocker(
         trigger: ContentBlockerTrigger(
           urlFilter: adUrlFilter,
         ),
         action: ContentBlockerAction(
           type: ContentBlockerActionType.BLOCK,
         )));
   }

   // apply the "display: none" style to some HTML elements
   contentBlockers.add(ContentBlocker(
       trigger: ContentBlockerTrigger(
         urlFilter: ".*",
       ),
       action: ContentBlockerAction(
           type: ContentBlockerActionType.CSS_DISPLAY_NONE,
           selector: ".banner, .banners, .ads, .ad, .advert")));
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
       appBar: AppBar(
         title: const Text("Ads Content Blocker"),
         actions: [
           TextButton(
             onPressed: () async {
               contentBlockerEnabled = !contentBlockerEnabled;
               if (contentBlockerEnabled) {
                 await webViewController?.setSettings(
                     settings: InAppWebViewSettings(
                         contentBlockers: contentBlockers));
               } else {
                 await webViewController?.setSettings(
                     settings: InAppWebViewSettings(contentBlockers: []));
               }
               webViewController?.reload();

               setState(() {});
             },
             style: TextButton.styleFrom(foregroundColor: Colors.white),
             child: Text(contentBlockerEnabled ? 'Disable' : 'Enable'),
           )
         ],
       ),
       body: SafeArea(
           child: Column(children: <Widget>[
         Expanded(
           child: Stack(
             children: [
               InAppWebView(
                 key: webViewKey,
                 initialUrlRequest:
                     URLRequest(url: WebUri('https://www.tomshardware.com/')),
                 initialSettings:
                     InAppWebViewSettings(contentBlockers: contentBlockers),
                 onWebViewCreated: (controller) {
                   webViewController = controller;
                 },
               ),
             ],
           ),
         ),
       ])));
 }
}

Using these rules will prevent a bunch of ads from appearing, such as Google Ads.

Click the Disable/Enable button to disable or enable the ad blocker feature.

Conclusion

Content Blockers allow us to write performant rules for blocking content in the WebView while respecting the user's privacy.

Full project code is available on GitHub.

That's all for today!

Are you using this plugin? Submit your app through the Submit Application page and follow the instructions.

Check the Showcase page to see who's already using it!

This project follows the all-contributors specification (contributors). I want to thank all the people who are supporting the project in any way. Thanks a lot to all of you! 💙

Migrating a Flutter app to Material 3

C💙demagic — Fri, 16 Dec 2022 08:33:53 +0000

This article is written by Taha Tesser and originally posted to Codemagic blog.

At Google I/O 2021, Google announced the next evolution of Material Design, Material You, along with Android 12. The Material Design system's biggest overhaul yet brought redesigned components, new colors, a wide range of shapes, simplified typography, new elevation, better accessibility, and many other tweaks. With this update, Flutter apps can have a consistent design across multiple platforms. Material Design 3 (the technical name for Material You) is sometimes referred to as Material 3 or simply M3 for the sake of brevity, similarly to how Material 2 is referred to as M2.

In this article, we will discuss everything that you, as a Flutter developer, should know about migrating your Flutter app to Material 3.

How to enable Material 3 in Flutter

Since the announcement of Material 3, Flutter has received a bunch of updates to support it, including support for new typography, shapes, elevation, updated widgets, and new M3 widgets. Most of the M3 components are available in Flutter. You can track the few remaining widgets that are yet to receive Material 3 support and the progress of the Material 3 implementations in Flutter for them in the Bring Material 3 to Flutter issue.

Currently, Material 3 changes are only available when opting in, so you'll need to use the useMaterial3 flag on ThemeData to enable Material 3 support. (This might change in the future, so be sure to check out the Flutter website for updated documentation. We'll also update this article soon after the change takes place.)

To use Material 3 in Flutter instead of Material 2, specify the following:

theme: ThemeData(
  useMaterial3: true,
),

What's new in Material Design 3 for Flutter?

Material 3 updates brought revamped typography, an improved ColorScheme (including the ability to generate a full ColorScheme from a given seed color), updated elevation, a beautiful Android 12 overscroll stretch effect, and a new ink ripple. A bunch of Material widgets, such as AppBar, FloatingActionButton (FAB), ElevatedButton, OutlinedButton, IconButton, and Card, have been updated to support Material 3 design. There are also new Material 3 widgets, such as NavigationBar, NavigationDrawer, andSegmentedButton, some new M3-style buttons, such as FilledButton and FilledButton.tonal, and a whole lot more.

If you simply migrate the Flutter starter app to Material 3, you'll already notice some changes: The AppBar has no elevation or background color, and the FAB has a rounded rectangular shape instead of the more familiar circular shape.

For a complete overview of M3 in Flutter, check out the official Material 3 Demo.

In the following sections, I'll explain some of the key changes and tweaks you might want to make in your app to support Material 3.

The key changes in Material 3 are:

Dynamic color
Typography
Shapes
Elevation

Let's go through each of them in detail.

Dynamic color

Let's start with Dynamic color, which enables you to apply consistent colors across your app. It contains some key colors and neutral colors related to separate tonal palettes. Colors from these tonal palettes are applied across the UI. Use the Material Theme Builder web app or the Figma plugin to visualize the dynamic color for your app and create a custom color scheme.

Flutter uses a low-level material_color_utilities package that contains algorithms to create a Material Design 3 color system. You can create color schemes for your apps using dynamic_color based on a platform's implementation of dynamic color.

The easiest way to create an M3 ColorScheme is by providing a seedColor color in the app's theme.

For instance, add colorSchemeSeed: Colors.green to the starter app. Notice that the FAB is now using a lighter green color instead of the light purple from the default color scheme.

Adding colorSchemeSeed when primarySwatch is present will throw assertion : 'package:flutter/src/material/theme_data.dart': Failed assertion: line 477 pos 12: 'colorSchemeSeed == null || primarySwatch == null': is not true.

To fix this, remove primarySwatch: Colors.blue, from the starter app's theme.

    ///...
    primarySwatch: Colors.blue,
  useMaterial3: true,
  colorSchemeSeed: Colors.green,
),

Here, I've created an example that shows all the colors from the M3 ColorScheme. On the left, we have the default ColorScheme, which is available when setting the useMaterial flag to true. And on the right, we're using the custom ColorScheme, generated using the colorSchemeSeed parameter, which takes a seed color or key color to generate a full Material 3 ColorScheme.

Default M3 `ColorScheme`	Custom M3 `ColorScheme`

You can take this to the next level using both flex_seed_scheme, which allows you to create a more flexible version of Flutter's ColorScheme.fromSeed, and flex_color_scheme, which ensures UI components get themed completely by the color schemes and custom colors you provide.

Typography

Material 3 simplified the typography naming by splitting the typescales into five key groups:

Display
Headline
Title
Body
Label

The role of each key group is more descriptive, and it's much easier to use different sizes in a particular typography group, e.g., BodyLarge, BodyMedium, and BodySmall instead of bodyText1, bodyText2, and caption. This helps when implementing typography for devices with different screen sizes.

The scaling of the typography has become consistent across the groups. Here is a comparison between the M3 and M2 typescales:

Elevation

In Material 2, each elevated component gets a shadow. The higher the elevation, the bigger the shadow. Going even further, Material 3 introduces a new surfaceTintColor color property. When applied to elevated components, the surface of the elevated components gets this color, and its intensity depends on the elevation value.

Source: https://m3.material.io/styles/elevation/overview

The surfaceTintColor property is added to all the elevated widgets in Flutter, along with the elevation and shadow properties.

Try out this Material elevation demo: Turn off shadows by tapping on the icon button in the top right and switch between M2 and M3. Notice that elevated surfaces take on the surfaceTintColor color, which makes them visible even when no shadow is provided.

When comparing the M2 AppBar with the M3 AppBar in the starter app, you'll notice that the AppBar doesn't have a default elevation value, surfaceTintColor color, or shadow color.

M2 `AppBar`	M3 `AppBar`

Providing a custom elevation value shows the default surfaceTintColor color in effect and applies the theme's shadow color to the AppBar so that the AppBar casts a shadow as well.

Note: This AppBar.elevation property is different from the new AppBar.scrolledUnderElevation property, which is only in effect when the content is scrolled underneath the AppBar. Learn more about this further below.

  appBar: AppBar(
    title: Text(widget.title),
    elevation: 4,
  ),

  appBar: AppBar(
    title: Text(widget.title),
    elevation: 4,
    shadowColor: Theme.of(context).shadowColor,
  ),

Shapes

Material 3 offers a wider range of shapes, including squared, rounded, and rounded rectangular shapes. The FAB, which was previously circled, now has a rounded rectangular shape, and material buttons went from rounded rectangular to pill shaped. Widgets like Card, Dialog, and BottomSheet are also more rounded in M3.

Migrating from Material 2 to Material 3

Here, I'll walk you through the process of migrating a Material 2 demo app to Material 3.

This demo app contains some Material 2 Flutter widgets. Some of them will be updated when enabling M3, and some of the M2 widgets can be replaced with new M3-style widgets. For example, ElevatedButton can be replaced with the new FilledButton to preserve the visual design, and BottomNavigationBar can be replaced with the new M3-style NavigationBar widget. The demo app also contains some customization needed in an M2 app for some widgets to stack well. For instance, InputDecorationTheme applies a custom fillColor so that the TextField is visible when placed in the AppBar in an M2 app.

  theme: ThemeData(
    colorScheme: const ColorScheme.light().copyWith(
      primary: Colors.green[700],
      secondary: Colors.green[700],
    ),
    inputDecorationTheme: InputDecorationTheme(
      filled: true,
      fillColor: Theme.of(context).colorScheme.onPrimary,
      hintStyle: TextStyle(
        color: Colors.green[700],
      ),
    ),
    floatingActionButtonTheme: const FloatingActionButtonThemeData(
      foregroundColor: Colors.white,
    ),
  ),

One of the best things about Material 3 is that widgets use consistent colors, and the overall theming experience has also been improved. For example, in the demo, we used a custom InputDecorationTheme to make the TextField visible in the dark green AppBar. But when migrating to M3, we can remove this, and the TextField will be visible without any customization.

In the demo, remove the existing colorScheme property, inputDecorationTheme, and floatingActionButtonTheme. Then add the following lines:

    theme: ThemeData(
    useMaterial3: true,
    colorSchemeSeed: Colors.green[700]
  ),

We now have a new beautiful ColorScheme that's applied to all the components in the demo app. Each UI component is using specific tonal palette colors. TextField uses an appropriate fillColor, and cards have the default greenish surfaceTintColor.

IconButton now supports the ButtonStyle property, which you can use to customize the IconButton to get an M3 visual and a new selected state. Let's update the IconButton from the AppBar in the demo app to an M3 filled-style icon button.

Check out https://api.flutter.dev/flutter/material/IconButton-class.html and https://m3.material.io/components/icon-buttons/overview to learn more.

Here's my favorite part: When you scroll through the content, the AppBar's default scrollUnderElevation kicks in. Notice that the surfaceTintColor intensified when we're scrolling, and as a result, the AppBar changes color. This is because the AppBar is elevated based on the scrollUnderElevation value when the content is scrolled underneath. List views send scroll notifications to the AppBar that they're being scrolled beneath.

You can implement AppBar.notificationPredicate and listen to scroll notifications from a nested list view for more complex layouts.

The Material 3 AppBar is elevated when content is scrolled underneath the AppBar. You can adjust this elevation using the new scrolledUnderElevation property.

Check out the official scrolledUnderElevation code sample I've added in the AppBar docs.

Execute flutter create --sample=material.AppBar.2 mysample to create a local project with this code sample.

The migration process for our demo app isn't complete yet. It still uses the M2-style BottomNavigationBar, so let's replace it with the new M3-style NavigationBar widget. It's taller and easier to interact with, and it isn't elevated.

M2-style `BottomNavigationBar`	M3-style `NavigationBar`

Check out the documentation for the NavigationBar class for more details.

Tapping on the FAB on the home screen opens a dialog with a rounded rectangular shape. Since the dialog is elevated by default, we can see that the default surfaceTintColor has been applied and the content padding has been slightly modified, as it has an optional icon property.

Check out the documentation for the showDialog function for more details.

Now, navigate to the details page by tapping on one of the list items. This page contains a SliverAppBar with expandedHeight and flexibleSpace to make the app bar title large and the SliverAppBar collapsable. This can be replaced with the new SliverAppBar.large, which supports large titles and is also collapsable. When doing so, we can remove expandedHeight and flexibleSpace.

    SliverAppBar.large(
    title: const Text('Lorem Ipsum'),
  ),

For the new M3 AppBar variants, which support medium and large titles, use the new SliverAppBar.medium and SliverAppBar.large.

Check out the documentation for the SilverAppBar.medium constructor and SilverAppBar.large constructor for more details.

Here are the screenshots of the final M3 demo.

The source code for all the demos is available on GitHub.

Conclusion

Material 3 makes it possible to create beautiful, personalized, and accessible designs. When combining Material 3 with Flutter, you can create a consistent and unified UI experience across mobile, web, and desktop platforms. It makes it much easier to create complex algorithmic color schemes and scale typography for devices with varying screen sizes. Furthermore, accessibility has been improved, and visual feedback is clearer.

The Flutter team has been working hard on adding full support for Material 3 to Flutter. As demonstrated above, you can already migrate your existing Material 2 app to Material 3. If you use some widgets that are yet to receive Material 3 support, you can track their progress in the Material 3 issue.

10 reasons to choose Codemagic CI/CD in 2022–2023

C💙demagic — Mon, 21 Nov 2022 08:33:46 +0000

Codemagic is a CI/CD (continuous integration and continuous delivery) tool that is best suited for mobile developers. It can help you speed up your release cycle, get actionable feedback faster, and forget about the pain of manually submitting your apps to stores.

Codemagic is evolving fast: This year, we added M1 Mac mini build machines and changed our pricing so that everyone can afford to use the friendliest mobile DevOps tool on the market.

Why using a CI/CD tool is especially important for mobile app development

Mobile application development has come a long way over the last decade, and users have developed high expectations for the look, feel, and functionality of the apps they use. They expect apps to work smoothly, be available across multiple platforms, look nice, and be intuitive.

All of that requires a fast software development life cycle so that you can quickly test concepts, fix issues, and iterate in order to improve the quality of your app and release new features. Building such a release cycle is impossible without adhering to DevOps best practices, which include automating a lot of tasks and improving collaboration between team members by building a continuous integration and continuous delivery pipeline for your app.

For continuous integration, you'll need a version control system such as GitLab, GitHub, or Bitbucket (Codemagic supports all of these version control systems, by the way) for your source code. You will also require a tool that will grab the source code from your repository, run automated tests, and build it into an actual working app.

For continuous delivery, you'll usually use the same tool to automatically publish your app to the app stores, such as Google Play and Apple App Store. This means that just committing your code with a change to a repository or approving a pull request is enough to trigger a pipeline that will automatically build, test, and deploy your app with that change and enable users to access it immediately.

Tools that carry out the above processes are called continuous integration and continuous delivery services, or CI/CD for short.

There are many CI/CD tools available in the market, from universal solutions such as Jenkins or GitHub Actions to hosted mobile-first cloud services such as Codemagic, Bitrise, or Appcircle. How do you know which CI/CD service is best for building mobile apps?

Download our ebook "Continuous Integration and Delivery for Mobile Apps"

Below, you'll find ten reasons why you should consider using Codemagic in 2022 (and 2023) for your mobile app development.

1. Never overspend

Codemagic has a unique billing model that helps you save money by adapting to your needs.

Firstly, you get 500 free build minutes per month. If you need more, you only pay for the build minutes you have used at the end of the month.

And if your usage exceeds 50 build-machine hours per month, you won't have to pay more than $299 a month --- Codemagic fixes the costs for you while providing unlimited build minutes. This is done automatically, so there's no need to worry about optimizing the spend --- we'll optimize it for you.

Finally, if you're sure you will be building extensively every month, you can choose the annual plan with the same unlimited usage but at a 20% discount so that you pay $2,870 per year of unlimited use.

Learn more about Codemagic's pricing

2. Build with Apple silicon machines

This winter, Codemagic introduced Apple M1 build machines, which recently replaced the old Intel Mac minis as our default VMs (even though you can still use Intel machines if you need to). That means that you can build with M1s even on a free plan. Once you exceed the limit and need to pay for build minutes, Codemagic still offers M1 Mac minis at a fraction of the price of what other mobile CI/CD services offer.

Read how Codemagic managed to lower its pricing while improving its infrastructure

3. Enjoy good performance

There are many benefits of using Apple silicon build machines in continuous integration/continuous delivery pipelines. The improvements in build speed that they provide are just amazing. Building with other Codemagic machines is also quite fast, primarily because they have all the necessary tools, such as Flutter SDK, Android Studio, Xcode, Unity Editor, and many more preinstalled.

You can find the build machine specs and information about preinstalled software via the links below:

Learn more about how Mac M1 build machines increase the build speed of Flutter apps

4. Forget about maintaining infrastructure

Perhaps even more importantly, you don't need to worry about maintaining infrastructure and updating dependencies. We always keep all the software up to date so that you don't need to worry about it --- you can just use it, and we'll take care of the maintenance. You don't need to update your environment. We've got you covered, from the latest Xcode versions (actually, we have several versions to choose from) to the latest Flutter versions.

And with Codemagic, there's no such thing as "our build server is broken" anymore --- there are always build machines in the pool ready to build your apps.

5. Embrace flexibility with the visual Workflow Editor or YAML Infrastructure as Code

Codemagic offers two different approaches to building CI/CD pipelines, and you can choose the one that suits you best. With our visual Workflow Editor, you can follow a very intuitive (yet well-documented) process to build a CI/CD pipeline with just a few clicks.

Alternatively, you can utilize the power IaC (Infrastructure as Code) with codemagic.yaml. This method gives you infinite options for customizing your pipeline and enables you to set up new pipelines within a few minutes by simply copying and pasting the contents of your codemagic.yaml file from the previous pipeline.

Choose whichever approach you like best. What's even better is that you can start with the simple Workflow Editor and then export your configuration as a codemagic.yaml file to continue tweaking it.

Learn how to get started with the Workflow Editor and codemagic.yaml

6. Build white-label apps at scale

Have you built a successful app for one service and want to sell it to another service with minor tweaks? This is called white labeling, and Codemagic supports it at no additional cost. No matter which white-labeling approach you choose or whether you're using Flutter, React Native, or another framework, Codemagic can help you build all flavors of your white-label app with a single commit and distribute them all to the stores using their respective accounts.

Codemagic speeds up release cycles for your white-label applications, helping you make sure your clients are happy with your app.

Learn more about white labeling apps with Codemagic

7. Build for all platforms

One of the core benefits of frameworks such as Flutter, React Native, and Unity is their support for many platforms, and Codemagic allows you to enjoy this support at its fullest.

Codemagic has Linux, Windows, and Mac build machines. (The latter even come with two different architectures --- x86/x64 and ARM64.) We allow you to build apps for the following platforms:

Android
iOS
Windows
Linux
Mac
Web
Standalone Oculus VR headsets

Codemagic can not only build your app for all these platforms but also help you automate deployment to the respective stores.

8. Enjoy tight integrations with App Store and Google Play

Codemagic is tightly integrated with both App Store Connect and the Google Play Store. This means that setting up automated deployment is easier with Codemagic. It can help you with steps such as code signing, automatic app versioning, distributing apps to TestFlight or Google Play Beta, and more.

Also, did you know that publishing to the App Store with Codemagic doesn't consume your build minutes? Well, now you do.

Learn more about Codemagic's App Store Connect integration

9. Use integrations with various test automation tools

Codemagic has quite an extensive list of integrations that are documented and ready for you to try out. Among those integrations, we'd like to specifically highlight tools that allow you to automate testing, including Katalon (one of the most powerful engines for no-code test automation), Kobiton (for testing on real devices), Sofy (for low-code test automation), and Firebase Test Lab (for cloud-based testing for Android and iOS apps on various devices).

And there are many more integrations that can help you improve testing, code coverage, and more.

Get acquainted with Codemagic's integrations

10. Get help from our very responsive support

With some SaaS companies, it can be difficult and time-consuming to reach support, and they often don't really solve your issue. Codemagic is different: You can contact our support using the in-app chat (for paying customers) or on GitHub Discussions (for everybody). We strive to provide help within 24 hours, and it usually takes just a few hours.

We also offer free onboarding assistance, and our DevOps engineers are here for you to get the most out of Codemagic and build better pipelines.

Conclusion

Choosing the right CI/CD for mobile app development might seem like a complicated task, but it essentially boils down to choosing the solution with the best parameters, such as:

Ease of use
Cost
Features and integrations
Build speed

Codemagic excels at all of the above. It is easy to set up and use, is much more affordable than its competitors, is feature-rich, and has a lot of useful integrations. And finally, Codemagic's virtual machines are really, really fast.

How to build a Chrome extension with Flutter Web

C💙demagic — Tue, 01 Nov 2022 14:01:18 +0000

This article is written by Hrishikesh Pathak and originally posted to Codemagic blog.

What is a Google Chrome extension?

Google Chrome is the most popular web browser in the world. Chrome extensions are small programs that extend Chrome's functionality. Google Chrome has a standardized API through which extensions can perform various tasks in the browser.

In our daily lives, we use browser extensions for various tasks, like ad and tracker blocking, grammar correction, and translation. These extensions are made using JavaScript and use the Chrome extension API to interact with the browser. Since Flutter Web projects are compiled in JavaScript, we can build a Chrome extension with Flutter with some small tweaks.

In this tutorial, we are going to learn how to make a Chrome extension using Flutter Web. We will explore different use cases, tweaks, and build commands to get the best result. To get the most out of this guide, make sure to follow it to the end.

The final result of the tutorial will be a Flutter application that runs as a Chrome extension. It will look like this.

To create a Chrome extension with Flutter, we'll need to go through the following steps:

Configure the manifest.json file for Flutter Web
Deal with Content Security Policy to make our Chrome extension actually work in the browser environment
Configure Flutter Web
Add optional background scripts to our Flutter Chrome extension
Build our Flutter Web project
Build a Codemagic pipeline to build and deploy our Chrome extension to Chrome Web Store

Add a new manifest.json file

If you look in the web/ folder in a default Flutter project, you will see a manifest.json file. This file includes all the application configuration and aims to provide Progressive Web App (PWA) capabilities to our Flutter web application.

To learn more about building PWAs with Flutter, take a look at this blog post.

Google Chrome also requires a manifest.json file to register an extension. Therefore, to make our extension work, delete the contents inside the manifest.json file, and substitute them with the following code.

{
  "name": "Chromextension",
  "description": "A Flutter chrome extension",
  "version": "0.0.0.1",
  "manifest_version": 3,
  "content_security_policy": {
    "extension_pages": "script-src 'self' ; object-src 'self'"
  },
  "action": {
    "default_popup": "index.html",
    "default_icon": {
      "16": "icons/chromextension16.png",
      "32": "icons/chromextension32.png",
      "48": "icons/chromextension48.png",
      "128": "icons/chromextension128.png"
    }
  },
  "icons": {
    "16": "icons/chromextension16.png",
    "32": "icons/chromextension32.png",
    "48": "icons/chromextension48.png",
    "128": "icons/chromextension128.png"
  }
}

Here, you can change the name and description of the extension. Chrome extensions require icons in four different sizes. Use an image-resizing tool to make four versions of your extension icon with dimensions of 128x128, 48x48, 32x32, and 16x16 pixels. Then place the icons in the adjacent icons/ directory.

In the action field in the manifest.json file, set index.html as the default pop-up page. This way, when you click on the extension icon in the browser's top bar, the index.html page will pop up.

An explanation of Content Security Policy

Content Security Policy (CSP) is a security layer in the browser that protects users from cross-site scripting and data injection attacks. Normally, browsers trust the content coming from a server. Cross-site scripting misuses this trust and runs malicious code in the browser.

Using CSP, developers can specify a trusted domain in the HTTP header. A CSP-enabled browser will only execute scripts coming from that specific domain and ignore inline scripts and event-handling HTML attributes.

Take a look at the CSP in our manifest.json file. Here, we define script-src and object-src as self. Therefore, the browser won't execute inline scripts and scripts from another origin. In developer mode, you get a CSP error.

We will rectify this error in the next section. If you want to learn more about CSP on the web, you can read this CSP guide from MDN Web Docs.

Configure Flutter Web

To rectify the CSP error, remove all the script tags from the index.html file in the web/ directory. Then link the main.dart.js file inside the <body> tag. The main.dart.js is generated at build time and contains all the transpiled Dart and Flutter code.

Now, remove all the unnecessary meta tags from the index.html file, and add an explicit width and height to the <html> element. After all these changes, the final version of index.html looks like this.

<!DOCTYPE html>
<html style="height: 600px; width: 300px">
  <head>
    <meta charset="UTF-8" />
    <title>chromextension</title>
  </head>
  <body>
    <script src="main.dart.js" type="application/javascript"></script>
  </body>
</html>

Add a custom background script

Background scripts are event-based programs that react to certain events within the browser. These scripts are optional for Chrome extensions. If you're developing some feature in your extension that requires the execution of background code, then having custom background scripts comes in handy.

To add a background script to a Flutter Chrome extension, add a new file background.js inside the web/ directory.

Then, register the background script in your manifest.json file.

{
  "name": "Chromextension",
  "description": "A flutter chrome extension",
  "version": "0.0.0.1",
  "manifest_version": 3,
  "content_security_policy": {
    "extension_pages": "script-src 'self' ; object-src 'self'"
  },
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["contextMenus", "clipboardWrite", "clipboardRead"],
  "action": {
    "default_icon": {
      "16": "/images/scholarr16.png",
      "32": "/images/scholarr32.png",
      "48": "/images/scholarr48.png",
      "128": "/images/scholarr128.png"
    }
  },
  "icons": {
    "16": "/images/scholarr16.png",
    "32": "/images/scholarr32.png",
    "48": "/images/scholarr48.png",
    "128": "/images/scholarr128.png"
  }
}

The background script needs explicit permission to run in the browser. This is controlled with the permissions field in the manifest.json file.

Now, populate the background script with the logic to run upon a browser event. To learn more, check out the Chrome developer documentation.

Build a Flutter Web project

Flutter Web projects can be built with two types of renderers. The first, HTML renderer, uses a combination of HTML elements, CSS, Canvas elements, and SVG elements. The second, CanvasKit renderer, uses Skia as the rendering engine and draws pixel-perfect widgets. CanvasKit renderer adds about 2 MB to the download size of your application.

If we don't specify the renderer when we build our Flutter Web project using the flutter build web command, Flutter will use an HTML-rendered web app in mobile browsers and a CanvasKit-rendered web application in desktop browsers.

However, Chrome extensions don't support CanvasKit-rendered applications. Therefore, add the --web-renderer html flag at build time to generate only an HTML-rendered application.

Another issue with Flutter Web is the dynamically generated code in the build output. This behavior gives us CSP errors in the browser. To disable dynamically generated code, use the --csp flag with the Flutter build command.

Therefore, to make an optimized Chrome extension using Flutter, the build command should look like this.

flutter build web --web-renderer html --csp

Integrate a Codemagic CI/CD pipeline

Codemagic is a CI/CD platform that facilitates the building and deployment of Flutter applications. We can use it to build and deploy our Flutter app for any platform, including the Flutter Web Chrome extension that we've just made. Create a Codemagic account today to get 500 build minutes for free.

Create a Codemagic account

Go to your Codemagic project dashboard and add a new application. Select your repository provider from the pop-up list. My code is hosted on GitHub, so I am selecting GitHub here.

Now, find your project repository in the dropdown menu, and select "Flutter App (via Workflow Editor)" as the project type.

For the build platform option, select web builds.

In the build argument, add the --web-renderer and --csp flags.

Finally, save your changes and start your Codemagic build.

Now you can download the generated artifacts and publish to Chrome Web Store. Let's do that!

Publish the Chrome extension to Chrome Web Store

After you've built your Chrome extension, it's possible to automatically publish in Chrome Web Store using a Codemagic post-publish script. Before following the steps in this section, make sure to sign up for a Chrome Developer Account.

It's also important to note that you should publish the extension manually the first time. But afterward, you can automate the deployment of your Chrome extension with Codemagic CI/CD.

So, let's start by getting the credentials we'll need to publish the extension for the first time.

Acquire the required credentials

Go to the Google Cloud Console and create a new project. In the search bar, search for "Chrome Web Store API". Click on the first result and enable the API.

Then click on the OAuthConsentScreen and select the user type "External". Fill out all the application details in the respective fields, click "Save", and continue to the next step. You can skip the "Scopes" tab and continue. Then add your email as a test user and click "Save and continue".

To get the access key, go to "Credentials" and select the "Create credentials" option. From the dropdown list, select "OAuth client ID".

For the application type, select "Desktop App", fill out the name, and click "Create". Now, a pop-up containing your client ID and client secret should appear. You can download the JSON file and save it in a secure place.

To work with the Chrome Web Store API, you'll need to have an access token. To get the access token, paste this URL https://accounts.google.com/o/oauth2/auth?response_type=code&scope=https://www.googleapis.com/auth/chromewebstore&client_id=$CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob in your browser, and replace $client_ID with our app's client ID.

When your browser resolves the URL, a Google OAuth page appears. Sign in with the email you have set as the test user inside the OAuthConsentScreen.

After you have been successfully authorized, you will get an authorization code. We'll use this code to request an access token.

To generate the access token, you have to make a request with your client ID, client secret, and the authorization code we've found in the previous step. I am using curl for this purpose.

curl "https://accounts.google.com/o/oauth2/token" -d\
"client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&code=$CODE&grant_type=authorization_code&redirect_uri=urn:ietf:wg:oauth:2.0:oob"

Replace $CLIENT_ID, $CLIENT_SECRET, and $CODE with their respective values. The response to this request should look like this.

{
  "access_token" : "ya29.a0Aa4xrXO...",
  "expires_in" : 3599,
  "refresh_token" : "1//0gZyg...",
  "scope": "https://www.googleapis.com/auth/chromewebstore",
  "token_type" : "Bearer",
}

Now you can use this access token to interact with the Chrome Web Store Publish API.

Publish the Chrome extension using the Chrome Web Store API

Before publishing, make sure to enable two-step authentication in your Google account.

Then go to your Chrome Web Store dashboard and create a new item. Fill out the store listing and privacy practices page.

After properly setting things up, we are ready to publish our extension to Chrome Web Store. I am using curl to make the request to the Chrome Web Store API.

 curl\
-H "Authorization: Bearer $TOKEN"\
-H "x-goog-api-version: 2"\
-X POST\
-T $FILE_NAME\
-v\
https://www.googleapis.com/upload/chromewebstore/v1.1/items

Here, fill in $TOKEN and $FILE_NAME with the access token and the ZIP file with the extension, respectively.

How to automate publishing a Chrome extension with a Codemagic post-publish script

After finishing building our Flutter project with Codemagic, click on the gear icon at the end to reveal the post-publish script section.

To access the generated artifacts from the build stage, add this script inside the post-publish script section.

ARTIFACT_TYPE=".zip"
ARTIFACT_URL=$(echo $CM_ARTIFACT_LINKS | jq -r '.[] | select(.name | endswith("'"$ARTIFACT_TYPE"'")) | .url')

Here, the ARTIFACT_URL contains the URL to the generated ZIP file in the build stage.

Now we can use this URL in our curl script to directly upload to Chrome Web Store.

curl\
-H "Authorization: Bearer $TOKEN"\
-H "x-goog-api-version: 2"\
-X POST\
--url $ARTIFACT_URL
-v\
https://www.googleapis.com/upload/chromewebstore/v1.1/items

Here, we replace the -T flag from the previous curl script with the --url flag to directly upload the generated artifact. Now, whenever you build your extension, it automatically uploads the project to Chrome Web Store.

You can use this official guide to explore more use cases of the Chrome Web Store API.

Conclusion

This is a beginner's guide to making a Google Chrome extension using Flutter Web. If you have followed all the steps, by now, you've learned how to configure the different files of your Flutter Web app so that it can be a Chrome extension, build the app, publish it to Chrome Web Store, and automate the process with Codemagic CI/CD.

You can find the sample project for making a Chrome extension with Flutter on GitHub.

Codemagic is a CI/CD tool for Flutter and other mobile developers.

Dr. Riverpod: How I learned to stop worrying and love state management

C💙demagic — Tue, 01 Nov 2022 13:50:46 +0000

This post is written by Alessio Salvadorini and originally posted Codemagic blog.

Overview

State management is a very controversial topic in the Flutterverse, with many holding strong opinions on it.

In the last few weeks, my Twitter feed has been overwhelmed with threads about state management, covering the entire spectrum of opinions, from GetX/BLoC/Riverpod fanatics on one side to a few rare enlightened ones on the other side who recommend not using any state management at all.

While I personally enjoyed almost all of them, the impact on the Flutter community has been quite severe.

When I asked my readers about writing this article in a typical TDD (Twitter-Driven Development, ©® @mkobuolys) approach, about a third voted no, and half of them were so fed up with state management that they recommended that I shoot myself, metaphorically speaking.

So, keep all this in mind while I walk you through this article about state management to show you how to choose the best state management solution for Flutter at the end of 2022 (and perhaps in 2023 as well). It's worth noting that this advice is based entirely on my own opinion, and you're always welcome to disagree. However, we first need to understand how and why we ended up in this situation, so bear with me for a few minutes longer.

The state of Flutter state management: How did we get here?

If you haven't done so yet, I strongly recommend you watch these two videos: the first shows Filip Hracek and Matt Sullivan on the Google I/O stage in May 2018 introducing BLoC (the pattern) to all of us; the second shows the same Filip and Matt on the very same stage but in May 2019, exactly one year later, introducing pragmatic state management.

However, in between those two videos, I think something important yet fleeting happened. A big misunderstanding was born, and it impacted our community more than I initially realized.

To understand the context at the time when the first video was released, we need to remember that the community was already asking Google, and the Flutter team in particular, for a recommended approach for state management. Also, Flutter wasn't as relevant as it is nowadays. This meant that very few videos at Google I/O were about Flutter, so one about state management felt even more relevant --- or at least, the community perceived it to be.

Shortly after the first video was released, a talented developer who needs no introduction, Felix Angelov, started to develop BLoC (the package).

It quickly became the de facto standard for state management, one of the most used packages by individual developers and big companies, and the subject of mandatory questions at job interviews. Basically, it was essential for anyone who wanted to become a Flutter developer to understand it.

This happened around the time when I was starting to look into Flutter. I quickly reached a point when the more I was coding in Android, the more I wanted to code in Flutter, and the more I was coding in Flutter, the more I wanted to code in Flutter. So, by the time I tried to wrap my head around BLoC (the pattern) and BLoC (the library), the second video was released, introducing what immediately felt like a much simpler approach to state management.

But, as the demand for a state management solution had already been met (or at least the community thought so), and everyone was already using BLoC (the package), I think the second video went almost unnoticed.

It does, however, contain this little gem starting at around 19:20, where Filip and Matt mention that even though Google also open sourced a similar package based on scope model, they would instead recommend Provider, a library created by a young and talented French developer, Remi Rousselet.

And Provider wasn't the only alternative to BLoC (the package) because many other options were also flourishing: Redux (which was already familiar to developers coming from JavaScript), get_it, MobX, the controversial GetX, and many, many more.

You can find a non-exhaustive list in the official Flutter docs.

Given all that, it's quite easy to understand how, by the end of 2022, we're still in a messy and unclear situation.

It's frustratingly difficult for beginners and new developers approaching Flutter to make a choice unless they have lots of time to spend learning about the topic.

The Flutter team has been mainly silent about this topic, and I don't blame them, as they can't (and, IMHO, shouldn't) suggest one state management technique that would be suitable for all kinds of apps, nor can they add one directly into the SDK.

The only way to resolve this situation is to end at the beginning.

Isn't this where we came in?

Believe me or not: Not all states need a state management technique. A state can be classified into one of two distinct types: ephemeral or application state.

You can think of the ephemeral state as a state that is self-contained into a widget, which doesn't need to be shared or accessed from anywhere else.

An example of an ephemeral state is the index of the actual page in a page viewer. For an ephemeral state, you don't need any state management technique, and setState() and StatefulWidget work perfectly fine for handling this case.

Think of the application state as a state that is shared between the different views of your app or that needs to be restored between two separate user sessions.

In this case, you need to move the state away from your view and into a state holder class. Examples of an application state are the settings or the login.

For an application state, you do need a state management technique.

Since you are going to pick only one, you want to choose carefully. And to choose carefully, you need to be able to compare your options. And to be able to compare, we need to agree on the metrics of the comparison.

Introducing metrics: Measuring how good a state management solution is

The only way we can choose which one is the "best" state management solution is to agree on how we define "best."

There are many different types of apps, and more will come in the future that we can't even imagine now. Therefore, it's practically impossible to suggest one state management technique to rule them all.

So far, I have found only two sources that have helped me compare state management techniques.

The first source is by my mate Mike Rydstrom, who created an exhaustive picture comparing the top 30 state management packages:

As you can see, this picture ranks the packages by package likes. It also includes extra information, like if a given package is null safe (NS), the percentage of test coverage (CodeCov), the percentage of API docs' completeness (API docs), a summary (Points), the package's popularity, GitHub stars, the ratio of likes to stars, and the ratio of open to closed issues.

That's a lot of info to crunch for one single picture.

It's a good start, with Provider, BLoC (the package), get_it, and Riverpod placing in the top rankings (2, 3, 4, and 5, respectively). This is all fine until you look at the highest-ranked package, get (formally known as GetX), which, for me, is an anti-pattern and a no-go.

The second source is a bachelor's thesis titled "State management approaches in Flutter" by Dmitrii Slepnev, published in December 2020.

In this thesis, Slepnev categorizes some of the most common state management techniques. He chooses six criteria, some of which are still subject to opinion, but they are well defined and easy to understand: complexity, amount of boilerplate code, code generation, time travel support, scalability, and testability.

An intuitive summary is provided in Table 11 of the study.

As you can see, this table makes comparing state management techniques easy, and it may help you to choose one based on such metrics. Likewise, after you choose your state management technique, this table could help you profile it.

Now that we have defined at least some metrics based on these two sources, let's see how to apply them.

And the winner is...

Just like many of you at this point, I was initially confused and overwhelmed by all the possibilities and alternatives we have when it comes to state management in Flutter.

This is definitely a healthy sign, as it clearly indicates that Flutter is developing, but it could also lead to a negative downward spiral.

So, I looked into and tried some of the different options. I strongly recommend you try them out too and not take anyone's opinion for granted, not even mine.

Try to implement and re-implement a sample app with different state management techniques, compare them, and see which one feels better to you and for what reasons. If possible, try to make the metrics explicit.

There is also a non-official code sample app that compares some of the alternatives.

For me, simplicity was the key, as simplicity is one of the most important values in my life.

After I tried some of them, I decided which one was the best for me: Provider/Riverpod. This choice was supported by Table 11 in Slepnev's study. Since I prefer simplicity, I want the complexity to be as low as possible. Additionally, I want minimal boilerplate code, I don't want any code generation, time travel is irrelevant to me, and scalability and testability must be decently good.

You can find a tutorial that will help you get started with Riverpod here

This decision is also confirmed by Mike's picture, as I want a well-maintained package.

Last but not least, this choice is supported by the official Flutter docs: Simple state management is the only officially documented state management technique.

What is simple state management?

Simple state management, aka pragmatic state management, is based on Provider+ChangeNotifier. It's well documented, and there's a code sample.

In case you don't know, Riverpod is a second take on Provider made by the same author, Remi Rousselet. You can think of Riverpod as a "Provider 2.0," a better version of Provider. If you're still using Provider, you should migrate to Riverpod, as it's very straightforward.

So, you can easily implement simple state management nowadays with Riverpod and ChangeNotifier.

Note: ChangeNotifier, ValueNotifier (from SDK), and StateNotifier (from Remi) are all interchangeable. Since they all accomplish the same thing, you can use the one you prefer as long as you know what you're doing and why.

Simple state management is very simple. It is built on three pillars:

The state holder class encapsulates the application state. It's responsible for changing the state and notifying about state changes; this is done with the ChangeNotifier class.
The UI needs to have access to your state holder class (the ChangeNotifier); this is done through Riverpod with its provider classes (ChangeNotifierProvider, ValueNotifierProvider, StateNotifierProvider, etc.).
The UI needs to consume the state changes; this is done through Riverpod with its consumer classes (Consumer, ConsumerWidget, ConsumerStatefulWidget).

Build your Flutter apps faster with Apple M1 VMs. Learn more!

Conclusion

This article is an extension of part of my talk for Flutter Vikings 2022.

In this article, I gave you some reasons why state management is a complex topic for Flutter and some metrics that can help you decide between the many options available. I recommend that you choose the safest bet (Riverpod) and the metric used (simplicity).

Now that you've chosen your state management technique, though, keep in mind that it's not enough to create a scalable and robust app in a production environment. You'll need a whole architecture.

Luckily, Riverpod is much more than a tool for state management; it's a reactive caching and data-binding framework, and we can build the whole app architecture around Riverpod. Curious to know how?

I kept this article codeless on purpose, as I'll follow up with a deep dive into architecture. So if you're interested, keep an eye on this blog. I'll keep you posted!

To be continued...

Codemagic is a CI/CD tool for Flutter and other mobile developers.

Flutter widgets cheat sheet

C💙demagic — Tue, 01 Nov 2022 13:43:05 +0000

This post is written by Godwin Alexander Ekainu and originally posted to Codemagic blog.

Flutter is an open-source tool designed to build fast and beautiful applications across multiple platforms. The Flutter SDK has been widely adopted for developing mobile applications, and many developers are learning Flutter every day. It is important to create content that can help them do this, and that's the aim of this blog post! So, we've prepared a simple cheat sheet of different Flutter widgets (and in Flutter, everything is a widget!), which you can use to build your Flutter apps.

We've grouped the widgets into several categories:

Interaction widgets. These help make your Flutter app interactive.
Input widgets. These widgets are used to handle user input.
Alignment and layout widgets. You use these widgets everywhere to position other widgets on the screen relative to one another and organize them into structures.
Scrollable widgets. These widgets come in handy when you need to create scrollable lists and galleries.
Structure widgets. These are the foundational widgets for your app.
Paint widgets. These widgets allow you to customize the design of your app.
Button widgets. These are, as you might have guessed, for creating buttons.
Basic navigation. To navigate between screens, you'll need navigation. We'll provide a basic example of navigation in this article.

If you don't understand the concept of widgets, you can refer to our Flutter From Scratch video on this topic.

How do you use this Flutter widgets cheat sheet? Just copy-paste the code for the widgets you want to use in your app, and modify it to incorporate the logic you need. Let's get started!

1. Interaction widgets

Interaction widgets make your application dynamic and provide a good user experience, so it's essential to understand how to use them.

GestureDetector

GestureDetector is a widget that responds to events or gestures that correspond to its non-callbacks.

onTap
onTapUp
onTapDown
onLongPress
onDoubleTap
onHorizontalDragStart
onVerticalDragDown
onPanDown
onScaleStart

You can use this gesture detector to create custom buttons or clickable text or pictures.

To add a gesture detector, use the code below:

    GestureDetector(

      onTap: () {
        const snackBar = SnackBar(content: Text('Tap'));

        ScaffoldMessenger.of(context).showSnackBar(snackBar);
      },
      // The custom button
      child: Container(
        padding: const EdgeInsets.all(12.0),
        decoration: BoxDecoration(
          color: Colors.lightBlue,
          borderRadius: BorderRadius.circular(8.0),
        ),
        child: const Text('My Button'),
      ),
    )

AlertDialog

The AlertDialog widget creates a window to display crucial information with options that allow the user to make decisions.

To add an alert dialog to your app, you can use the following code:

     Future<void> _showMyDialog() async {
      return showDialog<void>(
        context: context,
        barrierDismissible: false, // user must tap button!
        builder: (BuildContext context) {
          return AlertDialog(
            title: const Text('Cheat Sheet'),
            content: SingleChildScrollView(
              child: ListBody(
                children: const <Widget>[
                  Text('This is a demo alert dialog.'),
                  Text('Would you like to approve of this message?'),
                ],
              ),
            ),
            actions: <Widget>[
              TextButton(
                child: const Text('Approve'),
                onPressed: () {
                  Navigator.of(context).pop();
                },
              ),
            ],
          );
        },
      );
    }

SnackBar

The SnackBar widget is used to briefly tell a user that an action has taken place. For example, you can delete an item that triggers a snackbar, which tells the user that an item has just been deleted.

To add a snackbar to your application, use the code below:

    Center(
            child: ElevatedButton(
              onPressed: () {
              final snackBar =  SnackBar(
                content: const Text('Yay! A SnackBar!'),
                action: SnackBarAction(
                  label: 'Undo',
                  onPressed: () {
                   Text('data');
                  },
                ),
              );
                  ScaffoldMessenger.of(context).showSnackBar(snackBar);
              },
              child: const Text('Show snackbar'),
            ),
          ),

Dismissable

You can use a Dismissable widget to remove or dismiss items from a list. You can swipe left or right to remove any item.

Use the code below to implement this feature:

    List<String> items = <String>[
        'banana',
        'strawberry',
        'apple'
        'orange'
        'cat'
        'bobcat'
      ];
    ListView.builder(
              itemCount: items.length,
              padding: const EdgeInsets.symmetric(vertical: 16),
              itemBuilder: (BuildContext context, index) {
                return Dismissible(
                  background: Container(
                    color: Colors.green,
                  ),
                  key: Key(items[index]),
                  onDismissed: (DismissDirection direction) {
                    setState(() {
                      items.removeAt(index);
                    });
                  },
                  child: ListTile(
                    title: Text(
                      'Item ${items[index]}',
                    ),
                  ),
                );
              },
            ),

InteractiveViewer

If you have a big picture that doesn't fit on the screen, you can use the InteractiveViewer widget to enable it to fit on the screen by allowing the user to zoom in and out of the picture.

    InteractiveViewer(
            boundaryMargin: const EdgeInsets.all(20.0),
            child: Container(
              decoration: const BoxDecoration(
                gradient: LinearGradient(
                  begin: Alignment.topCenter,
                  end: Alignment.bottomCenter,
                  colors: <Color>[Colors.blue, Colors.yellow],
                  stops: <double>[0.0, 1.0],
                ),
              ),
            ),
          ),

2. Input widgets

Input widgets are a very important part of modern-day Flutter applications. For example, they are used to create an account, log in, or even perform a simple search.

Flutter forms

You can create a login and signup form using these widgets.

Try creating a form using the Forms widget and TextFormFields widget:

      class MyApp extends StatelessWidget {
      const MyApp({Key? key}) : super(key: key);
      @override
      Widget build(BuildContext context) {
        const appTitle = 'Flutter Form Demo';
        return MaterialApp(
          title: appTitle,
          home: Scaffold(
            appBar: AppBar(
              title: const Text(appTitle),
            ),
            body: const MyCustomForm(),
          ),
        );
      }
    }
    // Create a Form widget
    class MyCustomForm extends StatefulWidget {
      const MyCustomForm({Key? key}) : super(key: key);
      @override
      MyCustomFormState createState() {
        return MyCustomFormState();
      }
    }
    class MyCustomFormState extends State<MyCustomForm> {
      final formKey = GlobalKey<FormState>();
      @override
      Widget build(BuildContext context) {
        // Build a Form widget using the formKey created above
        return Form(
          key: formKey,
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: <Widget>[
              TextFormField(
                decoration: const InputDecoration(
                  icon:  Icon(Icons.person),
                  hintText: 'Enter your name',
                  labelText: 'Name',
                ),
              ),
              TextFormField(
                decoration: const InputDecoration(
                  icon: Icon(Icons.calendar_today),
                  hintText: 'Enter your date of birth',
                  labelText: 'Dob',
                ),
              ),
              const ElevatedButton(
                child:  Text('Submit'),
                onPressed: null,
              ),
            ],
          ),
        );
      }
    }

Autocomplete

This widget can come in handy in search boxes.

To add autocomplete to your Flutter application, you can use the following code snippet. The options to be displayed are determined by the optionsBuilder and rendered by the optionsViewBuilder.

    // have a list of words or names from a remote source or package
    const List<String> _kOptions = <String>[
        'aardvark',
        'bobcat',
        'chameleon',
      ];
    // use the Autocomplete widget to make selections
    Autocomplete<String>(
          optionsBuilder: (TextEditingValue textEditingValue) {
            if (textEditingValue.text == '') {
              return const Iterable<String>.empty();
            }
            return _kOptions.where((String option) {
              return option.contains(textEditingValue.text.toLowerCase());
            });
          },
          onSelected: (String selection) {
            debugPrint('You just selected $selection');
          },
        );

TextField

TextField is one of the most fundamental and commonly used widgets for keyboard input.

    TextField(
      obscureText: true,
      decoration: InputDecoration(
        border: OutlineInputBorder(),
        labelText: 'Password',
      ),
    )

3. Alignment and layout widgets cheat sheet

These widgets are very important for building UIs in Flutter.

Center

This widget centers a child within itself.

    Center( child: Text('Center me'))

Expanded

The Expanded widget expands the child of a Row or Column to fill any available space.

For example, you can use it to build a UI that fills the screen with just three containers or pictures. Theoretically, we can just specify their heights, but remember that there are different screen sizes for different devices, including tablets such as iPad devices. The expanded widget can help you create a more responsive design that can easily fit all screen sizes.

    Row(
              children: <Widget>[
                Expanded(
                  flex: 2,
                  child: Container(
                    color: Colors.amber,
                    height: 100,
                  ),
                ),
                Container(
                  color: Colors.blue,
                  height: 100,
                  width: 50,
                ),
                Expanded(
                  child: Container(
                    color: Colors.amber,
                    height: 100,
                  ),
                ),
              ],
            ),

Align

The Align widget aligns its child within itself. This widget is very flexible and can take the size of its child.

The child can be placed at different points within its parent widget using the alignment property, as shown below:

    Container(
        height: 120.0,
        width: 120.0,
        color: Colors.blue[50],
        child: const Align(
          alignment: Alignment.topRight,
          child: FlutterLogo(
            size: 60,
          ),
        ),
      ),

Row

The Row widget takes a list of widgets and arranges them horizontally. You will likely use this widget a lot when making layouts in your code.

    Row(
            children: [
              ElevatedButton(
                child: const Text('Widget 1'),
                onPressed: () => Navigator.pushNamed(context, '/second'),
              ),
               ElevatedButton(
                child: const Text('Widget 2'),
                onPressed: () => Navigator.pushNamed(context, '/third'),
              ),
               ElevatedButton(
                child: const Text('Widget 3'),
                onPressed: () => Navigator.pushNamed(context, '/fourth'),
              ),
            ],
          ),

Column

The Column widget allows you to arrange a list of widgets vertically, similar to how the Row widget aligns them horizontally.

    Column(
      children: const <Widget>[
        Text('Deliver features faster'),
        Text('Craft beautiful UIs'),
        Expanded(
          child: FittedBox(
            fit: BoxFit.contain,
            child: FlutterLogo(),
          ),
        ),
      ],
    )

SizedBox

Use SizedBox to give a specific size to its child widget or provide some white space between widgets.

    const SizedBox(
      width: 200.0,
      height: 300.0,
      child: Card(child: Text('Size me!')),
    )

BaseLine

Use the BaseLine widget to position the child widget according to the starting point of the parent widget.

    Center(
          child: Container(
                  width: 100,
                  height: 100,
                  color: Colors.green,
                  child: Baseline(
                    baseline: 50,
                    baselineType: TextBaseline.ideographic,
                    child: Container(
                      width: 50,
                      height: 50,
                      color: Colors.purple,
                    ),
                  ),
                ),
        );

LimitedBox

Use this widget to assign a default size to a list of widgets that are unconstrained.

    LimitedBox(
             maxHeight: 150,
             maxWidth: 150,
             child: Container(
             color: Colors.red,
            )
           )

Padding

Use the Padding widget to provide space around its child. The padding widget adds space around its child using the abstract EdgeInsetsGeometry class.

The padding property of the padding widget accepts the EdgeInsets object, which allows you to add different types of padding, including padding only in certain places using EdgeInsets.only or from different angles using EdgeInsets.fromLTRB.

    const Card(
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Text('Hello World!'),
      ),
    )

4. Scrollable widgets

ListView Builder

ListView Builder is the most used scrollable widget. It displays its children in the scroll direction one after the other. For example, if you have a long list that is dynamically created, you can use Listview.builder to display it.

Use the following code to get started:

    final List<String> entries = <String>['A', 'B', 'C'];
    ListView.builder(
      padding: const EdgeInsets.all(8),
      itemCount: entries.length,
      itemBuilder: (BuildContext context, int index) {
        return Container(
          height: 50,
          color: Colors.amber[colorCodes[index]],
          child: Center(child: Text('Entry ${entries[index]}')),
        );
      }

SingleChildScrollView

The SingleChildScrollView widget will come in handy if you have a list of items that you initially didn't intend for the user to scroll through, but the requirements change upon implementation. In this case, you can quickly wrap the parent widget with a SingleChildScrollView to make it scrollable.

    SingleChildScrollView(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            mainAxisAlignment: MainAxisAlignment.spaceAround,
            children: <Widget>[
              Container(
                color:  Colors.red,
                height: 300.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
              Container(
                color: Colors.blue,
                height: 250.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
              Container(
                color: Colors.green,
                height: 250.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
              Container(
                color: Colors.purple,
                height: 250.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
            ],
          ),
        );

5. Structure widgets

These are the widgets that compose your app. In this Flutter widget cheat sheet, we will only be highlighting two of them: Scaffold and Loader.

Scaffold

Use Scaffold widgets for all your application layers.

    Scaffold(
          appBar: AppBar(),
          body: Row(
            children: [
              ElevatedButton(
                child: const Text('Widget 1'),
                onPressed: () => Navigator.pushNamed(context, '/second'),
              ),
          ),

Adding Loader

Create Loaders for your app when making an API request.

    class SomeWidget extends StatefulWidget {
      @override
      _SomeWidgetState createState() => _SomeWidgetState();
    }
    class _SomeWidgetState extends State<SomeWidget> {
      late Future future;
      @override
      void initState() {
        future = Future.delayed(const Duration(seconds: 8));
        super.initState();
      }
      @override
      Widget build(BuildContext context) {
        return FutureBuilder(
          future: future,
          builder: (context, snapshot) {
            return snapshot.connectionState == ConnectionState.done
                ? const Text('Loaded')
                : const CircularProgressIndicator();
          },
        );
      }
    }

6. Paint widgets

Painting effects can give a finished look to your app's design.

InkWell

With the InkWell widget, you can create ink splash effects on images or custom buttons when you click on them.

    class _SomeWidgetState extends State<SomeWidget> {
      @override
      Widget build(BuildContext context) {
        Image img = Image.network(
            'https://images.unsplash.com/photo-1592194996308-7b43878e84a6?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=687&q=80');
        return Material(
          child: Ink.image(
            fit: BoxFit.fill,
            width: 300,
            height: 300,
            image: img.image,
            child: InkWell(
              onTap: () {
                print('image');
              },
              child: const Align(
                child: Padding(
                  padding: EdgeInsets.all(10.0),
                  child: Text(
                    'PUFFIN',
                    style: TextStyle(
                      fontWeight: FontWeight.w900,
                      color: Colors.white,
                    ),
                  ),
                ),
              ),
            ),
          ),
        );
      }
    }

DecoratedBox

DecoratedBox, together with BoxDecoration, helps you add more styling to your container widget.

    Container(
          decoration: const BoxDecoration(
            borderRadius: BorderRadius.all(
              Radius.circular(12),
            ),
            gradient:RadialGradient(
          center: Alignment(-0.5, -0.6),
          radius: 0.15,
          colors: <Color>[
            Color(0xFFEEEEEE),
            Color(0xFF111133),
          ],
          stops: <double>[0.9, 1.0],
        )));

ClipRect

Use ClipRect to clip the child within different shapes.

    class DecorateContainer extends StatelessWidget {
       const DecorateContainer(Key? key, this.image) : super(key: key);
     final Image image;
      @override
      Widget build(BuildContext context) {
        return ClipRect(
      child: Container(
        child: Align(
          alignment: Alignment.center,
            widthFactor: 0.4,
            heightFactor: 1.0,
            child: image
        ),
      ),
    );
      }
    }

ClipPath

With the ClipPath widget, you can give any shape to the child widget. This means you can use it to draw any shape of your choice or according to your UI requirements with less code.

     // body of your app
    ClipPath(
            child: Container(
              width: MediaQuery.of(context).size.width,
              height: 250,
              color: Colors.red,
            ),
            clipper: CustomClipPath(),
          ),

    // custom class
     class CustomClipPath extends CustomClipper<Path> {
      var radius=5.0;
      @override
      Path getClip(Size size) {
        Path path = Path();
        path.lineTo(size.width / 2, size.height);
        path.lineTo(size.width, 0.0);
        return path;
      }
      @override
      bool shouldReclip(CustomClipper<Path> oldClipper) => false;
    }

7. Buttons

There are many types of buttons in Flutter, so we'll only suggest the most useful ones in this cheat sheet.

TextButton

This is a Material button with text that has no borders.

     TextButton(
                      style: TextButton.styleFrom(
                        padding: const EdgeInsets.all(16.0),
                        primary: Colors.white,
                        textStyle: const TextStyle(fontSize: 20),
                      ),
                      onPressed: () {},
                      child: const Text('Gradient'),
                    ),

ElevatedButton

ElevatedButton is a Material button that elevates when pressed. Avoid using elevated buttons on widgets that are already elevated, like dialogs.

    ElevatedButton(
                style: ElevatedButton.styleFrom(),
                onPressed: () {},
                child: const Text('Enabled'),
              ),

FloatingActionButton

Use FloatingActionButton to create a primary action on the screen.

    Scaffold(
          appBar: AppBar(
            title: const Text('Floating Action Button'),
          ),
          body: const Center(child: Text('Press the button below!')),
          floatingActionButton: FloatingActionButton(
            onPressed: () {
              // on pressed
            },
            backgroundColor: Colors.green,
            child: const Icon(Icons.navigation),
          ),
        );

8. Basic navigation

Named routing can be used for small to medium-sized projects. Alternatively, you can use the Navigator API, which provides various routing functions.

Flutter provides named routing to enable users to navigate your application:

    void main() {
      runApp(MaterialApp(
        initialRoute: '/',
        routes: {
          '/' : ((context) => const FirstScreen()),
          '/second':(context) => const SecondScreen()
        },
        home: const MyApp()));
    }
    class MyApp extends StatelessWidget {
      const MyApp({Key? key}) : super(key: key);
      @override
      Widget build(BuildContext context) {
        return Scaffold(
            appBar: AppBar(
              title: const Text('Navigation'),
            ),
            body:const FirstScreen()

        );
      }
    }

    class FirstScreen extends StatelessWidget {
      const FirstScreen({Key? key}) : super(key: key);
      @override
      Widget build(BuildContext context) {
        return Center(
          child: ElevatedButton(
            child: const Text('Go to SecondScreen'),
            onPressed: () => Navigator.pushNamed(context, '/second'),
          ),
        );
      }
    }
    // can add this in a new file
    class SecondScreen extends StatelessWidget {
      const SecondScreen({Key? key}) : super(key: key);

      @override
      Widget build(BuildContext context) {
        return ElevatedButton(
          child:const Text('Go back!'),
          onPressed: () => Navigator.pop(context),
        );
      }
    }

To learn more about Flutter Navigator 2.0, read this article.

Conclusion

We have created this list of Flutter widgets as a quick reference for you while you build your Flutter app. We hope you have learned something new about these widgets that can help you improve the functionality of your Flutter application.

We have an ebook that covers a list of libraries commonly used by Flutter developers, including networking, state management, and more. You can also watch our Flutter From Scratch tutorial, which goes into detail about how to use these libraries and widgets.

Codemagic is a CI/CD tool for Flutter and other mobile developers.

A beginner’s guide to go_router in Flutter

C💙demagic — Tue, 01 Nov 2022 13:29:54 +0000

> Written by Hrishikesh Pathak and originally published to Codemagic blog.

Routing is a crucial aspect of an app. Just like when you manage the application state or build the UI, you should give sufficient attention to optimizing the routing of your application. An optimized routing system helps users navigate your app and can handle the user state efficiently.

go_Router is a declarative and minimal routing system built on top of Flutter's Router API. go_router provides a convenient URL-based API to navigate between different screens.

In this article, we'll help you learn how to use go_router in Flutter. We will discuss how to use route parameters, navigate using named routes, handle 404 errors, and much more. To get the most out of this article, be sure to read it to the end.

Adding go_router to your Flutter project

Open a terminal in your Flutter project. Then run the following command to install the go_router package in your Flutter project.



flutter pub add go_router

This command installs the latest version of go_router in your project. If you want to install a different version, just replace the version number in the pubspec.yaml file, and run flutter pub get to get your desired version.

Setting up basic routing using go_router

To integrate go_router in your app, change your MaterialApp widget to MaterialApp.router. This constructor accepts a routerConfig property.



MaterialApp.router(
  routerConfig: _router,
  title: "Go router",
);

Next, we'll add a GoRouter object _router to the routerConfig property. Let's configure our GoRouter and add the home and settings routes.



final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: "/",
      builder: (context, state) => const HomePage(),
    ),
    GoRoute(
      path: "/settings",
      builder: (context, state) => const SettingsPage(),
    )
  ],
);

When someone visits the / route, GoRouter returns the HomePage widget. Similarly, if someone visits the /settings route, GoRouter returns the SettingsPage widget.

Let's see what HomePage and SettingsPage look like in the code.



class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Homepage"),
      ),
      body: Center(
        child: ElevatedButton(
        ),
      ),
    );
  }
}

class SettingsPage extends StatelessWidget {
  const SettingsPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        automaticallyImplyLeading: true,
        title: const Text("Settings"),
      ),
      body: const Center(
        child: Text("Settings Page"),
      ),
    );
  }
}

How to navigate between routes with go_router

To navigate between routes, we can use the GoRouter.of(context).go() method or the more concise context.go() method. Let's add this method in the ElevatedButton in our HomePage widget to navigate to the /settings route.



child: ElevatedButton(
  onPressed: () => context.go("/settings"),
  child: const Text("Go to Settings page"),
),

Similarly, add an ElevatedButton in the SettingsPage to come back to the home / route.



child: ElevatedButton(
  onPressed: () => context.go("/"),
  child: const Text("Go to home page"),
),

Subroutes in go_router

In the above section, we define our GoRouter object. There, you can observe that we put a leading / in every route. If you need deeply nested routes, then you have to type the whole route with the leading / every time. This also makes the routes less organized.

GoRouter provides a routes argument in every GoRoute object to group subroutes and define nested routes more easily.

If we convert our previous GoRouter object to a subroutes structure, then the new GoRouter should look like this.



final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: "/",
      builder: (context, state) => const HomePage(),
      routes: [
        GoRoute(
          path: "settings",
          builder: (context, state) => const SettingsPage(),
        )
      ],
    ),
  ],
);

Can you see the difference? Now, the settings routes live inside the / routes. Therefore, there's no need to specify a leading / in subroutes.

Let's look at another example so that we can grasp the concept completely. If you want to define the nested route /a/b/c, then the GoRouter object should look like this.



final GoRouter _newRouter = GoRouter(
  routes: [
    GoRoute(
      path: "/",
      builder: (context, state) => const HomePage(),
      routes: [
        GoRoute(
          path: "a",
          builder: (context, state) => const PageA(),
          routes: [
            GoRoute(
              path: "b",
              builder: (context, state) => PageB(),
              routes: [
                GoRoute(
                  path: "c",
                  builder: (context, state) => PageC(),
                )
              ],
            )
          ],
        )
      ],
    )
  ],
);

Adding route parameters in go_router

It is very easy to add route parameters in go_router. To define a route parameter, add a trailing : with the parameter name in the path argument of GoRoute.

For example, if you want to add a name parameter in the settings route, the path argument should be /settings:name. You can access the route parameter with the state.params["name"] variable.

Let's see how to implement this in our Flutter app. The modified GoRouter with a route parameter in the settings route should look like this.



final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: "/",
      builder: (context, state) => const HomePage(),
      routes: [
        GoRoute(
          path: "settings/:name",
          builder: (context, state) => SettingsPage(
            name: state.params["name"]!,
          ),
        )
      ],
    ),
  ],
);

To receive the route parameter in the settings screen, let's modify our code and add a property called name.



class SettingsPage extends StatelessWidget {
  final String name;

  const SettingsPage({super.key, required this.name});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        automaticallyImplyLeading: true,
        title: Text(name),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.go("/"),
          child: const Text("Go to home page"),
        ),
      ),
    );
  }
}

Now, when we visit /settings/codemagic, the codemagic route parameter is passed to the SettingsPage and displays the variable on the screen. Similarly, if you visit the /settings/hrishikesh route, hrishikesh is displayed in the SettingsPage.

Named routes in go_router

Writing route paths manually is cumbersome and error prone. Therefore, go_router offers a named route feature to navigate around the app, and go_router will automatically resolve the path itself.

To generate named routes, let's change our GoRouter configuration with the name parameter.



final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      name: "home",
      path: "/",
      builder: (context, state) => const HomePage(),
      routes: [
        GoRoute(
          name: "settings",
          path: "settings/:name",
          builder: (context, state) => SettingsPage(
            name: state.params["name"]!,
          ),
        )
      ],
    ),
  ],
);

Passing route parameters to a named route is different from what you normally see. You have to define a params parameter in the context.goNamed() function. Here's how to set up navigation to SettingsPage from HomePage with a route parameter.



child: ElevatedButton(
  onPressed: () => context.goNamed(
    "settings",
     params: {"name": "codemagic"},
     ),
  child: const Text("Go to Settings page"),
),

Passing query parameters in go_router

You have access to queryParams in the context.goNamed() function. The best thing about queryParams is that you don't have to explicitly define them in your route path and can easily access them using the state.queryParams method. You can add miscellaneous user-related data as a query parameter.

Let's look at an example to illustrate this concept. In the ElevatedButton in HomePage, let's add some query parameters to the settings route.



child: ElevatedButton(
  onPressed: () => context.goNamed("settings", params: {
    "name": "codemagic"
  }, queryParams: {
    "email": "example@gmail.com",
    "age": "25",
    "place": "India"
    }),
    child: const Text("Go to Settings page"),
),

Now we can access these query parameters inside the GoRouter configurations and pass them to the page. In this example, I am just printing out the values for demonstration.



GoRoute(
  name: "settings",
  path: "settings/:name",
  builder: (context, state) {
    state.queryParams.forEach(
      (key, value) {
        print("$key:$value");
       },
     );
   return SettingsPage(
     name: state.params["name"]!,
   );
 },
)

Now, when you click the button to navigate to the SettingsPage, you can see the following output on the console screen.

Handling 404 errors with go_router

When a user visits a screen that is not defined in the GoRouter configuration, it causes an exception. But go_router provides a very easy way to handle these errors, and you can provide a custom page to show to the user when this type of exception occurs.

We can define an errorBuilder argument in the GoRouter object to handle these 404 errors. Let's make an ErrorScreen page that includes a button to navigate back to the HomePage.



class ErrorScreen extends StatelessWidget {
  const ErrorScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        automaticallyImplyLeading: true,
        title: const Text("Error Screen"),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.go("/"),
          child: const Text("Go to home page"),
        ),
      ),
    );
  }
}

Now add this ErrorScreen to the errorBuilder argument of the GoRouter object.



final GoRouter _router = GoRouter(
  errorBuilder: (context, state) => const ErrorScreen(),
);

That's it. Try to launch your Flutter app in the Chrome browser and navigate to a random path. You will see that ErrorScreen will appear as a response.

Redirecting routes using go_router

Sometimes, you want to programmatically navigate your user from one page to another based on certain logic. You can enable that feature using redirects in go_router. You can define a redirect for every path and a global redirect for all pages.

For example, when a new user opens your application, you can navigate them to the login screen instead of the home screen. Similarly, when a logged-in user opens your application, you can navigate them to the home page. You can implement this type of feature very easily using go_router.

Let's see how to implement a redirect in your app. Inside the route, define a redirect argument. Inside the redirect builder, check if the user is logged in or not. If they are not logged in, navigate them to the /login page. Otherwise, show them the home page.



final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      name: "home",
      path: "/",
      builder: (context, state) => const HomePage(),
      redirect: (context, state) {
        if (userIsNotLoggedIn){
          return "/login"
        }
        return "/"
      },
    ),
  ],
  errorBuilder: (context, state) => const ErrorScreen(),
);

GoRouter navigation comparison: go vs. push

GoRouter has two methods for navigating between pages: GoRouter.of(context).go() and GoRouter.of(context).push(). On the surface, they look very similar, but they function differently. The push() method stacks one page on another in navigation, while the go() method directly navigates from one path to another without any stacking.

Here's an example to demonstrate this concept. Assume you have three pages: A, B, and C. If you navigate from A to B to C using the push method, then C is stacked on top of B on top of A. Take a look at this diagram to understand better.

On the other hand, if you navigate from A to B to C using the go method, then C is only stacked on top of A and only if A is the home page with the route /. B is eliminated from the navigation stack altogether. Therefore, the go() method leaves no routing history.

You can choose which strategy works best for your apps.

Bonus: Remove the # prefix from the web URL in Flutter

If you launch your app on the web, you can see a trailing # in the URL. Sometimes it looks very annoying, and you may want to remove it. You can easily achieve this with the help of a package called url_strategy.

First, install this package in your Flutter project.



flutter pub add url_strategy

Then import this package in your main.dart file, and add the setPathUrlStrategy() function before the runApp() function.

Now, run your application. You can see that the trailing # is removed from the URL of your Flutter app.

Choosing between go_router, Navigator 2.0, and Beamer for navigation in Flutter

Flutter has several packages you can use for routing. The most well-known ones are go_router, Navigator, and Beamer. How do you choose which navigation to use for your app?

If you are primarily targeting mobile platforms (Android and iOS) and don't have time to learn a new package for routing, it's completely fine to use Navigator 1.0. It is capable of meeting all your routing needs in Android/iOS apps.

Flutter's core strength is in its multiplatform support, which spans beyond just Android and iOS. If you want to make a real multiplatform app that supports desktop and web platforms in addition to Android/iOS, then you should migrate to Navigator 2.0. Navigator 2.0 provides a very flexible and fully customizable routing solution for truly multiplatform apps.

But a huge chunk of developers don't like the verbose nature of Navigator 2.0, which usually requires you to write boilerplate code to create a simple route. If you want to avoid these issues, you can use go_router, which is declarative and a significantly simpler solution for Flutter. If you have a medium-sized to large application and want to handle dynamic routes, go_router can help you minimize your effort and maximize the results.

Beamer is the new kid on the Flutter navigation stack. Like go_router, Beamer is also based on the Flutter router API. It makes developers' lives easier by simplifying Navigator 2.0. If you are already using go_router, then there is no need to switch to Beamer unless you are missing some features and Beamer can satisfy your needs.

If you are a beginner Flutter dev, you can go with either go_router or Beamer. Both are good and focus on developer productivity by removing complexity and boilerplate code.

Build your Flutter app using Codemagic

Our app isn't completely ready for release at this point, but let's set up a CI/CD pipeline for it anyway. Ideally, you should do this right from the start of the development process to make it easier to collaborate on the app with other developers and deliver new features to testers and customers while avoiding falling into the "it works on my computer" trap.

Codemagic is a CI/CD platform for Flutter applications. You can trigger a new Flutter build when you push your code to your GitHub/GitLab/Bitbucket repository. Then just download the generated artifacts from the Codemagic dashboard and run them on your devices (unless you want to publish them to stores, which Codemagic can also help you with). Let's see step by step how to set up a CI/CD pipeline with Codemagic for your Flutter application.

In case you are not a Codemagic user yet, you can sign up here:

Create a new Codemagic project and connect your repository.

Select Flutter as the project type.

Under Automatic build triggering, check Trigger on push.

In the Build tab, select your Flutter version, build format, and custom build arguments.

Click on the Start new build button to initiate the first build of your application.
After the build completes, you can download the artifacts and run the app on your devices.

Conclusion

go_router is a very minimalistic but powerful routing package for Flutter. It removes all the complexity that Flutter Navigator 2.0 brings to the table and provides a very developer-friendly API to work with.

In this article, we have discussed how to use go_router in your Flutter app as well as some of its features, like route parameters, query parameters, named routes, handling errors, and redirection. This is just a beginner's guide for getting started with go_router. If you want to learn more, visit the official go_router API documentation.

If you have any questions, you can ask me on Twitter. Have a good day.

You can find the sample app on GitHub.

Creating a Progressive Web App (PWA) with Flutter

C💙demagic — Fri, 07 Oct 2022 07:27:00 +0000

Written by Jahswill Essien and originally posted to Codemagic blog.

So, you just finished building that application that's going to change the world, you've submitted the Android apk to the Google Play Store and the iOS ipa to the Apple App Store, and you're awaiting review. But when you check your email, you discover that your iOS app has been rejected. Given the urgency of releasing the app, what do you do now?

Well, the good news is that your application was built with Flutter, which is a great tool for creating Progressive Web Apps (PWAs). But what is a PWA?

This tutorial discusses what PWAs are, how to create a Flutter PWA, what to consider while creating one, handling web navigation efficiently, building and publishing a Flutter web app with Codemagic, how to install a PWA, and the benefits of PWAs.

To get the most out of this Flutter PWA tutorial, you should at least be proficient in the Flutter framework and reading Flutter code. At least some familiarity with Navigator 2.0 is needed for the Navigation section of this post.

Also, you will need a Codemagic account to complete the building and deployment part. If you don't have one, you can sign up, it's free.

By the time you finish this article, you will have completed this simple demo Flutter PWA that displays job openings. (Please note that the figures and data displayed below are just dummy data.)

The design used for this app was inspired by the design I found on Dribbble here.

What is PWA?

A Progressive Web App, or PWA for short, is simply a web page that can be saved (installed) from the web to provide a native app feel. PWAs work offline and have support for notifications, just like native applications.

Flutter allows you to build multiple apps with one code base, so you can build a web app, or a PWA, if you already have your codebase for Android and iOS, quite quickly.

Read this article about PWAs vs native apps to understand the pros and cons of PWAs.

Creating a Flutter PWA

Creating a PWA in Flutter is as simple as creating a Flutter web application. What better time than now is there to set up our demo Flutter project?

Setup

Clone the starter code by running the command git clone -b starters-code git@github.com:JasperEssien2/pwa_demo.git.

The dependencies used in this project are shown in the table below.

Dependency	Use cases
`font_awesome_flutter`	To access icons that aren't available in the material icon
`Beamer`	Used for efficient, complicated navigation

You should do your best to navigate the codebase to understand what each component does, but here's a breakdown of the main components.

/lib/widgets/detail_widgets.dart: contains the detail page's widget code
/lib/widgets/job_list.dart: houses the job list's widget code
lib/app_provider.dart: contains an implementation of InheritedWidget named AppProvider

InheritedWidget provides a good way to pass data down Flutter's widget tree. AppProvider will be utilized to pass down dummy jobs data and a childBeamerkey (more on this in the navigation section).
lib/extensions.dart: defines the isLargeScreen, isExpanded, and provider getter functions in the BuildContext

Dart's extensions make it possible to define custom functionalities in existing libraries.
lib/job_model.dart: defines the model classes that the app uses
lib/main.dart: contains our app entry point and the home page widgets

With this out of the way, let's look at some things to consider while building a web application in Flutter.

Considerations while building a web app with Flutter

There are a few important things to consider while building a web app with Flutter. This article covers two important aspects: responsiveness and navigation.

Responsiveness in Flutter

Given that our web application may be run on various screen sizes, as Flutter developers, we have to do our best to account for them. A responsive app is an app that is tuned for different screen sizes. So, let's make our Flutter Progressive Web App responsive!

In this project, we will use a list-detail design pattern. To make it responsive, we will take the following approach:

On a smaller screen size, the list view occupies the entire screen, and tapping on a list item pushes a new screen to display the job details
On a larger screen size, the list view occupies the left pane, while the detail widget is displayed beside the list view on the same screen
On a very large screen size, we will add margins to the left and right sides of the home screen

A structure like this makes implementing navigation tricky because the user can resize the window or change the orientation of the device. But you don't want your users to see an ugly wide detail screen after resizing the window from a small to a larger size (if the detail screen is already in view). In other words, you want the navigation to be in sync even if the user suddenly resizes the window.

Navigation for Flutter Web

While Navigator 1.0 (imperative API) works fine for most Flutter applications, it is very inefficient for complex routing for web applications and complex deep linking. That is why the Flutter team introduced Navigator 2.0 (declarative API) for Flutter. Although it is much more efficient, it also introduced a great deal of complexity.

A discussion of Navigator 2.0 is out of the scope of this article. To learn more about Navigator 2.0, read this article.

On the positive side, we can use Flutter packages like go_router and Beamer, which are built upon Navigator 2.0, to simplify things for ourselves.

We are using the Beamer package for this project because of its flexibility in handling nested navigation. (It synchronizes the navigation history of both a nested Router and parent Router seamlessly.)

Implementation

You have probably noticed by now that although the majority of the code has been written, there are some tasks left for you to handle to construct our Flutter PWA. This section will walk you through implementing these TODOs.

First task: Starting up with Beamer

Our first task is to initialize the BeamerDelegate variable. Search for TODO: 1 in the lib/main.dart file, and assign the code below to the routerDelegate variable.

final routerDelegate = BeamerDelegate(
    locationBuilder: (routeInformation, _) {
        return HomeLocation();
    },
);

BeamerDelegate is Beamer's implementation of Navigation 2.0 RouterDelegate, which is used to build and configure a navigation widget based on the pop and push route intent it receives from the engine.

The locationBuilder helps Beamer determine what screen to show based on the developer's configuration. An instance of HomeLocation defined for this project is passed as an argument to the locationBuilder. The HomeLocation is an implementation of the BeamLocation.

By implementing BeamLocation, we can configure what URI to handle and how to build the stack of pages based on the URI. Take a look through the comments in the code snippet below.

class HomeLocation extends BeamLocation<BeamState> {
  @override
  List<BeamPage> buildPages(BuildContext context, BeamState state) {
    JobModel? job;

    // Try to get the job with the [id] passed from the route path
    try {
      job = context.provider.jobs.firstWhere(
          (element) => element.id.toString() == state.pathParameters['id']);
    } catch (e) {
      log(e.toString());
    }

    return [
      /// Always have the [MyHomePage] in the stack of pages
      const BeamPage(
        key: ValueKey('home'),
        title: "Home",
        name: '/',
        child: MyHomePage(
          currentIndex: 0,
        ),
      ),

      /// Only show the detail page over the [MyHomePage] when on a small screen and
      //a job id is passed alongside the URI. Note that [MyHomePage] is configured to be responsive.
      if (!context.isLargeScreen && state.pathParameters.containsKey('id'))
        BeamPage(
          key: ValueKey('job-${job!.id}'),
          title: "${job.company.name} - ${job.role}",
          /// The URL path to navigate to this page, the [id] is a placeholder for the actual job id to be passed
          name: '/:id',
          child: JobDetailWidget(
            model: job,
          ),
        ),
    ];
  }

  /// This is where you indicate the URI patterns that can be handled by this [BeamLocation]
  @override
  List<Pattern> get pathPatterns => ['/:id'];
}

A somewhat similar implementation of the above is done for the nested navigator. The beam location is named InnerJobLocation, which determines the current detail screen that is navigated to when the app is displayed on a large screen.

Second task: Determining what widget to return for small screens

The goal of this section is to determine what widget to return when the app is running on a small screen.

Locate TODO: 2 on line 123 and return the JobList widget;

return const JobList();

Third task: Determining what widget to return for large screens

Replace the TODO on line 134 with the code below to display a list-detail widget when the app runs on a large screen.

    return Container(
            color: Colors.white70,
            // Add a horizontal margin for the largest screen size
            margin: EdgeInsets.symmetric(horizontal: horizontalMargin),
            child: Row(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
                /// Display the [JobList] on the left pane and constrain its width
                SizedBox(width: listviewMaxWidth, child: const JobList()),
                /// Use a nested Router
                SizedBox(
                width: detailMaxWidth,
                /// By using the [Beamer] widget, we add a nested Router
                child: Beamer(
                    /// Pass in the [childBeamerKey] instantiated in the [AppProvider] class
                    key: context.provider.childBeamerKey,
                    /// Pass a routerDelegate that uses the [InnerJobLocations]
                    routerDelegate: innerRouterDelegate,
                ),
              ),
            ],
          ),
        );

Fourth task: Getting rid of exceptions

Remove the Exception thrown on line 155 that was added to keep the compiler happy in regard to missing a return statement.

Fifth task: making the beaming work

The final task is making the actual "beaming" --- in other words, the navigation when a job item widget is tapped on.

Now, we are faced with a minor issue. We have implemented two Routers: a parent Router and a nested Router that is added to the widget tree when the app is running on a device with a large screen. So we'll need to use a different instance of Beamer to navigate based on the screen size.

Head over to lib/widgets/job_list.dart and replace the TODO at line 40 with the code below.

context.isLargeScreen
    // Use the nested Beamer to navigate
    // to the correct detail page for large screen
    ? context.provider.childBeamerKey.currentState?.routerDelegate
        .beamToNamed('/${model.id}')
    : context.beamToNamed('/${model.id}');

Congrats on finishing these tasks! You can now run your web app by running flutter run -d chrome.

I know you're eager to download your Flutter PWA onto your mobile device, but we need to host our mobile web application. Luckily, Codemagic has simplified a lot of things for us.

Publishing a Flutter PWA with Codemagic

Codemagic is an excellent continuous integration/delivery (CI/CD) tool that works with Flutter. CI/CD tools automate building and deployment processes so that developers can focus on tasks like meeting product requirements and writing and maintaining high-quality code.

With Codemagic, you can automate the process of building for all platforms supported by Flutter. Here, we'll focus on setting up the web pipeline.

Start by logging in or creating an account if you don't have one by clicking here.
Add an application by clicking the Other -> Add repository button.
Input the repository URL, check the Public Repository checkbox, and select Flutter App as the project type.

You can use the repository URL for the completed version: git@github.com:JasperEssien2/pwa_demo.git

Select the platforms you want to build for in the Build for platforms section. Select only Web for now.

Scroll down to the Distribution section, enable Codemagic Static Page publishing, and input your desired web page subdomain.

Save your settings.
Click Start new build.
Relax and sip your coffee while Codemagic does the hard work of building and publishing your web app. Codemagic will notify you once it is done.

You can now access your published web page by visiting yourSubdomain/codemagic.app.

(yourSubdomain is the text you input in the Web page subdomain in step 5.)

Here's the app running on a Chrome browser for desktop.

You probably want your app to be hosted on your own domain. At the time of writing this article, Codemagic supports setting up automatic publishing of your web apps to AWS S3 Bucket. How to set this up is out of the scope of this article, but you can learn more in the docs.

Installing a PWA

iOS: Visit the web page on your Safari browser, and then tap Share -> Add to Home Screen -> Add.

At the time of writing this article, Chrome does not support the installation of PWA on iOS.
Android: Visit the web page on your Chrome browser, and tap the Add pwa_demo to Home Screen snackbar.

You can find the PWA among your installed apps on your mobile device. Open the app, and you should see a nice splash screen on startup.

By default, PWAs for Android have the splash screen enabled. To add splash screens for an iOS PWA, you have to specify this in the /web/index.html file --- click here to learn how to go about this. Generate splash screen images for specific iOS screen sizes by using this PWA toolkit.

Benefits of PWAs

Provide a legal way to have users install your iOS app without the headache of using app stores
Quick installation time
Small app size for your users
Native app-like features
Instant updates

Conclusion

You'll probably agree that Flutter is a great tool for PWA and, when combined with Codemagic, makes things a lot easier and smoother.

The next time you're faced with the problem introduced at the beginning of this article, don't fret --- you can simply utilize Flutter Web so that your users can install a PWA.

Up for a challenge? Currently, the web app works fine on a browser until a URL that contains an invalid job ID is accessed (e.g., pwa_demo.codemagic.app/60). The challenge is to direct users to an error screen that tells them the job they are trying to access does not exist. Cheers, and good luck.