Another Supabase Launch Week has passed, with some exciting new updates. During a previous launch week, I had participated in a hackathon by building a multiplayer quiz game with Flutter and Supabase, and I wrote about my experience in a blog post.

In this post, we will build a two-player, realtime Tic-tac-toe game. While parts of this are similar to Supaquiz, the multiplayer quiz game I built as part of the hackathon, this post is more of a how-to guide. It will also make use of Supabase's new anonymous login feature, which was implemented as a "hack" in the previous multiplayer game.

The full source code is on GitHub, so I will focus on snippets highlighting the main logic, rather than sharing snippets to build this step-by-step.

Set up Flutter and Supabase

Lets create an empty Flutter app, and then initialize Supabase in the project.

flutter create supatictactoe --empty
cd supatictactoe
supabase init

Then we can run supabase start to start Supabase locally. When running, we will have the Supabase URL and anon key which we will need for our secrets.dart file, which is .gitignore'd.

// secrets.dart
const supabaseUrl = 'http://127.0.0.1:54321';
const supabaseAnonKey = 'eyJhbGc...';

These secrets are used to initialise the Supabase client when setting up our dependencies:

final supabase = await Supabase.initialize(
    url: supabaseUrl,
    anonKey: supabaseAnonKey,
);

Anonymous login

This is a very simple but very useful feature of Supabase Auth, and I'm really happy it finally landed. When building Supaquiz, the anonymous login feature was quite hacky! It would create a random email and random password and log in the user. Because email verification was turned off, a user was logged in when opening the app. This meant we could not log in with the same user, but in the context of a trivia game played with friends, it wasn't that necessary.

The funny part about my previous anonymous hack is that the random emails I used had the dartling.dev domain, and ALL emails from that domain are forwarded to me. This meant that anyone who forked Supaquiz and tried to play, without noticing they have to disable email verification first, would cause random Supabase email verification emails to be sent to me, if they were running on Supabase dev. I wasn't expecting it, but I got quite a few of these emails!

Supabase now supports this out of the box. Here's how simple this is:

class AuthService {
  final GoTrueClient _auth;

  AuthService(this._auth);

  Future<AuthResponse> signIn() async {
    return _auth.signInAnonymously();
  }
}

No random email/password hacks, no random email confirmation emails in my inbox... it just works!

Game codes

Tic-tac-toe is a game for 2 players. In order to share the game with someone else, we implement "game codes" which can be shared. A user can "host" a game and share their game code. As soon as another user joins a game using that code, the game starts.

I go about using HashIds to convert game IDs to easy to share game codes in the Supaquiz article.

Database schema

For the database schema, we're going with a very simple approach. The board is stored as a 9-character string on a games table, defaulting to all zeroes. We can replace the zeroes with 1 or 2 depending on which player moves.

We also have a status, and we will listen to these status updates to start the game by moving to the game screen in the Flutter app, or showing the winner when completed.

The last_played is either 1 or 2 depending on which player moved last, so that we know which player is allowed to make a move. We default to 1 so that player 2 always goes first. The winner is a nullable integer which will be set to 1 or 2 if one of the player wins.

create type game_status as enum ('pending', 'started', 'complete');

create table games (
  id bigint generated by default as identity primary key,
  status game_status default 'pending' not null,
  board text not null default '000000000',
  last_played int not null default 1,
  winner int
);

-- To listen to status and board updates
alter publication supabase_realtime add table public.games;

The last line is used to add real-time support to the games table, as we want to react to status updates and board changes in the Flutter app.

The game service

The Supabase logic to create and update game is abstracted in a GameService. In the game service, we can create a new game, join a game (for the second player), and make a move in the board. We also have a method to stream the game "state", by listening to realtime updates.

New game

Future<Game> newGame() async {
  final game =
      await _supabaseClient.from('games').insert({}).select().single();
  final gameId = game['id'];
  final gameCode = _codeManager.toCode(gameId);
  log('Created game with code $gameCode (ID $gameId)');
  return Game(gameId, gameCode, 1);
}

New game creates a new game. Note that we don't need to pass any information to create it, all the values are set to the default ones: pending status and player 1 as last_played, and an empty board. We use the CodeManager class to convert the game ID to a game code, using HashIds.

Join game

Future<Game> joinGame(String gameCode) async {
  final gameId = _codeManager.toId(gameCode);
  log('Searching for game with code $gameCode (ID $gameId)');

  if (gameId == null) {
    throw InvalidGameCodeException('Invalid code');
  }

  final game = await _supabaseClient
      .from('games')
      .select()
      .eq('id', gameId)
      .maybeSingle();
  if (game == null) {
    throw InvalidGameCodeException('Invalid code');
  }

  final status = game['status'];
  log('Found game with status $status');
  if (status != 'pending') {
    throw InvalidGameCodeException('Game has already started');
  }

  await _supabaseClient
      .from('games')
      .update({'status': 'started'}).eq('id', gameId);

  return Game(gameId, gameCode, 2);
}

Join game accepts a game code, converts it to an ID, and looks up for the game by ID in the database. If a game is found, and the game is still pending (which means no one else joined), we update the game status to started. This will trigger the game to start for both players.

Play move

Future<void> playMove(Game game, GameState state, int index) async {
  if (state.lastPlayed == game.player || state.board[index] != 0) {
    return;
  }
  state.board[index] = game.player;
  await _supabaseClient.from('games').update({
    'board': state.board.join(),
    'last_played': game.player,
  }).eq('id', game.id);
}

A player can "move" to a square in the grid, only if it's their turn, and only if the square is empty. To make this change, we replace the board string at the selected index to either 1 or 2 depending on the player, and set the last_played field to the player.

Stream game state

Stream<GameState> streamState(int gameId) {
  return _supabaseClient
      .from('games')
      .stream(primaryKey: ['id'])
      .eq('id', gameId)
      .map((e) => toGameState(e.first));
}

GameState toGameState(Map<String, dynamic> game) {
  final status = GameStatus.fromString(game['status']);
  print(game['board']);
  final board = (game['board'] as String)
      .split('')
      .map((e) => int.tryParse(e) ?? 0)
      .toList();
  return GameState(status, board, game['last_played'], game['winner']);
}

Last but not least, we stream all updates to the game by its ID, in order to show the changes as they happen.

The game view

In Flutter, the main game screen is a StreamBuilder widget, which streams the game state from the GameService and shows the board in a 3x3 grid.

class GameView extends StatelessWidget {
  final Game game;

  const GameView({super.key, required this.game});

  @override
  Widget build(BuildContext context) {
    final textStyle = TextStyle(fontSize: 40);
    final colorScheme = Theme.of(context).colorScheme;

    return StreamBuilder<GameState>(
        stream: Services.of(context).gameService.streamState(game.id),
        builder: (context, snapshot) {
          if (snapshot.connectionState != ConnectionState.active ||
              snapshot.data == null) {
            return const SizedBox();
          }
          final state = snapshot.data!;
          log('Game status ${state.status}');
          if (state.status == GameStatus.complete) {
            return Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                Text(
                    state.winner != null
                        ? 'Player ${state.winner!} wins!'
                        : 'It\'s a tie!',
                    textAlign: TextAlign.center,
                    style: textStyle.copyWith(color: colorScheme.primary)),
                Text(
                    state.winner == game.player
                        ? 'Congratulations!'
                        : 'Better luck next time!',
                    textAlign: TextAlign.center,
                    style: textStyle),
              ],
            );
          }
          log('Game state updated with board ${state.board}');
          return Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              if (state.lastPlayed != game.player) Text('Your turn'),
              if (state.lastPlayed == game.player)
                Text('Waiting for Player ${game.secondPlayer}...'),
              GridView.builder(
                padding: const EdgeInsets.all(8.0),
                itemCount: 9,
                shrinkWrap: true,
                gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
                  crossAxisCount: 3,
                ),
                itemBuilder: (BuildContext context, int index) {
                  return GestureDetector(
                    onTap: () => _onTap(context, state, index),
                    child: Container(
                      decoration: BoxDecoration(
                        border: Border.all(color: colorScheme.secondary),
                      ),
                      child: Center(
                        child: Text(
                          state.getSquareLabel(index),
                          style: textStyle.copyWith(
                            color: state.board[index] == game.player
                                ? colorScheme.primary
                                : null,
                          ),
                        ),
                      ),
                    ),
                  );
                },
              ),
            ],
          );
        });
  }

  void _onTap(BuildContext context, GameState state, int index) {
    Services.of(context).gameService.playMove(game, state, index);
  }
}

We use GridView.builder to build the grid, if the game status is started . If the game status is complete, we skip the grid and show a message with the winner, if it's not a tie.

Winning

Notice that the game service does not have a method to determine the winner. We could add something there for this. For example, on every move, we could write some Dart code to check the board to see if there's a winner. If there is, we can update the game status to complete and set the winner.

While doing this on the client-side is a nice, simple way to do it, there is a different, although a bit more complicated way, to do this from the database with a function and a trigger.

First, we write a function check_winner() that checks the board for a winner. If there is one, it sets the game status to complete and updates the winner. If there's no winner, it checks if there are any empty squares left. If there aren't, it ends the game by also setting the status to complete, as there can be no winner.

-- Function to check if there is a winner and end the game
create function check_winner()
returns trigger as $$
begin
    -- check rows, columns and diagonals for a win
    if substring(new.board, 1, 1) = '1' and substring(new.board, 2, 1) = '1' and substring(new.board, 3, 1) = '1' or
       substring(new.board, 4, 1) = '1' and substring(new.board, 5, 1) = '1' and substring(new.board, 6, 1) = '1' or
       substring(new.board, 7, 1) = '1' and substring(new.board, 8, 1) = '1' and substring(new.board, 9, 1) = '1' or
       substring(new.board, 1, 1) = '1' and substring(new.board, 4, 1) = '1' and substring(new.board, 7, 1) = '1' or
       substring(new.board, 2, 1) = '1' and substring(new.board, 5, 1) = '1' and substring(new.board, 8, 1) = '1' or
       substring(new.board, 3, 1) = '1' and substring(new.board, 6, 1) = '1' and substring(new.board, 9, 1) = '1' or
       substring(new.board, 1, 1) = '1' and substring(new.board, 5, 1) = '1' and substring(new.board, 9, 1) = '1' or
       substring(new.board, 3, 1) = '1' and substring(new.board, 5, 1) = '1' and substring(new.board, 7, 1) = '1' then
        update games set status = 'complete', winner = 1 where id = new.id;
        return new;
    end if;

    if substring(new.board, 1, 1) = '2' and substring(new.board, 2, 1) = '2' and substring(new.board, 3, 1) = '2' or
       substring(new.board, 4, 1) = '2' and substring(new.board, 5, 1) = '2' and substring(new.board, 6, 1) = '2' or
       substring(new.board, 7, 1) = '2' and substring(new.board, 8, 1) = '2' and substring(new.board, 9, 1) = '2' or
       substring(new.board, 1, 1) = '2' and substring(new.board, 4, 1) = '2' and substring(new.board, 7, 1) = '2' or
       substring(new.board, 2, 1) = '2' and substring(new.board, 5, 1) = '2' and substring(new.board, 8, 1) = '2' or
       substring(new.board, 3, 1) = '2' and substring(new.board, 6, 1) = '2' and substring(new.board, 9, 1) = '2' or
       substring(new.board, 1, 1) = '2' and substring(new.board, 5, 1) = '2' and substring(new.board, 9, 1) = '2' or
       substring(new.board, 3, 1) = '2' and substring(new.board, 5, 1) = '2' and substring(new.board, 7, 1) = '2' then
        update games set status = 'complete', winner = 2 where id = new.id;
        return new;
    end if;

    -- check if the board has no zeroes indicating a full board
    if position('0' in new.board) = 0 then
        update games set status = 'complete' where id = new.id;
    end if;

    return new;
end;
$$ language plpgsql;

We define a trigger to call this function after every update of the board field of each game.

-- Trigger check winner function after each board update
create trigger trigger_check_winner
after update of board on games
for each row
execute function check_winner();

You could easily argue that this is way too much complexity, and doing it on the client is the easiest way. I agree. But having the backend (in this case the database) rather than the client determine the winner feels more "right".

Wrapping up

In this post, we built a realtime Tic-tac-toe game with Flutter and Supabase. We made use of Supabase Auth's new anonymous login feature, which was released last week as part of the Supabase Launch (GA) Week.

You can find the full source code here.

If your mobile or web app requires user management, you're going to need a way for your users to sign up. By now, developers do not try to reinvent the wheel and write their own auth solutions, and can either use self-hosted or managed auth solutions (and preferably open-source!).

Traditionally, you sign up for an app using your username or email, and a password. While still widely used, password-less login is becoming increasingly popular, allowing users to sign up just by providing an email or a phone. With password-less login, users receive a one-time password (OTP) or a "magic link" that is used to sign them in.

In this tutorial, we will go over how you can easily set up password-less login in a Flutter app with Supabase Auth via one-time password through email. We will also discuss the benefits of the password-less approach and potential drawbacks.

Why go password-less?

Password-less login can be beneficial for two main reasons. Firstly, security. If you don't have to store passwords, you don't have to worry about passwords getting leaked, or hackers attempting to guess a user's password (either by a brute force approach or social engineering).

Secondly, and perhaps more importantly depending on how you see it, is user convenience. Not requiring a separate sign-up flow for your users, and simply allowing them to sign up (and in) to your app by tapping on a link sent to their email or filling in a code emailed or texted to them can reduce friction when getting new users. While you could argue that signing in with a password is quicker, especially when using a password manager, the initial sign-up process can be time-consuming, and could cause potential users to skip signing up and look for another app.

Why not?

Despite these benefits, there are potential drawbacks and considerations to keep in mind.

Recovering access to an account can be challenging if a user has lost access to their email. With passwords, you could sign in to your account and change your email. Instead, users would have to contact the app developers or go through customer support to regain access, and even then, you will need a way to verify that the user is who they say they are. However, you could still mitigate this by requiring both an email and a phone number (though this might again introduce some additional friction in the sign-up flow). You could also prompt users to add a phone number (or email if they signed up with a phone number) later, or even a backup password, as a way to better secure their account. This way, you'd still get the benefits of a quick user sign-up.

Another important point to consider is dependency on external services. To receive a one-time password or magic link, you will likely rely on an external service to send an email or SMS. This could mean additional costs, but also an additional point of failure; if the email service you use is down, for example, your users won't be able to log in at all. This also becomes a bit easier to deal with if you support logging in with passwords in addition to password-less.

Supabase Auth

One way to implement password-less login in Flutter apps is with Supabase Auth. Supabase is an open-source alternative to Firebase, providing services such as a Postgres database, instant APIs, edge functions and storage, in addition to authentication.

I had previously written about using Supabase with Flutter, introducing its database offering, as well as password-based auth. Supabase has gone a long way since then, and so has its integration with Flutter and the Dart/Flutter SDK.

You can use Supabase Auth in your Flutter projects on its own, without having to use any additional Supabase product.

Password-less login

Let's get started on implementing password-less login in a new Flutter app. To start, let's create a new Flutter project.

flutter create passwordless --empty
cd passwordless

This creates a new Flutter project called passwordless, in the passwordless directory. We use the --empty flag to only start with the bare minimum, otherwise we'd get a sample counter app with a lot of comments describing what everything does.

Setting up Supabase Auth

Getting started with Supabase is quick and easy using the Supabase CLI.

supabase init
supabase start

The init command initializes Supabase in our passwordless directory, and start runs the Supabase services locally.

Next, let's add the Supabase client library to our Flutter app.

flutter pub add supabase_flutter

This updates the dependencies in the project's pubspec.yaml, adding the Supabase Flutter SDK's latest version:

dependencies:
  supabase_flutter: ^2.0.2

Now, we need to initialize Supabase before running the app. When running Supabase locally with supabase start, the API URL and anon key were logged in the terminal. We need these when initializing the Supabase client.

// lib/main.dart
import 'package:flutter/material.dart';
import 'package:passwordless/secrets.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Supabase.initialize(
    url: supabaseUrl,
    anonKey: supabaseAnonKey,
  );
  runApp(const MainApp());
}

We don't want to commit these properties to version control, so we're adding them as constants in a file named secrets.dart which is included in the .gitignore file.

// secrets.dart
const supabaseUrl = 'http://127.0.0.1:54321';
const supabaseAnonKey = 'eyJhbGciOiJR5cCI6IkpXVCJ9.eyQwgnWNReilDMblYTn_I0';

In the repository, the secrets_sample.dart file has the same structure with empty strings. If you're cloning this repo, simply copy this file to a new filed named secrets.dart and fill in the properties with either the local URL and key or your live Supabase project.

One-time-password via email

Now that everything is set up, we can start implementing the OTP via email flow. The flow is simple:

• User taps on button sign in via OTP

• User is shown a new screen in which they need to submit the OTP

• User inputs the OTP received via email to sign in

First, we start with a main screen with just the e-mail OTP sign in option:

// main.dart
class MainApp extends StatelessWidget {
  const MainApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Passwordless'),
        ),
        body: Center(
          child: Column(
            children: [
              SignInOptionButton(
                label: 'Sign in with OTP (email)',
                screen: EmailOtpScreen(),
              )
            ],
          ),
        ),
      ),
    );
  }
}

class SignInOptionButton extends StatelessWidget {
  const SignInOptionButton({
    super.key,
    required this.label,
    required this.screen,
  });

  final String label;
  final Widget screen;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: OutlinedButton(
        onPressed: () {
          final route = MaterialPageRoute(builder: (context) => screen);
          Navigator.push(context, route);
        },
        child: Text(label),
      ),
    );
  }
}

Next, the user needs to input their email address to receive their one-time password.

Above is the EmailOtpScreen widget in action, below the code:

// screens/email_otp_screen.dart
class EmailOtpScreen extends StatelessWidget {
  EmailOtpScreen({super.key});

  final _emailController = TextEditingController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          children: [
            Padding(
              padding:
                  const EdgeInsets.symmetric(vertical: 16.0, horizontal: 24.0),
              child: TextField(
                controller: _emailController,
                keyboardType: TextInputType.emailAddress,
                decoration: const InputDecoration(
                  border: OutlineInputBorder(),
                  hintText: 'Enter your e-mail',
                ),
              ),
            ),
            OutlinedButton(
              onPressed: () {
                final email = _emailController.text;
                final supabase = Supabase.instance.client;
                supabase.auth.signInWithOtp(email: email);
                final route = MaterialPageRoute(
                  builder: (context) => VerifyOtpScreen(email: email),
                );
                Navigator.pushReplacement(context, route);
              },
              child: const Text('Get OTP'),
            )
          ],
        ),
      ),
    );
  }
}

The two lines below are all we need to send an email with the OTP to the email supplied through the text field.

final supabase = Supabase.instance.client;
supabase.auth.signInWithOtp(email: email);

If you're following along and you've just tried to sign in, you'll be expecting to receive an email by now... But we're running Supabase locally, so no emails are being sent. We could set up a live Supabase project and switch the secrets to point there to receive emails, but for now we're going to keep working locally. When running Supabase locally, we can still test the email flows thanks to Inbucket, a tool which lets you receive outgoing emails through a web interface. When running supabase start, along with the Supabase URL and anon key we used to initialize the client, the Inbucket URL was also logged. If we follow that URL, we'll see the contents of the email that would have been sent if we were working with a live Supabase project.

You'll notice the email mentions "magic link" and includes both a log in link (the magic link), as well as the code. This is due to the email template, which we can customize. Currently, it doesn't look like we can customize the template when running Supabase locally, but we can do so in a deployed Supabase project. If your app does not support magic links, you can remove the magic link from the email template and send the OTP only.

After tapping on "Get OTP", we redirected to a new screen to verify the OTP. Let's put in the code from the email:

// screens/verify_otp_screen.dart
class VerifyOtpScreen extends StatelessWidget {
  VerifyOtpScreen({super.key, required this.email});

  final String email;
  final _otpController = TextEditingController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          children: [
            Padding(
              padding:
                  const EdgeInsets.symmetric(vertical: 16.0, horizontal: 24.0),
              child: TextField(
                controller: _otpController,
                keyboardType: TextInputType.number,
                decoration: const InputDecoration(
                  border: OutlineInputBorder(),
                  hintText: 'Enter the 6-digit code',
                ),
              ),
            ),
            OutlinedButton(
              onPressed: () async {
                final navigator = Navigator.of(context);
                final scaffoldMessenger = ScaffoldMessenger.of(context);
                try {
                  final response =
                      await Supabase.instance.client.auth.verifyOTP(
                    email: email,
                    token: _otpController.text,
                    type: OtpType.email,
                  );
                  final route = MaterialPageRoute(
                      builder: (_) => SuccessScreen(user: response.user!));
                  navigator.pushReplacement(route);
                } catch (err) {
                  scaffoldMessenger.showSnackBar(
                      const SnackBar(content: Text('Something went wrong')));
                }
              },
              child: const Text('Verify OTP'),
            )
          ],
        ),
      ),
    );
  }
}

To verify the OTP, we need to pass the email passed from the previous screen, as well as the token/code. We also need to specify the OTP type, which for this case is email.

Let's go over the Supabase code to see what's happening:

// keep references to both the navigator and scaffold messenger 
// as the verifyOTP method is async and we should not use the 
// context across async gaps
final navigator = Navigator.of(context);
final scaffoldMessenger = ScaffoldMessenger.of(context);
try {
  // pass the email from previous screen, OTP from the text field
  final response =
      await Supabase.instance.client.auth.verifyOTP(
    email: email,
    token: _otpController.text,
    type: OtpType.email,
  );
  // if a response is received with no error thrown, we assume
  // the response contains a valid user, so we show a success screen
  final route = MaterialPageRoute(
      builder: (_) => SuccessScreen(user: response.user!));
  navigator.pushReplacement(route);
} catch (err) {
  // if an error is thrown, for example if the OTP is wrong, we show
  // a generic error (but ideally we explain what actually went wrong)
  scaffoldMessenger.showSnackBar(
      const SnackBar(content: Text('Something went wrong')));
}

If the OTP is correct, we should now be redirected to the success screen.

// screens/success_screen.dart
class SuccessScreen extends StatelessWidget {
  const SuccessScreen({super.key, required this.user});

  final User user;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          children: [
            const Text('You are now logged in!'),
            Text('Email: ${user.email ?? '--'}'),
          ],
        ),
      ),
    );
  }
}

We've successfully signed in to our app! Since this is the first sign-in, we are also automatically signed up.

For better security, as discussed previously, we could require users to sign up with an email and password, and only allow logins via OTP later. In this case, we would need to set the shouldCreateUser flag to false for the login via OTP.

Supabase.instance.client.auth.signInWithOtp(
  email: email,
  shouldCreateUser: false,
);

Updating the email template

Previously, we saw that the email we received (through Inbucket) contained a magic link as well. We haven't added support for magic links in this project, so we should update the email template to stop sending them.

To do this, we first had to set up a live Supabase project, and change the settings to point to that instead of the local Supabase services. From the project dashboard, we can edit the email templates from the Auth tab.

This was the template:

<h2>Magic Link</h2>

<p>Follow this link to login:</p>
<p><a href="{{ .ConfirmationURL }}">Log In</a></p>

<p>Alternatively, enter the code: {{ .Token }}</p>

And this is how we change it to look to avoid including a magic link:

<h2>Your one-time password</h2>

<p>This is your one-time password to sign in to Passwordless: {{ .Token }}</p>

Wrapping up

In this tutorial, we showed how we can easily support password-less login in Flutter via email OTP with Supabase. You can find the source code here.

Supabase Auth also supports password-less login via one-time password through phone, as well as magic links. We've only focused on the email OTP flow in this tutorial, but we could cover these other two approaches in the future. If you're interested, please let me know in the comments!

ChatGPT and AI-powered tools have been increasingly popular these days. Most recently, a lot of websites, apps and services have integrated ChatGPT or ChatGPT-like tools so you can "chat" with their documentation and content, most notably Supabase Clippy.

In this tutorial, we will build our own ChatGPT, with which we'll be able to store any documents in text format, and ask it questions about these documents. And while Python and JavaScript/TypeScript have been the most popular choices for such tools, we'll be doing this in Dart!

Why Dart? Well, this is a Dart and Flutter blog after all. For a Flutter app with AI capabilities, the AI backend could be written in any language. But why not Dart? It makes things easier as the full stack is written in the same language, and models such as requests and responses can be reused. And while some could argue that the Dart libraries are not as advanced, for this ChatGPT clone we only really need two things: Supabase Vector and OpenAI, both of which have available Dart packages.

Setting up the project

To keep things simple, we'll build our ChatGPT clone as a simple API with two endpoints: one for "embedding" new information, where we upload any documents/text we would like to ask questions on, and a chat endpoint to ask questions and get answers based on the uploaded documents.

We will use Dart and the shelf package for the API. Supabase will be used to store the documents as well as their embeddings, which will be used to perform similarity search thanks to Supabase's pgvector plugin.

Let's create our new Dart project:

dart create dart_ai_api
cd dart_ai_api

Our first dependencies to build out the API are shelf, shelf_router and dart_openai:

dart pub add shelf
dart pub add shelf_router
dart pub add dart_openai

Next, we're adding Supabase as a dependency, but also initializing a Supabase project within our Dart project.

dart pub add supabase
supabase init

For additional information on the Supabase project initialization, check out the documentation here.

Supabase Vector

Supabase Vector is actually a set of tools to help you build AI apps, and what we'll actually be using for this project is pgvector, a Postgres extension which allows you to store and query vectors in Postgres. And if you're new to Supabase, the Supabase service includes a Postgres database!

Preparing the database

In the seed file, we will create a table to store documents and embeddings, as well as a function to perform similarity search. First, we need to enable the pgvector plugin.

-- supabase/seed.sql
create extension vector with schema extensions;

Next, the documents table:

-- supabase/seed.sql
create table documents (
  id serial primary key,
  title text not null,
  body text not null,
  embedding vector(1536)
);

And last but not least, the similarity search function:

-- supabase/seed.sql
create or replace function match_documents (
  query_embedding vector(1536),
  match_threshold float,
  match_count int
)
returns table (
  id bigint,
  body text,
  similarity float
)
language sql stable
as $$
  select
    documents.id,
    documents.body,
    1 - (documents.embedding <=> query_embedding) as similarity
  from documents
  where 1 - (documents.embedding <=> query_embedding) > match_threshold
  order by similarity desc
  limit match_count;
$$;

There is a lot to explain, but the documentation over at Supabase does a good job introducing all the concepts. So I won't be going too in-depth on the details and rather focusing on getting this to work in Dart.

At this point we could run our Supabase project locally, which will create the database including the documents table and function.

supabase start

The Dart API

Let's build the Dart API next. We'll start with an AI service class, which will handle the interactions with Supabase and OpenAI. This service will then be called by the endpoint handlers.

class AIService {
  static const _openAiKey = "SECRET";
  static const _supabaseUrl = "http://localhost:54321";
  static const _supabaseKey = "SECRET";

  final OpenAI openAi;
  final SupabaseClient supabase;

  factory AIService.init() {
    OpenAI.apiKey = _openAiKey;
    final supabase = SupabaseClient(_supabaseUrl, _supabaseKey);
    return AIService(OpenAI.instance, supabase);
  }

  AIService(this.openAi, this.supabase);
}

The embed method will receive a document's title and body, and store this data along with the embeddings created by calling the OpenAI API. For the embedding model we use text-embedding-ada-002, which is recommended by OpenAI for most use cases. Note that we should use the same model for all embeddings, otherwise similarity search will not work.

void embed(EmbedRequest request) async {
  final response = await openAi.embedding.create(
    model: "text-embedding-ada-002",
    input: request.body,
  );
  final embedding = response.data.first.embeddings;
  await supabase.from("documents").insert({
    "title": request.title,
    "body": request.body,
    "embedding": embedding,
  });
}

The second and last method of our AI service is the chat functionality. It does several things:

• Creates an embedding of the question we pass to it, similar to the embed functionality previously.
• Uses that embedding to perform similarity search on our existing saved documents, using the function we created during the database setup step.
• Calls the OpenAI Chat API with a system prompt including any relevant documents found as the context, as well as the question.

Future<String> chat(ChatRequest request) async {
  // create an embedding of the message to perform similarity search
  final embeddingResponse = await openAi.embedding.create(
    model: "text-embedding-ada-002",
    input: request.message,
  );
  final embedding = embeddingResponse.data.first.embeddings;

  // retrieve up to 5 most similar documents to include in chat system prompt
  final results = await supabase.rpc('match_documents', params: {
    'query_embedding': embedding,
    'match_threshold': 0.8,
    'match_count': 5,
  });

  // combine document content together
  var context = '';
  for (var document in results) {
    document as Map<String, dynamic>;
    final content = document['body'] as String;
    context += '$content\n---\n';
  }

  final prompt = """
      You are a helpful AI assistant.
      Given the following sections, answer any user questions by
      using only that information.
      If you are unsure and the answer is not explicitly written in
      the sections below, say "Sorry, I can't help you with that."

      Context sections:
      $context
    """;

  final chatResponse =
      await openAi.chat.create(model: 'gpt-3.5-turbo', messages: [
    OpenAIChatCompletionChoiceMessageModel(
        role: OpenAIChatMessageRole.system, content: prompt),
    OpenAIChatCompletionChoiceMessageModel(
        role: OpenAIChatMessageRole.user, content: request.message),
  ]);
  return chatResponse.choices.first.message.content;
}

Why similarity search?

A request to OpenAI's Chat API has a maximum token limit. We cannot just give it all our documents as the context in the prompt. Because of this, similarity search through vector embeddings is a solution for this. Of course, this depends on the total number of documents, and if there's only a few, this could still be possible. Additionally, the more tokens that are part of the request, the more expensive the API call.

In the chat method above, you can see from the RPC call to Supabase that we are only returning the 5 most relevant documents that are past the threshold. Both the threshold and count parameters can be tweaked as desired. By only passing the few most relevant documents to OpenAI, we can get a better, faster, and cheaper response.

API routes

The last piece is the router which route the API requests to the appropriate AI service method. The shelf and shelf_router packages make this quite easy.

void run() async {
  final app = Router();
  final ai = AIService.init();

  app.post('/embed', (Request request) async {
    try {
      final json = await _requestToJson(request);
      ai.embed(EmbedRequest.fromJson(json));
      return Response.ok('embedding saved');
    } catch (err) {
      print(err);
      return Response.internalServerError(body: 'something went wrong');
    }
  });

  app.post('/chat', (Request request) async {
    try {
      final json = await _requestToJson(request);
      final response = await ai.chat(ChatRequest.fromJson(json));
      return Response.ok(response);
    } catch (err) {
      print(err);
      return Response.internalServerError(body: 'something went wrong');
    }
  });

  final server = await io.serve(app, 'localhost', 8080);
  print('Server running on localhost:${server.port}');
}

Future<Map<String, dynamic>> _requestToJson(Request request) async {
  final reqString = await request.readAsString();
  return jsonDecode(reqString);
}

After this, we are now ready to run our Dart server. Make sure to start Supabase as well if not already running.

supabase start
dart run

The API in action

We can now store documents by calling the /embed endpoint:

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"title":"Flutter","body":"Flutter is an open-source, cross-platform UI software development kit"}' \
  http://localhost:8080/embed

And ask questions by calling the /chat endpoint:

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"message":"What is Flutter?"}' \
  http://localhost:8080/chat

The answer to the above question should be taken from the previous data we stored! We can now use this API to store any kind of information we want, and ask questions about it.

Wrapping up

In this post, we built our own ChatGPT API which we can use to store textual data and ask questions on it, all in Dart, and with the help of Supabase and the OpenAI API. You can find the full source code here.

Supabase has recently had its 7th Launch Week, with lots of new features and functionality shipped by the Supabase team as well as the community.

One of the community highlights was Dart Edge for Supabase Edge Functions. Built by Invertase, Dart Edge allows you to write your edge functions in Dart. It supports Vercel, Cloudflare Workers, and now Supabase Edge Functions, which until recently only supported writing functions with TypeScript. However, it is still experimental!

Being able to write our edge functions with Dart is amazing news for Flutter developers. It allows us to write Dart for both the front-end and any back-end code we need, which also means we can share Dart code, such as the request/response models. And while Supabase's database functions can be quite powerful, an edge function can do additional things such as call third-party APIs and services, and even bypass RLS policies if necessary.

In this post, we will explore Dart Edge with Supabase Edge Functions. We will build a simple app with Dart on the full stack, using a Flutter app front-end and a Dart Edge function as our back-end. We'll keep things simple by starting with the classic Flutter counter app but using an edge function to get the current count and increment it.

Set up an edge function

First, we need both the Supabase CLI and edge CLI. For the edge CLI, simply run:

dart pub global activate edge

The Supabase CLI can be installed through NPM or either Homebrew or Scoop depending on your operating system, so check out the documentation here.

Now, let's set up a Dart Edge project:

edge new supabase_functions edge_functions
cd edge_functions
supabase init

edge_functions is the name of our project and the name of the newly created directory. We run supabase init to generate the Supabase config.

The newly generated edge_functions directory is a typical Dart project with a pubspec.yaml file with the required dependencies. It has a main.dart file with a simple response to get us started:

// edge_functions/lib/main.dart
void main() {
  SupabaseFunctions(fetch: (request) {
    return Response("Hello from Supabase Edge Functions!");
  });
}

To run the edge function locally, we need to build the function and run Supabase:

edge build supabase_functions
supabase start
supabase functions serve dart_edge --no-verify-jwt

We can also use the --dev flag when running edge build to recompile when we make any changes to the code.

By default, the edge function is expected to have a valid authorization header. We pass the --no-verify-jwt flag so we can run the function without one.

We can now access the local edge function at http://localhost:54321/functions/v1/dart_edge

To deploy the function, we can build it and then run the following command:

supabase functions deploy dart_edge

Connect to Supabase from the edge

The current edge function only returns some text in the response. In a real app, we would likely want to interact with our database, make some third-party service calls, or both.

dart pub add supabase
dart pub add edge_http_client

The supabase package has all we need to interact with the Supabase database, but we also need to use a special HTTP client.

We can now instantiate a Supabase client:

final supabase = SupabaseClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!,
  httpClient: EdgeHttpClient(),
);

A couple of notes on the above snippet:

• The Supabase credentials are already available by default in the environment variables.

• The service role key bypasses Row Level Security, meaning we can access and edit all data of all users. Since this is for an edge function, it's fine, but we could also use the anon key (SUPABASE_ANON_KEY environment variable) if that's a concern.

We now have access to the Supabase database from our edge function. Let's modify the function's logic to do two things:

1. Return the counter's current value if we make a GET request.

2. Increment the counter by 1 if we make a POST request.

We'll first need to create the database table that will hold our increments. These SQL statements are added to the seed.sql file.

-- edge_functions/supabase/seed.sql
create table increments (
  id bigint generated by default as identity primary key,
  amount int default 0 not null
);

create function get_count()
returns numeric as $$
  select sum(amount) from increments;
$$ language sql;

We also create a SQL function that returns the current count by summing up all the increments.

Now let's update our edge function's main method:

// edge_functions/lib/model/counter_response.dart
class CounterResponse {
  final int count;

  CounterResponse(this.count);

  factory CounterResponse.fromJson(Map<String, dynamic> json) =>
      CounterResponse(json['count'] as int);

  Map<String, dynamic> get toJson => {'count': count};
}

// edge_functions/lib/main.dart
void main() {
  SupabaseFunctions(fetch: (request) async {
    final client = SupabaseClient(
      Deno.env.get('SUPABASE_URL')!,
      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!,
      httpClient: EdgeHttpClient(),
    );

    if (request.method == 'POST') {
      await client.from('increments').insert({'amount': 1});
    }
    final count = await client.rpc('count').single() as int;
    final response = CounterResponse(count);
    return Response.json(response.toJson);
  });
}

If the request is a POST, we increment the count by 1. For all requests, we fetch the current count and return it in the response. To fetch the count, we're calling a SQL function within an edge function!

Call the function from Flutter

With the edge function ready to go, we will now create the Flutter counter app, and update it so that the count display and increment button work by calling the edge function.

flutter create app

We'll be calling the function with the http package, but we're also going to need to add the edge_functions package as a local dependency. This is so we can reuse the CounterResponse model.

Here are the current dependencies (pubspec.yaml) for the Flutter app:

dependencies:
  flutter:
    sdk: flutter
  counter_edge_functions:
    path:  '../edge_functions'
  http: ^0.13.5

At the moment of writing, there seems to be a dependency issue due to the path package, so I had to remove flutter_test as a dev dependency to get this to work. A nicer fix for this would be to move the model to a separate local package instead and have it as a dependency for both the edge function package and the Flutter app.

Let's also encapsulate the interactions with the edge function to a repository:

import 'dart:convert';

import 'package:counter_edge_functions/model/counter_response.dart';
import 'package:http/http.dart' as http;

class CounterRepository {
  static final _functionUrl =
      Uri.parse('http://localhost:54321/functions/v1/dart_edge');

  Future<CounterResponse> get count async {
    final response = await http.get(_functionUrl);
    final body =
        jsonDecode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>;
    return CounterResponse.fromJson(body);
  }

  Future<CounterResponse> increment() async {
    final response = await http.post(_functionUrl);
    final body =
        jsonDecode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>;
    return CounterResponse.fromJson(body);
  }
}

The final piece is to call the repository methods from our widgets. There are not that many changes compared to the generated counter app code from the template, but here is the final result:

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

  @override
  Widget build(BuildContext context) {
    final repository = CounterRepository();
    return MaterialApp(
      title: 'Edge Counter',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      // Fetch the initial count from the Edge Function.
      home: FutureBuilder<CounterResponse>(
        future: repository.count,
        builder: (context, snapshot) {
          if (snapshot.connectionState != ConnectionState.done) {
            return const SizedBox();
          }
          return MyHomePage(
            title: 'Edge Counter',
            initialCount: snapshot.data?.count ?? 0,
            onIncrement: repository.increment,
          );
        },
      ),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({
    super.key,
    required this.title,
    required this.initialCount,
    required this.onIncrement,
  });

  final String title;
  final int initialCount;
  final Future<CounterResponse> Function() onIncrement;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late int _counter;

  // Increment through the Edge Function, and update with the latest count.
  Future<void> _incrementCounter() async {
    final response = await widget.onIncrement();
    setState(() {
      _counter = response.count;
    });
  }

  @override
  void initState() {
    super.initState();
    _counter = widget.initialCount;
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'Users have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

We wrap the home page in a FutureBuilder to start with the current counter value, and call the increment method on button click. The count persists across restarts, and if we were using a deployed function rather than a local one, we could even share the app with friends and have everyone increment it at the same time!

Wrapping up

In this post, we talked about the experimental Dart Edge, allowing us to write Dart on the full stack - by using Flutter and Supabase. We created a very simple edge function that interacts with our database, and an even simpler Flutter counter app that calls the edge function to increment the counter.

You can find the full source code here.

If you found this helpful and would like to be notified of future tutorials, please follow the blog or subscribe to the newsletter with your email below!

In this blog post, we will build a simple conversational interface to chat with OpenAI's ChatGPT through its API.

There has been a lot of hype with OpenAI and ChatGPT lately, especially with GPT-4 being released recently. A ton of use cases for such tools have been popping up, but the most popular way people have been using ChatGPT so far is through chat.openai.com. I've been using ChatGPT to brainstorm ideas, write some Flutter code snippets, and even write the outline for this blog post! Of course, its suggested outline was quite optimistic so I had to leave some sections out, but it still provided enough pointers for me to be able to get started right away.

The official chat experience at OpenAI's chat interface is not great, however. It's very limited, and the chat history is often not working properly. There are already people building client apps for ChatGPT with a better UI and user experience, such as TypingMind, built with web technologies.

As a Flutter developer, I can't help but think that Flutter is a great fit for a ChatGPT client app! With cross-platform capabilities and a rich set of UI components, Flutter is a perfect choice for such a project. We can write the code once, and we could publish our app on the web, iOS, Android, and also the desktop platforms: Windows, macOS and Linux.

The ChatGPT API

To use any of OpenAI's APIs, you'll need to sign up and get an API key. You can do this here. Please note that API usage can cost money and you will need to provide payment details. The gpt-3.5-turbo model specifically, which we will be using, is quite cheap and should not cost more than a few cents unless you use it a lot.

Specifically, we will be using the Chat API (chat completions), which supports two of OpenAI's models: gpt-3.5-turbo and gpt-4. We can find the full reference for the Chat API here, which involves performing a POST request at https://api.openai.com/v1/chat/completions.

At this point, we could use the http library to perform the request with the required data to the Chat API, and parse the response. However, thanks to the Dart and Flutter communities, there is already a package available on pub.dev: dart_openai. It will make the API request for us and return a parsed response, so we can simply grab the response text and display it in the app.

Here is what a method that accepts a user message and returns ChatGPT's response looks like:

Future<String> completeChat(String message) async {
  final chatCompletion = await OpenAI.instance.chat.create(
    model: 'gpt-3.5-turbo',
    messages: [
      OpenAIChatCompletionChoiceMessageModel(
        content: message,
        role: 'user',
      ),
    ],
  );
  return chatCompletion.choices.first.message.content;
}

Since this will be a conversation, we need to pass previous messages to the request, so that ChatGPT has the whole context of the conversation so far, and not just the user's last message.

class ChatMessage {
  ChatMessage(this.content, this.isUserMessage);

  final String content;
  final bool isUserMessage;
}

Future<String> completeChat(List<ChatMessage> messages) async {
  final chatCompletion = await OpenAI.instance.chat.create(
    model: 'gpt-3.5-turbo',
    messages: [
      ...previousMessages.map(
        (e) => OpenAIChatCompletionChoiceMessageModel(
          role: e.isUserMessage ? 'user' : 'assistant',
          content: e.content,
        ),
      ),
    ],
  );
  return chatCompletion.choices.first.message.content;
}

The above method accepts the user's last message and all previous messages in the conversation. Note that ChatGPT's responses are marked with the role assistant in the API request.

Let's put the final version of our completeChat method to a ChatApi class, to be used later.

// models/chat_message.dart
class ChatMessage {
  ChatMessage(this.content, this.isUserMessage);

  final String content;
  final bool isUserMessage;
}

// api/chat_api.dart
import 'package:chatgpt_client/models/chat_message.dart';
import 'package:chatgpt_client/secrets.dart';
import 'package:dart_openai/openai.dart';

class ChatApi {
  static const _model = 'gpt-3.5-turbo';

  ChatApi() {
    OpenAI.apiKey = openAiApiKey;
    OpenAI.organization = openAiOrg;
  }

  Future<String> completeChat(List<ChatMessage> messages) async {
    final chatCompletion = await OpenAI.instance.chat.create(
      model: _model,
      messages: messages
          .map((e) => OpenAIChatCompletionChoiceMessageModel(
                role: e.isUserMessage ? 'user' : 'assistant',
                content: e.content,
              ))
          .toList(),
    );
    return chatCompletion.choices.first.message.content;
  }
}

Note that in the constructor, we are setting the API key and organization ID. Without the API key, any request will fail. Organization ID is optional and can be provided in case you have multiple organizations set up with the OpenAI platform.

// secrets.dart
const openAiApiKey = 'YOUR_API_KEY';
const openAiOrg = 'YOUR_ORGANIZATION_ID';

The secrets file is included in .gitignore to avoid committing it to version control. In the project repository on GitHub, a secrets_example.dart file is provided with placeholder values.

A note on API keys

In this post, we are building a client app. An app like this one with the API key hard-coded should not be published. Since API usage can cost, you don't want to expose your API key.

If you want to publish such an app, you have two options:

1. Allow users to provide their own API key to start chatting. Users can provide their key through the app and you can securely store it in local storage, to be used in every API request.

2. Rather than calling the Chat API directly, call a server, or edge function which will then call the Chat API with your own token. This way, you won't expose your API key, can control the traffic, as well as have additional authorization and rate-limiting requirements. If you go with this approach, you might want to consider monetizing, as users who use the app a lot will cost you money!

The chat interface

With the Chat API ready to be used, it's time to build the UI. If you're starting from scratch, you can use flutter create to initialize a Flutter project:

flutter create my_chatgpt_client

The UI will be pretty standard and will contain two main widgets: the message composer, and the message bubble. The main screen will be a list of all messages in the chat (as message bubbles), with the message composer at the bottom where we can type in the messages.

Let's start with the message composer widget:

// widgets/message_composer.dart
import 'package:flutter/material.dart';

class MessageComposer extends StatelessWidget {
  MessageComposer({
    required this.onSubmitted,
    required this.awaitingResponse,
    super.key,
  });

  final TextEditingController _messageController = TextEditingController();

  final void Function(String) onSubmitted;
  final bool awaitingResponse;

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(12),
      color: Theme.of(context).colorScheme.secondaryContainer.withOpacity(0.05),
      child: SafeArea(
        child: Row(
          children: [
            Expanded(
              child: !awaitingResponse
                  ? TextField(
                      controller: _messageController,
                      onSubmitted: onSubmitted,
                      decoration: const InputDecoration(
                        hintText: 'Write your message here...',
                        border: InputBorder.none,
                      ),
                    )
                  : Row(
                      mainAxisAlignment: MainAxisAlignment.center,
                      children: const [
                        SizedBox(
                          height: 24,
                          width: 24,
                          child: CircularProgressIndicator(),
                        ),
                        Padding(
                          padding: EdgeInsets.all(16),
                          child: Text('Fetching response...'),
                        ),
                      ],
                    ),
            ),
            IconButton(
              onPressed: !awaitingResponse
                  ? () => onSubmitted(_messageController.text)
                  : null,
              icon: const Icon(Icons.send),
            ),
          ],
        ),
      ),
    );
  }
}

The message composer will call the onSubmitted method we pass to it when the text field is submitted (e.g. by pressing Enter), or when we tap on the send button on the right. With the awaitingResponse flag, we can hide the text field and disable the send button. We will set this flag to true while a message submission is in progress and we await the API's response.

The message bubble widget is a simple container, with a different background color and sender name depending on whether it's a user message or an AI-generated one:

// widgets/message_bubble.dart
import 'package:flutter/material.dart';

class MessageBubble extends StatelessWidget {
  const MessageBubble({
    required this.content,
    required this.isUserMessage,
    super.key,
  });

  final String content;
  final bool isUserMessage;

  @override
  Widget build(BuildContext context) {
    final themeData = Theme.of(context);
    return Container(
      margin: const EdgeInsets.all(8),
      decoration: BoxDecoration(
        color: isUserMessage
            ? themeData.colorScheme.primary.withOpacity(0.4)
            : themeData.colorScheme.secondary.withOpacity(0.4),
        borderRadius: const BorderRadius.all(Radius.circular(12)),
      ),
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Row(
              children: [
                Text(
                  isUserMessage ? 'You' : 'AI',
                  style: const TextStyle(fontWeight: FontWeight.bold),
                ),
              ],
            ),
            const SizedBox(height: 8),
            Text(content),
          ],
        ),
      ),
    );
  }
}

We now have all the necessary smaller widgets, now let's put them all together on the main page.

Here is what the code for the main chat page looks like:

// chat_page.dart
import 'package:chatgpt_client/api/chat_api.dart';
import 'package:chatgpt_client/models/chat_message.dart';
import 'package:chatgpt_client/widgets/message_bubble.dart';
import 'package:chatgpt_client/widgets/message_composer.dart';
import 'package:flutter/material.dart';

class ChatPage extends StatefulWidget {
  const ChatPage({
    required this.chatApi,
    super.key,
  });

  final ChatApi chatApi;

  @override
  State<ChatPage> createState() => _ChatPageState();
}

class _ChatPageState extends State<ChatPage> {
  final _messages = <ChatMessage>[
    ChatMessage('Hello, how can I help?', false),
  ];
  var _awaitingResponse = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Chat')),
      body: Column(
        children: [
          Expanded(
            child: ListView(
              children: [
                ..._messages.map(
                  (msg) => MessageBubble(
                    content: msg.content,
                    isUserMessage: msg.isUserMessage,
                  ),
                ),
              ],
            ),
          ),
          MessageComposer(
            onSubmitted: _onSubmitted,
            awaitingResponse: _awaitingResponse,
          ),
        ],
      ),
    );
  }
}

This is a stateful widget that starts with the message "How can I help?", just so we don't start with an empty chat.

The final piece is the _onSubmitted method, called through the message composer when a message is submitted.

Future<void> _onSubmitted(String message) async {
  setState(() {
    _messages.add(ChatMessage(message, true));
    _awaitingResponse = true;
  });
  final response = await widget.chatApi.completeChat(_messages);
  setState(() {
    _messages.add(ChatMessage(response, false));
    _awaitingResponse = false;
  });
}

When a message is submitted, we add the message to the chat messages and set _awaitingResponse to true, wrapped in a setState call. This will show the user message in the conversation, and disable the message composer.

Next, we pass all messages to the Chat API and await the response. Once we have the response, we add it as a chat message in _messages and set _awaitingResponse back to false, wrapped in a second setState call.

And that's it for the conversation flow! Let's see it in action:

This is the code for the App and the main method:

import 'package:chatgpt_client/api/chat_api.dart';
import 'package:chatgpt_client/chat_page.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(ChatApp(chatApi: ChatApi()));
}

class ChatApp extends StatelessWidget {
  const ChatApp({required this.chatApi, super.key});

  final ChatApi chatApi;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'ChatGPT Client',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(
          seedColor: Colors.teal,
          secondary: Colors.lime,
        ),
      ),
      home: ChatPage(chatApi: chatApi),
    );
  }
}

Parsing markdown

In our previous conversation with ChatGPT, we ask the follow-up question "show me the code".

We get a decent amount of Flutter code in the response, but it's all in markdown! Let's use the markdown_widget package to solve this.

flutter pub add markdown_widget

In the MessageBubble widget, replace the Text widget containing the message content with a MarkdownWidget:

MarkdownWidget(
  data: content,
  shrinkWrap: true,
)

One hot reload later, and we can see that the code is now properly parsed. That was easy!

Error handling

What if we get an error response from OpenAI? While testing, I did run into a few 429 (Too Many Requests) exceptions. Such an error could happen if you are calling the API too often, but also if the OpenAI API is getting too many requests in general.

The least we can do is handle the error and display a useful message. Here's a revised _onSubmitted method:

Future<void> _onSubmitted(String message) async {
  setState(() {
    _messages.add(ChatMessage(message, true));
    _awaitingResponse = true;
  });
  try {
    final response = await widget.chatApi.completeChat(_messages);
    setState(() {
      _messages.add(ChatMessage(response, false));
      _awaitingResponse = false;
    });
  } catch (err) {
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('An error occurred. Please try again.')),
    );
    setState(() {
      _awaitingResponse = false;
    });
  }
}

Of course, this could be improved even further. We can provide an option to retry the response without needing to send a new message, but also automatically retry the request in ChatApi without showing an error.

Wrapping up

We now have a fully working chat app to chat with ChatGPT at any time, on any platform!

In this post, we showed how to build a basic chat app to have conversations with ChatGPT through OpenAI's chat API. We also added some additional features such as markdown parsing and error handling.

The functionality is quite basic, but there's a lot more we can do with such an app. We could have useful features such as being able to copy and/or share the responses. Additionally, we can use a local or cloud database to store the conversations so we can access them at any time.

You can find the source code here.

Are you interested in building a ChatGPT client, or building a Flutter app utilizing ChatGPT? Or would you be interested in any follow-up articles where we improve this app by adding more features such as conversation storage and organization? Let me know in the comments!

If you found this helpful and would like to be notified of future posts and tutorials, please subscribe to the newsletter with your email below!

During the Supabase Launch Week 6 Hackathon, I decided to take on the challenge of building a multiplayer quiz game using Flutter and Supabase.

It had been a while since I wrote something about Supabase, and there's been a lot of changes and new functionality I had been looking forward to trying out, especially Realtime. So a Supabase hackathon was the perfect chance to get back into it!

Working on it a couple of hours at a time over about a week, I managed to build a simple quiz game that you can play with friends at the same time. In this post, I will share the journey of building the quiz game and how I used Supabase to achieve the multiplayer functionality.

If you want to play, you can try out the live demo here; there's also a practice mode in which you can play alone.

Building Supaquiz

The idea was simple; a quiz game that you can play with friends at the same time. With Supabase's Realtime functionality, it seemed achievable to build a functional app with Flutter during the hackathon.

It would take too long to share how I built Supaquiz step-by-step, but I will go over some specific parts that I found interesting and/or challenging. The project is open-source, so you can have a look at the source code here.

User interface

As easy as it is to build user interfaces in Flutter, this is usually my least favorite part as it can take a while to get a screen/widget to look exactly as I want it to. But in this case, the screens were quite simple, so all I had to decide was the main color (I went with what I call "Supabase Green") and a font. A quick search led me to the Press Start 2P font, which fit well.

const supabaseGreen = Color.fromRGBO(101, 217, 165, 1.0);

ThemeData get theme {
  final theme = ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: supabaseGreen,
      brightness: Brightness.dark,
    ),
    useMaterial3: true,
  );
  return theme.copyWith(
    textTheme: GoogleFonts.pressStart2pTextTheme(theme.textTheme),
    primaryTextTheme: GoogleFonts.pressStart2pTextTheme(theme.primaryTextTheme),
  );
}a

With the style decided on, the most complex widget I had to build was the button!

class AppButton extends StatelessWidget {
  final String label;
  final VoidCallback onPressed;

  const AppButton({
    Key? key,
    required this.label,
    required this.onPressed,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: Material(
        elevation: 8.0,
        child: OutlinedButton(
          onPressed: onPressed,
          style: OutlinedButton.styleFrom(
            shape: RoundedRectangleBorder(
              borderRadius: BorderRadius.all(Radius.circular(4.0)),
            ),
            side: BorderSide(
              color: supabaseGreen,
              width: 2,
            ),
          ),
          child: Padding(
            padding:
                const EdgeInsets.symmetric(horizontal: 8.0, vertical: 16.0),
            child: Text(
              label.toUpperCase(),
              style: Theme.of(context).primaryTextTheme.bodyLarge,
            ),
          ),
        ),
      ),
    );
  }
}

And with the buttons done, the rest was easy. Here is what the title screen looks like:

For multiplayer mode, you can either host a game or join a game. Each game needs a host, though if you wanted you could host a game and start it before anyone else joins... There is also a practice mode if you want to play alone.

The Trivia API

It's a quiz game, so we need questions! The Trivia API was perfect for this. It's a completely free, simple API, and fetching questions in the app using it was simple.

class TriviaRepository {
  static const _authority = 'the-trivia-api.com';

  Future<List<TriviaQuestion>> getQuestions(int numOfQuestions) async {
    final url = Uri.https(
        _authority, 'api/questions', {'limit': numOfQuestions.toString()});
    final response = await http.get(url);
    final questions = jsonDecode(utf8.decode(response.bodyBytes))
        as List<Map<String, dynamic>>;
    return questions.map(TriviaQuestion.fromJson).toList();
  }
}

As you can see above, it's only a simple GET call to the API, with a limit query parameter to return a specific amount of questions. It also supports more customization, such as specific categories for the questions as well as difficulty.

Supaquiz fetches a set of questions before every game and displays the question and possible answers on the screen.

I promise I got the answer wrong for the sake of the screenshot! If you get the answer wrong it's marked in red, while the correct answer is in a bright "Supabase Green".

Setting up Supabase

Setting up Supabase was a breeze using the Supabase CLI, a nice addition since the last time I used Supabase.

The CLI sets up your Supabase config with a simple command, supabase init, and starts up a local instance of Supabase for local development with supabase start.

I added some table creation SQL statements in the seed.sql file generated by the CLI, and was ready to go.

-- seed.sql
create type game_status as enum ('pending', 'started', 'complete');

create table games (
  id bigint generated by default as identity primary key,
  channel uuid default uuid_generate_v4() not null,
  status game_status default 'pending' not null,
  seconds_per_question int not null,
  host_id uuid references auth.users (id) default auth.uid() not null
);

Anonymous login

I was initially thinking of making Supaquiz work without needing users, as this was for a hackathon project and it had to be built fast. But still, I wanted to have users for future potential features such as statistics by tracking games played and number of correct answers.

Requiring sign-up with email for a demo project can be a barrier for some people, and I wanted to make it easy to start playing right away. Additionally, I wanted to test out the multiplayer functionality with friends during the development process. Unfortunately, anonymous sign-in is not currently supported by GoTrue, the authentication server used by Supabase.

There is a workaround, however, as you can disable email confirmations and assign users a custom email and password when first visiting the app. The AuthService, which has "anonymous sign-in", looks like this:

class AuthService {
  static const _emailKey = 'email';
  static const _defaultPassword = '82eb32f2a3ef';

  final GoTrueClient _auth;
  final SharedPreferences _preferences;

  AuthService(this._auth, this._preferences);

  Future<AuthResponse> signIn() async {
    if (_preferences.containsKey(_emailKey)) {
      return _auth.signInWithPassword(
        email: _preferences.getString(_emailKey)!,
        password: _defaultPassword,
      );
    } else {
      final email = _randomEmail;
      final response =
          await _auth.signUp(email: email, password: _defaultPassword);
      log('User signed up with random email $email');
      _preferences.setString(_emailKey, email);
      return response;
    }
  }

  static String get _randomEmail {
    return '${Uuid().v4().toString()}@dartling.dev';
  }
}

On sign-in, a user is signed up with a random @dartling.dev email and a default password. The generated email is stored in shared preferences to avoid creating a new user every time on the same device. The AuthService#signIn function is called after a user selects their nickname.

With users/authentication/authorization, I could also enable Row Level Security to restrict access to games and answers. As an example, here are the RLS policies for the games table:

create policy "Users can create games" on public.games
for insert to authenticated with check (true);

create policy "Users can view games" on public.games
for select to authenticated using (true);

create policy "Games can only be updated by their hosts" on public.games
for update using (auth.uid() = host_id)
with check (auth.uid() = host_id);

Game codes

For the games to be multiplayer, someone would have to host a game and share it with others. Games can be shared with codes. For the game codes, I wanted to have strings that are short, easy to share between people, and unique. After some searching, I came across Hashids, which fit my use case perfectly. With Hashids, you can map integers (which would be the game IDs in the database) to a unique hash of the length and characters of your choice.

Here are some snippets from the game code encoding and decoding logic.

// Hashids config
_hashIds = HashIds(
  minHashLength: 4,
  alphabet: 'abcdefghijkmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789',
);

// game ID to game code
String _toGameCode(int gameId) {
  return _hashIds.encode(gameId);
}

// game code to game ID
int? _toGameId(String gameCode) {
  final decoded =
      _hashIds.decode(gameCode.replaceAll('O', '0').replaceAll('l', '1'));
  return decoded.isNotEmpty ? decoded.first : null;
}

I chose a minimum 4-character long hash and excluded the capital letter O and lowercase l from the alphabet, as I found them to look too similar to the numbers 0 and 1 respectively with the game's font. When users input a game code, O is mapped to 0 and l is mapped to 1, to make things easier for everyone.

Multiplayer functionality

By this point, I had an app with a simple UI, questions fetched from the Trivia API, plus Supabase set up with authentication. I also had logic to generate shareable game codes so that others can join someone's game. The last piece is the most fun one, multiplayer.

My plan to achieve multiplayer mode was simple; you can choose to host a game, and other players can join it. At any time, the host can choose to start the game, and each player answers the questions on their device until the end of the game.

With Supabase Realtime, we can have devices listen to any changes to a specific game in the games table. When a host starts the game, the game's status is updated from pending to started. Players in the game will be notified of the game's status update, and start the game. To enable listening to real-time updates of the games table, I had to make this small change:

alter publication supabase_realtime add table public.games;

With that enabled, data can be exposed as streams through the Supabase client.

Stream<GameStatus> getGameStatus(int gameId) {
  return _supabaseClient
      .from('games')
      .stream(primaryKey: ['id'])
      .eq('id', gameId)
      .map((e) => GameStatus.fromString(e.first['status']));
}

Initially, I planned to have an additional round/question number field in the games table, and have users listen to updates to the round field of a game so the game can move on to the next question at the same time for all players. Instead, I went for a hackier approach with a time limit. The host can choose how many seconds players will have to answer the question, and after the time is up, the game moves on to the next question.

Once all questions are answered, the final scores are calculated and displayed to all players. To calculate the scores, I created a Postgres function:

create or replace function calculate_scores(game_id_param int) returns table (
  user_id uuid, nickname text, score int
) as $$ begin return query
select
  players.user_id :: uuid as user_id,
  min(players.nickname):: text as nickname,
  (count(answers.id) * 100):: int as score
from
  players
  join questions on questions.game_id = players.game_id
  left join answers on answers.question_id = questions.id
  and answers.user_id = players.user_id and questions.correct_answer = answers.answer
where players.game_id = game_id_param
group by players.user_id
order by score desc;
end;
$$ language plpgsql;

The calculate_scores function is called from the Supabase client:

Future<List<PlayerScore>> getScores(int gameId) async {
  await Future.delayed(const Duration(seconds: 2));
  final scores = await _supabaseClient.rpc('calculate_scores',
      params: {'game_id_param': gameId}).select<List<Map<String, dynamic>>>();
  log('Player scores for game $gameId: ${scores.join(', ')}');
  return scores.map(PlayerScore.fromJson).toList();
}

And with that, the game is over! You get 100 points for every correct answer.

Plans for the future

Given more time, there are many more features I would have liked to implement for Supaquiz. The hackathon is over, but if I find myself still playing the game, I might spend some time improving it at some point.

• Player statistics (games played, games won, questions answered correctly...)

• Quiz customization (categories, difficulty)

• Other game modes (TV mode)

Wrapping up

In this post, I shared a few parts of my experience building Supaquiz, a real-time multiplayer quiz game with Flutter and Supabase. I went into some detail on some of the challenges faced, including the implementation of anonymous sign-in, game code generation and real-time functionality.

By the end of Launch Week 6, I finally had a working quiz game that I could play with friends. You can check out the live demo here and the source code here. I'm also thrilled to share that Supaquiz won the Best Flutter Project category at the hackathon!

Overall, participating in the Supabase Launch Week 6 hackathon was a fun and rewarding experience. I'm looking forward to participating in more hackathons in the future.

For me, 2022 was a year of growth and learning as I delved deeper into the world of Flutter development. In addition to building apps with Flutter, writing about Flutter has been a great way to share my knowledge and experiences with the community.

In this blog post, I will share some personal highlights and accomplishments from the past year. I hope that, whether you're an experienced Flutter developer or just getting started, this post will inspire you to continue learning and growing with this incredible framework! So, let's dive in and take a look at my year with Flutter and the Dartling blog!

Accomplishments

The Dartling blog grows

In 2022, I published a total of 11 blog posts. That's almost one blog post a month, which is very close to the goal I set for me. While I would have liked it to be more, it's more than I expected, and it's also 550% more posts compared to 2021! I started the Dartling blog in May 2021, but only managed to publish 2 articles about using Flutter with Supabase.

Here are the top 3 Dartling blog posts of 2022:

• Displaying a loading overlay or progress HUD in Flutter

• Dynamic theme color with Material 3 (You) in Flutter

• How I built and published a Flutter app in 48 hours

And below are some stats for the year:

If you're curious about the huge spike in views and visitors in September, that's the main topic of the next section.

4 Articles in 4 Weeks

Thanks to the 4 Articles in 4 Weeks Hashnode Writeathon, I was motivated enough to keep blogging consistently for a month, publishing one post per week. Participating in this writeathon was one of the highlights of my year in blogging, as it resulted in having two of my four articles written featured on Hashnode.

• How I built and published a Flutter app in 48 hours

• Tips and tools for Flutter apps in production

As a result of the articles being featured, Dartling became more visible and resulted in a huge amount of new followers. I started the year with less than 10 followers on Hashnode, and the blog is now at over 200! I would highly recommend joining any contests, hackathons or writeathons on Hashnode if you can.

Growing my first Flutter app

Two and a half years ago, I published my first ever mobile app built with Flutter, Timelog. Since then, I added a lot more features and made many improvements to it. Timelog has had almost 20k downloads in 2022, and that's only from the Play Store! Though it's not as popular on the App Store (yet), with just a little less than a thousand downloads total.

Publishing my second Flutter app

Because of the lockdown rules introduced during the pandemic in early 2022, I had a lot of free time in the evenings while at home. I spent a lot of time building a second Flutter app, Flow, an expense tracking app. I share more details, from design to implementation to publishing, in this post.

Supabase Launch Week 6 Hackathon

During the Supabase Launch Week 6 Hackathon, I decided it was time to brush up on my Supabase skills and build something using Flutter and Supabase. By the end of the hackathon, I had built a real-time, multiplayer quiz game, Supaquiz, which you can play here. You can play on your own or host a game and play with friends. You can also check out the source code here.

Supaquiz won the best Flutter project category! I am planning to share some more on how I built it in a separate blog post soon.

Lessons learned

Stay consistent

One of the biggest lessons I learned during the past year is the importance of staying consistent. For both writing and app development, I found that the key to making meaningful progress was to set a regular schedule and stick to it.

Keep up-to-date

Another important lesson I learned is the value of keeping up-to-date with the latest developments in the Flutter ecosystem. Flutter keeps growing, and there is always something new to learn and explore. Through newsletters, Reddit and Twitter, it's easy to stay informed about the latest features, new packages, or interesting projects built with Flutter.

Goals for the future

I have several goals that I hope to achieve in 2023. One of my main goals is to continue writing about Flutter on a (more) regular basis and contribute to the Flutter community. I plan to write at least two blog posts per month, sharing my experiences and insights with other Flutter developers, and improving my skills and knowledge.

In addition to writing, I also hope to continue growing my existing Flutter apps, adding new features (and maybe even doing some marketing) to make them even better. And perhaps I might even release a third Flutter app!

Wrapping up

All in all, it's been a productive year, but as always there is room for improvement! Balancing writing, and building personal projects on top of a full-time job can be quite the challenge! However, I am excited to continue exploring Flutter and getting a stronger and deeper understanding of the framework.

If you have any particular topics or aspects of Flutter development you'd like to see more of in mind, please let me know in the comments! Do you have any plans or goals that have to do with writing or Flutter for the new year?

Keep building, writing, or both! Happy new year!

Cover image generated by OpenAI's DALL-E.

In this tutorial, we will show how we can enter, as well exit, a "full screen mode" in a Flutter application. This can be achieved by controlling the visibility of the native platform's overlays. In the case of mobile platforms such as Android and iOS, the overlays are the status bar at the top, and optionally the button or navigation bar at the bottom.

This solution does not require using any external packages, so this should be simple to do. Let's get started!

Control system overlay visibility

As already mentioned, if we want our Flutter app to take the full screen, we need to hide any overlays by the native platform (system).

We can do this by using the static setEnabledSystemUIMode method provided by SystemChrome.

import 'package:flutter/services.dart'; // For `SystemChrome`

void enterFullScreen() {
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.manual, overlays: []);
}

void exitFullScreen() {
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.manual, overlays: SystemUiOverlay.values);
}

That's it, actually! By setting the SystemUiMode.manual mode, we can specify which overlays should be visible. By passing an empty list, we can hide all overlays, and by providing all overlays, we can show them once again.

There are currently just two types of system UI overlays. One is the top overlay, typically the status bar, and the second is the bottom overlay, usually a button bar used for navigation. If we wanted, we could only hide just the top overlay, leaving the bottom button bar available for user interactions.

void enterFullScreenButKeepBottomOverlay() {
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.manual, overlays: [SystemUiOverlay.bottom]);
}

Types of full-screen modes

In the above example, we used the SystemUiMode.manual mode to achieve a full screen mode by hiding all overlays. But there are different values for SystemUiMode we could be using instead. All 4 modes will hide all overlays, but behave differently.

Manual with no overlays

This is the approach we used in the above example. All overlays are hidden, and the overlays can only be visible again by programmatically showing them (e.g. using the exitFullScreen() method above). Swiping the edges of the display can briefly show the overlays, but they are automatically hidden after a couple of seconds.

Lean back

In SystemUiMode.leanBack mode, while the overlays are initially hidden, they are visible after tapping anywhere on the display. One thing I noticed, for Android 12 at least, is that this only shows the navigation bar at the bottom (if there is one) and not the status bar, so this could depend on the operating system or device. You can still show the status bar by swiping the edges of the display.

Immersive

SystemUiMode.immersive mode is similar to leanBack mode, but the overlays are only shown when swiping the edges of the display.

Immersive sticky

SystemUiMode.immersiveSticky is the same as immersive, but with one difference. The swipe gesture which triggers showing the overlays can be received by the application, in case you want to react on it.

Edge to edge

In SystemUiMode.edgeToEdge mode, the overlays are still visible, but are actually rendered over the application. I tried this in an Android emulator, and the Flutter app's AppBar is shown below the status bar; it is not rendered on top of it. But the app's layout does seem to be affected when using this mode. This doesn't really achieve a full screen mode, but it's still good to know!

When enabling a system UI mode other than manual, we don't have to provide any overlays.

void enterFullScreen() {
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.leanBack);
}

Listen to overlay changes

We can use SystemChrome.setSystemUIChangeCallback to register a callback to be called when system overlay visibility is changed. This could be useful, as in some modes the user can tap or swipe on the display, which could result to the overlays becoming visible again.

The callback has a systemOverlaysAreVisible boolean, and if its value is true, it means we are not in full screen mode. I noticed the value is not always what's expected though, so if you're planning on using it, make sure to test it out and see how it behaves.

To see it in action, we could register the callback in initState in a stateful widget.

@override
void initState() {
  super.initState();
  SystemChrome.setSystemUIChangeCallback((systemOverlaysAreVisible) async {
    log('System overlays are visible: $systemOverlaysAreVisible');
  });
}

Usage examples

Now that we know how to toggle full screen mode in a Flutter app, let's apply it in practice. We will use the default counter app/template to get started.

flutter create .

How our app utilizes full screen mode can depend on the use case. We might want to have "focus mode" which opens up in its own page, or we might want to toggle full screen mode on an existing page.

Enter a new page in full-screen mode

In the counter app, let's introduce a new focus mode page, which can be opened by a button on the main screen. The logic is identical to the main counter screen, but without the app bar.

// main.dart (_MyHomePageState)
TextButton(
    onPressed: () {
    Navigator.push(context,
        MaterialPageRoute(builder: (_) => const FocusModePage()));
    },
    child: const Text('Enter focus mode'),
),

// focus_mode.dart
class FocusModePage extends StatefulWidget {
  const FocusModePage({super.key});

  @override
  State<FocusModePage> createState() => _FocusModePageState();
}

class _FocusModePageState extends State<FocusModePage> {
  int _counter = 0;

  @override
  void initState() {
    super.initState();
    log('Entering full screen mode...');
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersive);
  }

  @override
  void dispose() {
    super.dispose();
    log('Exiting full screen mode...');
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.manual,
        overlays: SystemUiOverlay.values);
  }

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

In this stateful widget, we enter full screen mode in initState, and exit it in dispose. This way, full screen mode is only enabled while the user is on this specific page.

Toggle full-screen mode in a page

If we want to enable full screen mode in an existing page, we could toggle it with buttons. On the main counter page, let's add two new buttons, conditional on whether full screen is enabled.

We add a variable named _isFullScreen to keep track of whether we enabled full screen mode or not.

// main.dart (_MyHomePageState)
bool _isFullScreen = false;

Depending on the value of _isFullScreen, we either show the button to enter full screen mode, or exit it.

// main.dart (_MyHomePageState)
if (!_isFullScreen)
  TextButton(
    onPressed: () {
      log('Entering full screen mode...');
      SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersive);
      setState(() {
        _isFullScreen = true;
      });
    },
    child: const Text('Enter full screen'),
  ),
if (_isFullScreen)
  TextButton(
    onPressed: () {
      log('Exiting full screen mode...');
      SystemChrome.setEnabledSystemUIMode(SystemUiMode.manual,
          overlays: SystemUiOverlay.values);
      setState(() {
        _isFullScreen = false;
      });
    },
    child: const Text('Exit full screen'),
  ),

This might become a bit more complicated if the gestures by a user cause the overlays to become visible as from the widget/state's point of view full screen is still enabled. For that, we could make use of SystemChrome.setSystemUIChangeCallback to track any changes.

Wrapping up

In this tutorial, we showed how to enter and exit full screen mode in a Flutter app without using any external packages. We also showed how we would use this functionality by either having certain full screen pages or enabling this mode manually on a page.

You can find the full source code here.

If you found this helpful and would like to be notified of future tutorials, please subscribe to the newsletter with your email below!

Publishing your first app feels great. Flutter makes it very easy to build apps on any platform, so it's easy to turn your idea into a production-ready app and get it published on the Play Store, App Store, or anywhere.

But what should you do next, if you want to keep working on the app? My first instinct, personally, would be to just build more features! This can be a good idea, of course, especially if you've built a relatively simple app and want to keep improving it and introducing new, more advanced features, which can also help your app stand out from the rest. However, once your app is live, there are a few other things you should focus on first, or at least in parallel, while you're working on new features.

People build apps for many reasons, but most commonly it's to solve a problem and make people's lives easier. In this article, I will share some tips and things you can do once you've published an app in production to grow your app and make it even better. I will focus more on apps built with Flutter, and share tools, packages and services you can use, some which are specific to Flutter, and some not.

Improve your process

Continuous delivery

If you're publishing your app on multiple stores and platforms, or even just one, the process can be quite time consuming. Even if it takes a few minutes at a time, the process can be very manual and repetitive.

There are many tools you can use to automate releases and deployments of your app, and this official Flutter guide lists some of the options available to you.

There are all-in-one tools such as Codemagic which provide both CI (Continuous Integration) and CD (Continuous Delivery), so you could run tests and some verifications before your releases. If you have existing CI workflows, such as with GitHub Actions or GitLab, you can integrate fastlane with them to do this.

CI/CD can save you a lot of time, especially if you start releasing more often. While you don't really have to set this up before publishing the first version of your app, it's a good idea to set it up as early as possible. The setup will only take a little bit of time, but will end up saving you a lot more time in the future.

Screenshot creation

On stores such as the Play Store and App Store, app listings are required to have screenshots of your app. Taking these can be very tedious, as you might have to do it for multiple platforms, and even for multiple screen sizes!

Screenshots are important to get right, as it's one of the first things people will see, and you want them to want to download your app after checking out the screenshots. You can use tools such as AppScreens which can help with the layouts and adding phone frames or text in the screenshots. It works for both the Play Store and App Store, in addition to multiple screen size support and localization, so all you have to do is set it up once and then upload the "raw" screenshots.

Even with screenshot creator tools, you still need to manually capture these screenshots of your app. This is usually not too bad, as your app's main look might not change that often. But this can still be very time consuming and repetitive, as you need to repeat the same process for all supported platforms as well as screen sizes. You might also want to have some dummy data in the app so that the screenshots are not of an "empty" app. The screenshot taking process can also be automated. The tool screengrab is included with fastlane and can help capture screenshots in multiple languages on emulators or real devices, but does not currently support Flutter. There is an article on how to achieve this in Flutter with the screenshots package, but it seems to be outdated by now. However, it's worth spending at least some time to at least make this process easier and shorter, if not completely automated, as it could literally save you hours; I did this manually for apps I have on both the Play Store and App Store and the whole process usually took over an hour.

Crash reporting

If the app crashes for your users, it would be good to know about it before they leave a bad review or feedback! You can use a service such as Sentry which is easy to integrate with their Flutter SDK to track any errors, monitor them, and act on them.

Analytics

Besides crashes, it's also a good idea to know how users are using your app. You can use services such as Amplitude, which integrate with Flutter, to track which features are being used and how. This can help you figure out what to work on next, or what to improve. And if some features are not being used as much as you expected, maybe you could consider removing them, or changing them.

Grow your app

Ask for reviews

Once you're happy with your app and are confident it is bug-free, it's a good idea to ask for reviews inside the app. You can use packages such as in_app_review that will show the native Store review pop-ups to your users, and you can decide to only show this once a user has been using the app for some time or has used some specific features an arbitrary number of times.

This is a great, easy way to get more reviews, and more (ideally positive) reviews can also mean more downloads.

Ask for feedback

While users usually leave feedback in reviews, it's also good to have an option for people to message you with any feedback or questions they have. Usually this through email. With the url_launcher plugin you can have users open their email app straight to your feedback email. This could be a personal email or a feedback-specific email for your app's domain (e.g. support@myflutterapp.com). For custom domains, if you don't want to pay for email services, you can use an email forwarding service such as ImprovMX to forward any feedback to your support email to your personal one.

Gathering feedback from users is a great way to get to know how users use your app, in addition to analytics. You can also get suggestions on things to improve on or features to add. And as a tip, if you receive any emails with very positive feedback, make sure to ask them to leave a review or rating in the Store if they haven't already!

Monetization

Perhaps not great for your users, but great for you! Monetizing your app gives you a good incentive to keep working on it and improving it. Ads can usually be bad for the user experience, so in-app purchases to unlock more advanced, "premium" features would be a good approach. For apps that require a server/backend to store data, subscriptions would be a good fit as they can also cover server costs. If your app is offline-only, maybe a one-time-purchase makes more sense. Services such as RevenueCat have Flutter SDKs and make it easy to implement in-app purchases, but you can also use Google's official in_app_purchase plugin, though for the latter you will need a backend to validate receipts.

Locking functionality behind a paywall can also help you validate how useful your app is. If people pay to use your app's more advanced features, it means they found your app helpful and have probably been using it for a while.

Localization

Even with your app just being in the English language, you can still get users from all over the world. However, by localizing your app you can expand your target audience for little cost, as a lot of mobile phone users prefer to use apps in their native language. You just need the translations, and localization in Flutter is very easy to set up.

At the very least, you can localize your app store listings (description, features), to make your app easier to find in app stores of different countries.

Accessibility

Besides localization, another way to reach more users is to improve your app's accessibility. Flutter has an accessibility page describing how you can test your app's accessibility and what you can do to address any potential issues, and there are also accessibility widgets you can use to improve accessibility.

App store optimization

App store optimization, typically referred to as ASO, is important if your app is on stores such as the Play Store and App Store. The more you optimize, the more people can find your app while browsing the stores, and the more downloads and users you get. I will not go into detail about this here as there are already countless resources for ASO out there. Two points already mentioned above, localization and asking for reviews, are good ways to improve your app store ranking.

Keep your users

On-boarding

Simply getting people to download your app is never enough. Most people are usually testing out different apps, so it's very likely they only briefly install your app, decide it's not what they're looking for and then uninstall it. This is why a user's first interaction with your app is important.

Introducing an on-boarding flow is an easy way to highlight your app's features when an app is first opened. With Flutter, you can quickly build an on-boarding flow with multiple pages to do this. One example would be to use the smooth_page_indicator package as well as some images (unDraw is a good free resource) with descriptions (ideally, localized!) of your app's main or stand-out features.

Tutorial

Regardless of how complex your app is, it could be helpful to show users how to use the app. A tutorial, also called a tour or product tour, is usually done by highlighting the buttons or areas users should be tapping or looking at. There are a lot of tutorial packages for Flutter on pub.dev that make it easy to highlight widgets and display descriptions.

The tutorial is a good follow-up to the initial on-boarding, and it's a good way to get users to interact more with your app and use its main functionality right from the beginning.

Hook

After a good on-boarding flow and tutorial, people are more likely to continue using your app! But how do you get them to keep using your app? This can vary depending on the type of app, but a user might install your app, find it useful, but then forget to use it regularly.

You can "nudge" your users by sending a daily local notification or push notification at a good time to get them to use your app. You can also incentivize continuous activity by introducing gamification or showing charts and streaks of the user's recent activity.

Spread the word

Landing page

You might already have a domain for the app, and some "legal" pages (privacy policy, terms and conditions). But do you have a landing page for the app? It doesn't have to be anything fancy, but it's useful to have a simple page with buttons to the app stores where you list the main features of the app. If you already have good reviews on the stores, you could also list some of them in this page; user testimonials are a good way to convince people to at least try out your app.

People can stumble across your landing page either by searching for your app or by accident, or by someone sharing the landing page. This is good if your app is on multiple platforms, as you have a main page where users can see all available platforms, head to the correct store or website and download your app.

For this tip, using Flutter is actually not recommended! SEO matters for the landing page, so a Flutter web app would not help at all with this.

Share your app

If you've built something you think others will find useful, you should share it! Having a landing page, as mentioned above, helps with this as you can promote your app by simply sharing this landing page. So, tell your friends, Twitter, Reddit... everyone!

You can also build share functionality in your app with the share_plus package, so that users who like your app can share it with friends.

Get featured

You can share your app with press, such as journalists which write about apps on different websites and blogs. Getting featured on such a site could be a great way to get downloads. You can simply reach out to sites or specific people by sharing your landing page and some info, but in this case, having a "press kit" including a description and details of your app's features, screenshots and/or videos, will make it more likely to actually convince people to write about your app. Using a service such as ImpressKit can help with setting up a press kit.

It's also possible to get featured on app stores such the Google Play Store or Apple App Store. For Apple's App Store, you can actually ask to get featured, and the team there will review your request. And if your request is rejected, keep asking! You can ask to be featured for every new/significant update of your app.

Launch

Another way to spread the word about your app and get more users is by "launching" your app on different places. ProductHunt is a popular site for launching products, and though again it can depend on your app if launching there will get you any visibility and downloads, showcasing your app on multiple sites is still useful. Every download counts!

Wrapping up

In this article, we listed some tips on things you can do after you publish your Flutter app, from improving the development and deployment process, to getting more downloads, and to getting users to keep using your app.

Some of these are actually never-ending processes (if you want them to be!), as there are always things to improve on and optimize, in addition to new features. But these are highly recommended if you want to keep working on your app.

Images generated by OpenAI's DALL-E.

This article was published as the #week4 article for #4articles4weeks.

A couple of years ago, I built and published my first app built with Flutter, Timelog. It's a time tracking app which lets you track your time across different activities, and set daily/weekly/monthly goals per activity. I built this app mainly for myself, but I was quite happy to find out that a lot of other people have found it useful too.

Fast forward to the start of this year, and I was looking forward to building another app with Flutter. I decided to build Flow, a simple expense tracking app that would fit my needs, as I found the tons of expense tracking apps already out would either have clunky UIs or way too many features that I didn't need, yet still not flexible enough.

Firstly, I'd like to point out that no, this is not a guide to build and publish an app in production in a weekend. The title may be a little misleading (sorry!), but by 48 hours I mean 48 total hours of development of the app as well as the landing page, in addition to the Play Store listing (I haven't got to publishing this to the App Store yet). This process actually took me about 3 months in total, and I was mostly building this during the weekends and evenings in 1-3 hour chunks.

I actually used my first Flutter app, Timelog, to track how much time I spent building Flow, and that's how I noticed that by the time I had published Flow to the Play Store, I was at roughly 48 hours tracked in total. I also ended up looking at Timelog's source code to see how I did some things, and even copied some approaches and technologies used.

In this post, I will go over the process I took to build Flow, an expense tracking app with Flutter, in 48 hours of total development. We will start from the (a bit too short) planning phase, followed by the implementation, and then the final steps leading to publishing the app on the Play Store.

Planning

This phase was relatively short, and mostly consisted of thinking about what features I would want such an app to have, at least for a minimum viable product.

Features

Expense tracking

This was an expense tracking app, so of course it would need to support recording your expenses: an amount, a date, and a category. Users should be able to see a history of their expenses, as well as manage their categories.

Statistics

Of course, the reason you would track your expenses is to monitor your spending and see how much you spend and on what. One of the main features would be to display useful charts that would show you total amount spent per category, with options to filter categories and set specific time ranges.

For this, I used syncfusion_flutter_charts. It's very customizable and has every chart I could think of, or at least needed. I had also used the same library previously for Timelog, so this was an easy choice.

Labels

For Timelog, my first app, the stand-out feature which most of the existing time trackers did not have were goals you can set per activity. For example, I have a reading goal of 2 hours per week, and a blogging goal of 4 hours per month (though thanks to #4articles4weeks, I'm already well past over 4 this month!).

For Flow, the stand-out feature is the ability to assign labels on each expense. For example, you could have labels specific to locations, trips, or people. This way, you could track exactly how much you spend e.g. on a trip, without having to assign the generic "Travel" category to every expense.

Currencies

Users in different countries will need to track expenses for different currencies. The user should be able to pick their own currency, and this package made this very easy to implement. Supporting multiple currencies at the same time would make things more complicated, so this was left out and added to the backlog as a feature for the future.

Design

I'm not a designer, but thankfully, it's easy to build beautiful looking UIs with Flutter. I decided to simply use the Material widgets to make my life easier, as the Material look is decent enough for all platforms.

The main layout is just a Scaffold with a NavigationBar at the bottom and a FloatingActionButton to record expenses. There's also a lot of ListTile widgets used for the expense history, settings, and the category/label management pages, as well as icons and charts. The most complex widget that I built from scratch was the number picker, which you can input the expense amount with. It's really just a bunch of rows and columns, but the decimal button logic was a bit tricky.

Implementation

Data storage

For an expense tracking app, we need to store the user's expenses and categories. At least for the first version, we're just going to store the data locally on the user's device. For this, I went with Drift, which is built on top of sqflite. For less critical data such as the theme and user preferences, shared_preferences is used instead.

State management

I spent ages trying to figure out which state management approach to use for my first app, so thankfully this time it was easy. For state management, I used "vanilla" Flutter; a combination of FutureBuilders, StreamBuilders, ValueNotifier/ValueListenableBuilders, and even StatefulWidgets.

Drift, the persistence library supports exposing data not just as futures but also as streams, which emit new events every time the data changes. Most views showing data such as expenses, categories or labels simply use a StreamBuilder to display the data, and these are refreshed automatically every time something is added or changed.

Other views that require "complex" state such as the expense creation page, are made of small StatefulWidgets that communicate changes to the data through callback methods, and state changes that influence other widgets can do so through ValueNotifiers.

In total, so far, the app uses 12 StreamBuilders, 8 FutureBuilders, and 9 ValueListenableBuilders. No external libraries!

Architecture

Flow is a simple app so far. A lot of the business/data logic that deals with creating expenses, storing user settings and configuring notifications is isolated in specific Service and Repository classes. These classes are passed around to widgets through the use of a Services inherited widget, which holds the references to instances of any dependencies needed.

class Services extends InheritedWidget {
  final ExpenseRepository expenseRepository;
  final SettingsService settingsService;
  final NotificationService notificationService;
  final AnalyticsService analyticsService;
  final SubscriptionService subscriptionService;

  Services({
    Key? key,
    ...
    required Widget child,
  })  : ...
        super(key: key, child: child);

  static Services of(BuildContext context) {
    final Services? result =
        context.dependOnInheritedWidgetOfExactType<Services>();
    assert(result != null, 'No Services found in context');
    return result!;
  }

  @override
  bool updateShouldNotify(Services oldWidget) {
    return false;
  }
}

To avoid coupling widgets with business logic, some complex bigger widgets/views have their own ViewModel class, usually per page/screen. This view model has all the dependencies needed (services or repositories), and the view simply calls methods on this view model.

class NewExpenseViewModel {
  final ExpenseRepository _expenseRepository;
  final CategoryRepository _categoryRepository;
  final AnalyticsService _analyticsService;

  int amount;
  DateTime date;
  TimeOfDay? time;
  Category category;

  NewExpenseViewModel(
    this._expenseRepository,
    this._categoryRepository,
    this._analyticsService, {
    required this.amount,
    required this.category,
    this.time,
  }) : date = DateTime.now().startOfDay;

  Future<void> save() async {
    _analyticsService.track('new_expense');
    await _expenseRepository.create(
        amount, date, time, description, category.id, labels);
  }

  Future<List<Category>> get categories => _categoryRepository.all;
}

These views and view models are created by first getting the Services from the context in order to create it with any of its dependencies, like below:

Future<Expense?> openNewExpensePage(
    BuildContext context, int amount, Category category) {
  final services = Services.of(context);
  final viewModel = NewExpenseViewModel(
    services.expenseRepository,
    services.categoryRepository,
    services.analyticsService,
    amount: amount,
    category: category,
  );
  return Navigator.push<Expense>(
    context,
    MaterialPageRoute(
        builder: (_) => NewExpenseView(viewModel)),
  );
}

This is a basic architecture that's been working for me. It's quite simple and has no dependencies on external libraries, and view models can easily be tested in isolation. It does feel like a little bit of boilerplate at times, though, especially when trying to build something quickly, and especially in a team of one. I do occasionally "cheat" by accessing the services and their methods directly in widgets, though!

Local notifications

Flow has a simple daily notification to remind you to register your expenses. This is set when you first open the app and can be toggled on/off and its time can be changed. For this, I used the local_notifications package.

Theming

No app is complete without dark mode! In Flutter, it's so simple to implement that it was one of the first things I worked on. I also used flex_color_scheme with the Material 3 settings enabled to make my life a bit easier, and even have true black mode out-of-the-box in addition to dark mode.

Since Flow is meant to be a simple expense tracking app, I also made use of Material 3's dynamic color feature to change the app's theme/color based on the user's main theme/color on their device.

Monitoring

While monitoring of any kind is optional, it's something I'd recommend to always have, just to have an idea of how your app is used, or how it doesn't work!

Analytics

I find it useful to track metrics to measure how and how much the app is used and what features are used the most. Things like expenses created, new labels created, and which statistics/charts are viewed the most. This can help decide which features to focus on while working more on the app.

For Flow, I decided to go with Mixpanel, as it had an official Flutter package. However, I later realized that you can only have up to 5 reports on your dashboards on the free plan, which is far too little to get any useful insights. Because of this, my suggestion would be to go with something like Amplitude instead, which has a much more generous free tier.

Crash reporting

I went with Sentry for error/crash reporting, which also has good support for Flutter. It's nice to be able to see any errors thrown while other users are using your app, as your tests might not catch everything. And in my case, I was only mostly testing things manually (sorry, TDD folks!).

On-boarding

Another "nice-to-have" is an on-boarding flow. This is what is shown when a user first starts up the app. I used the smooth_page_indicator package as well as some images from unDraw to show a few pages explaining Flow's core functionality. On the last page, the user can also opt in or out of the analytics and crash reporting mentioned above.

A good follow-up for the introductory pages would be a tutorial, or tour, of the main functionality. For Flow, for example, the FAB that lets you add expenses could be highlighted with a tool-tip explaining that this is where you need to tap to start tracking expenses. Flow is currently not that complicated to require such a tutorial, though.

In-app purchases

I wanted to monetize the app from the beginning. Again an optional step, but it's nice to be able to validate if your app is actually good and unique enough for people to want to pay to use it more. I'm not a fan of ads at all, so I decided to implement a one-time "Flow Plus" purchase, which gives you access to more colors and icons for categories and labels, as well as unlimited labels.

For the implementation of in-app purchases, I used RevenueCat. When I was building Timelog, Flutter's official in_app_purchase plugin was not complete. This is how I found out about RevenueCat and its purchases_flutter package. RevenueCat has lots of extra features and functionality you might otherwise have to implement yourself, in addition to a generous free tier!

Necessary things

In order to publish the app on the stores, there are some small things I had to include, namely, terms of use and privacy policy pages. I had already bought a domain for the app, flowmoneytracker.com, so I created two pages with the necessary information there, making sure to include third party services used for monitoring. I also spent some time on a very basic landing page.

Since I implemented in-app purchases, I also needed to make sure a "Restore purchases" option is available. This is a requirement for iOS apps, and I made sure to add this in the settings page as soon as possible, as it's one of the reasons Timelog's initial App Store submission was rejected!

A few more things

I wasn't really in a rush to release Flow, which is why I spent some time to also implement some features that are not really necessary to have in a minimum viable product. Some of these I also wanted for myself and did not take too much time, so I went for them:

• The option to change the start day of the week (for the weekly statistics)
• A set of preset categories as well as pages to manage categories and labels
• Backup and restore functionality (useful for me in case I broke things while testing on my device! I had already been tracking my expenses while developing the app, and didn't want to lose my data)
• Sharing functionality that simply shares the landing page's URL, and a feedback option that opens up an email to Flow's support email. I used ImprovMX to forward support emails to a personal email account.

Production

Publishing

And so, after a little less than 48 hours divided across 1-3 hour sessions, Flow was ready for production. I spent some time making screenshots for the Play Store listing, and quickly wrote short and long descriptions. A couple of days later, Flow was approved, and live on the Play Store.

Once I gather some more feedback from the Android version and make some more improvements, I also want to publish Flow to the App Store. Maybe even on desktop platforms, but I would need to make some layout changes first so that it looks good on larger screens.

Future plans

There are too many features an expense tracker like Flow could eventually support: recurring expenses, income tracking, budgeting, multiple accounts, multiple currencies... The current plan is to keep things simple and see if the labels feature actually makes Flow stand out from the hundreds of expense tracking apps out there. I do need to first market it a little, as currently it's just quietly sitting in the Play Store and not very easy to find!

Wrapping up

I hope you found this post helpful! It covered a little bit of everything involving building Flutter apps, from designing and planning to implementing, with a little technical details on the architecture as well as packages and approaches used.

I've been using Flow for myself for a few months and find it quite useful, so this is already a win for me! It's been a great experience building and publishing my second Flutter app. Since publishing my first Flutter app two years ago, Flutter's developer experience has improved, making it easier to develop with Flutter, and I even got to re-use some past learning from the first app. Perhaps my third app could be published even quicker!

Cover image generated by OpenAI's DALL-E.

This article was published as the #week3 article for #4articles4weeks.

As a Flutter developer, at some point in your learning path, you'll feel like you know enough about Flutter and are confident enough to build production-ready applications with Flutter.

Perhaps you've struggled a bit to pick the state management or routing approaches of your choice, but now you've even built some small or even big apps with Flutter. But is there more to learn about Flutter? Of course, there's always more to learn!

While you don't have to "force" yourself to level up your Flutter skills, since it's something that can happen the more you work with Flutter anyway, there are many ways to improve further as a Flutter developer. In this post, we will share some tips and resources on things you can do and learn to take your skills to the next level.

Flutter deep dives

It's easy to build with Flutter, thanks to its great user experience and learning resources out there. But have you been inside Flutter, and do you know about its architecture? You don't need to know about these, but it's nice to know a little more about the framework and how it works behind the scenes.

There are tons of resources out there going over the more complex aspects and features of Flutter, and learning about these can definitely help. They might seem elusive at first, but animations and slivers are useful to know about, even if there are widgets and packages available that can simplify these by a lot for you.

Everyone likes to learn differently. Personally, I learn (and enjoy it) best when going over written tutorials such as blog posts, and building (example) apps on my own, but others might prefer videos and/or courses. Thankfully, Flutter's learning page has plenty of resources of all kinds, and even separates them in Beginner, Intermediate and Advanced levels. And there are likely countless "unofficial" resources on any topic and in the format of your choice, just a simple search away!

Experiment

Depending on apps you've worked on, there might be things Flutter can do you've never heard of. For example, did you know you can build games with Flutter? Packages like Flame make it very easy to get started as a Flutter game developer.

pub.dev has tons of packages that can do interesting things which you can experiment with. You could build an app that uses NFC, the camera, bluetooth... There are many more advanced use cases for Flutter apps that you might never come across while working for a company or making your own apps.

Expanding your horizons (and skills!) as a Flutter developer is a great way to improve as a developer and learn more about what you can do with Flutter. Experimenting with things you haven't already worked with is one way to achieve this. You might even consider trying alternative approaches to what you've been used to so far, such as a different package for state management (or no package at all), routing and persistence/data storage. Or perhaps if you've only been building mobile apps, you could try out Flutter on desktop and web. It's a (slightly) different world there, as you need to adapt for bigger screens, potentially support multiple windows, and use different plugins (if they even exist!).

Go native

It's (almost) inevitable that at some point while building apps with Flutter, you'll want to make use of some native platform features that are not available as plugins. For that, you have to know about platform channels, but you'll also have to write native code for each platform you're supporting.

For the Flutter/Dart part, I've written some tutorials on building plugins platform channels as well as doing the same but using the Pigeon package which simplifies a few things compared to just using channels. The Flutter website also has useful resources on developing plugins.

It's good to at least know the basics of each native language of the platform you're targeting. If you're a mobile app dev, some Java/Kotlin knowledge is useful for Android, and Objective-C/Swift for iOS. For plugins or accessing some native features, it should be enough to just know the language, without needing to know how to build native UIs. However, things like home page widgets or watch (WearOS, Apple watch) apps are things you can't achieve with Flutter (yet?), so building a small native app for each platform might be good experience.

Get involved

There are many ways to get involved with the Flutter community, from online and offline events/meet-ups, to the Discord server and the Flutter subreddits. By being involved you can meet more people working with Flutter, as well as learn new things. You may even be able to help others who are earlier on their Flutter journey (for this, there is also StackOverflow).

You could even contribute to open source Flutter packages or plugins, or even publish your own if you've built something that's not already available and want to share it with everyone else. You could even contribute to the Flutter SDK itself! There are currently over 5000 issues listed on the Flutter GitHub repo, and you could start by looking at ones marked with the good first contribution label.

Write or produce

By writing in any form, either a personal blog or other sites, you can not only contribute to the community as well as teach and help others, but it can also be a great way to learn about things yourself. Of course, you might prefer to produce videos rather than write, and the same applies for that!

I've personally found writing tutorials very useful when I was interested to use a new technology with Flutter, such as Supabase, or wanted to tackle some of the "harder" things in Flutter such as writing plugins.

Stay up-to-date

Besides Flutter news such as new versions and upgrades, which are usually easy to hear about, especially if you're on Twitter or Reddit, there are tons of resources, packages or apps using Flutter out there and being released every day. It's hard to keep up with everything, and can be very time-consuming.

Newsletters are a good way to keep up with the latest on Flutter. You can receive curated lists of articles, videos, news and packages weekly (or bi-weekly) in your inbox. There are other Flutter developers in the community that are happy to do the curation for you! Some popular newsletters include Flutter Tap and The Flutter Bi-Weekly. I'm also a fan of This week in Flutter by Michele.

Keep building

Most importantly, though, you should just keep building! Having your own Flutter apps in production is already a big achievement, and simply by maintaining these apps and dealing with user feedback and requests, you would also be "maintaining" your Flutter skills, as wel as improving them, and staying up-to-date with any new changes.

Wrapping up

In this article, we shared some tips on improving your Flutter development skills and taking them to the next level. There are many ways to do this, and some might be obvious, but I hope you found some of these helpful! If there are more tips and/or resources you would like to share, please do so in the comments.

Images generated by OpenAI's DALL-E.

This article was published as the #week2 article for #4articles4weeks.

It's 2022, and the tech job market is very hot right now. Not so much for Flutter jobs, unfortunately. Since Flutter is still relatively young, not too many companies currently use it, or even plan to do so in the future.

For mobile applications, some companies still prefer to go native, and the ones that do choose to go cross-platform seem to be more leaning towards React Native because it's been around longer and comes with the whole NPM ecosystem which is more mature than pub.dev.

For desktop applications, this is where Flutter would potentially be a great candidate as you can develop for Windows, Linux and macOS with one codebase. However, Flutter's support for these platforms is even younger than mobile, and depending on the complexity of the desktop applications there could still be a need for native code due to the lack of plugins. Similarly with mobile and React Native, companies might choose to use Electron, if not stick with native apps.

With all that in mind, you might still want to work with Flutter full-time anyway. Flutter's developer experience is pretty great after all, and so is the community. So, let's not lose hope! Even though there's currently way less demand for Flutter compared to other jobs in tech, it's still possible to land your first job with Flutter. After all, Flutter is a popular choice with new companies or startups, and more and more established companies are looking to adopt it.

In this post, we will go over some possible ways to find and apply for a Flutter job. We will cover some places to look for a job, as well as alternative places you could look at or things to do in order to find potential opportunities. In some cases, opportunities could find you!

Go through job boards

The most common way to find yourself a job to apply for is simply to start looking online. Any online search for "flutter developer job" could get you quite a few results. However, since there's not as many Flutter jobs out there, you could only come across either outdated job openings, or job descriptions that simply mention Flutter as a nice-to-have, with the job being mainly for a native developer position.

LinkedIn's job board is a good place to look at to avoid coming across outdated listings. A lot of professionals are already on LinkedIn, and so are companies looking for developers. So if any companies out there are looking for Flutter developers, it's likely they've put this up on LinkedIn as well. Additionally, if you haven't listed Flutter as one of your skills on your LinkedIn profile, you should do so! Recruiters looking for Flutter developers could come across you when searching for candidates.

There are also a few Flutter-specific job boards out there, but a few are not really active or kept up-to-date. Flutter Jobs seems promising and they also have a Twitter account and a mailing list which you could follow to be notified of any new job posts.

Start with an internship

This was how I got my first job, but way before Flutter was stable! An internship is a great way to get started, especially if you've recently graduated from university or finished a programming course or bootcamp, and looking to start your career in software development.

As mentioned before, however, it might be even harder to find companies that are offering internships for Flutter developers. But if you do find one, there's a good chance the companies will be happy to help you get started with your Flutter career, and you could potentially move on to a full-time position with the company after your internship.

Go freelance or consulting

Because a lot of new companies and startups could pick Flutter for their apps, it's possible to get a job as a freelancer or consult for companies that are just starting out and looking to use Flutter.

At places such as Upwork, you can sign up and either look for freelance jobs or get hired for an hourly rate. There are also websites such as Flexiple or Toptal where you can apply as a freelance developer and get assigned clients and projects.

If you have a good network and portfolio, you could even do that without needing a middleman, but you'd need to find your own clients and work which is more challenging. But if your network is good enough, instead it could be that clients find you!

Join the Flutter community

There are many benefits to being involved with the Flutter community. The Discord server in particular has a #hiring channel where companies or people looking for Flutter developers share information on their openings. There is also a #for-hire channel in which you can share your resume and portfolio, and anyone interested can reach out to you directly.

Write about Flutter

While this might not necessarily evolve into a full-time job, writing about Flutter is a great way to improve your Flutter skills as well as get your name out there as a competent Flutter developer.

Start a blog

The best way to learn something is by teaching it. By starting a blog, you could share some of the knowledge you pick up while working on your Flutter apps. Did you use some fancy new package in your app to do something cool? Write a blog post about it! Others could find this useful.

But you're looking for a job, and a salary, so a blog is unlikely to become something that will get you a proper developer salary (at least not very early!). However, simply having a blog out there is great for your resume, and I've personally had a couple of companies reach out to me on Dartling's email to offer me a job (or at least, to interview for one).

Become a technical writer or editor

You could also have a career as a technical writer, or simply do this on the side. Companies such as raywenderlich.com and Pieces can pay you per article, and you can start with just a couple of articles per month. Digital Ocean will even donate to tech-focused charities in addition to compensating you!

A personal blog, or guest posts in other blogs could definitely help you land a technical writer job, so if you're interested, just get started! It's easy to get started on a tech blog with Hashnode, and it would be nice to see more Flutter-focused blogs on here also.

Publish your apps

If you're looking for a Flutter job, you've at least built a counter app with Flutter, and hopefully something a bit more complex. But publishing it to the Play Store, App Store or any store could potentially earn you some money if you implement in-app purchases. There are plenty of indie developers making a full-time income by building apps, either by going all-in one one app, or building several small ones. With the right idea and execution (Flutter helps with the execution!), you can earn money on your own, with your own apps.

Going indie and making your own Flutter apps as a full-time job is probably the hardest option of all mentioned here, however, at least in my opinion. There's no guarantee you will get to earn as much as you would by working full-time for a company as a developer, and it could take a while to get there. I released my first Flutter mobile app a couple of years ago and I'm perfectly happy with the few coffees and lunches I get from its in-app purchases every month. It's something I'd really recommend having on the side, and it's also a great addition to your portfolio!

Wrapping up

In this article, we listed a few ways you can go about finding a job as a Flutter developer. It can be challenging, but your best best is to keep looking and applying to any opportunities you come across and are interested in. Freelancing is a viable alternative but can be more challenging, and perhaps a bit less stable than a full-time job.

In the meantime, getting more involved with the Flutter community, perhaps writing about Flutter and publishing and iterating on your Flutter apps is a great way to improve both your Flutter skills and your portfolio, as well as expand your network. These could also get more job opportunities coming your way, as well as increase your chances of getting hired next time you apply for a job as Flutter developer.

If you're reading this and looking for your first job as a Flutter developer, we wish you good luck! And if you have managed to land a job in a way not mentioned here, do let us know in the comments.

Images generated by OpenAI's DALL-E.

This article was published as the #week1 article for #4articles4weeks.

In this tutorial, we will create a Flutter plugin which targets the Android and iOS platforms using the Pigeon package.

With Flutter being a UI framework, communicating with the native platform is not something we always need or use. And usually when we do need to do so, there are tons of packages out there that already do this for specific use cases.

But there are cases when the functionality the native platform has to offer is not yet available in a public package on pub.dev. In these cases, it's up to us! We need to write some Dart code on the Flutter side to call the platform, as well as the native platform code to call the functionality we need (and that's once per platform your app supports!).

Native platform communication

Platform channels

One way to communicate with the native platform in Flutter is by using a MethodChannel. We covered how to build a plugin or call native platform code in Flutter using method channels in a previous post.

While using MethodChannel is relatively straightforward, it can actually be quite time-consuming; when calling methods through the MethodChannel, you can only pass arguments of simple types such as int, double, bool or String, as well as maps of list with such types as values. You can see the full data types support here. If you need to pass a complex object as an argument, you would need to have logic to parse this to, let's say, a map of string keys to their values. In addition, you need to do the same for any data that is returned from the native platform.

We could work around having to introduce parsing logic by using a package such as json_serializable to parse data to and from JSON to save ourselves some time. However, you'd need to make sure the native platforms are returning the data in the exact format you are expecting, and vice versa. Otherwise the parsing will fail.

Pigeon

Pigeon is a code generator package which generates all the code necessary to communicate between Flutter and any host platform. All you have to do is define the API. This is convenient, because you don't have to worry about any parsing logic, and the communication is guaranteed to be type-safe.

As of July 10th 2022, Pigeon only supports Android and iOS, and generates Java and Objective-C code (Swift is experimental) respectively. The generated code is still accessible to Kotlin or Swift. There is also experimental Windows support with C++.

Creating a plugin

In this post, we will create a simple plugin using Pigeon. What we will build will be identical to the (fake) app usage plugin we built previously, so we can compare the results.

The plugin is simple; it should return a list of all apps and their usage, as well as support the ability to set time limits on specific apps. We won't actually implement this functionality on the native side as it's outside the scope of this tutorial, but rather return dummy data from the native side instead.

The plugin template

To get started, we'll create a Flutter plugin using flutter create with the plugin template.

flutter create --org dev.dartling --template=plugin --platforms=android,ios app_usage_pigeon

This will generate the code for the plugin, as well as an example project that uses this plugin. By default, the generated Android code will be in Kotlin, and iOS in Swift, but you can specify either Java or Objective-C with the -a and -i flags respectively. (-a java and/or -i objc).

There is quite a bit of code included with the plugin template. We go into the Dart, Kotlin and Swift code into more detail in this post, if you're curious. For the context of this tutorial, it's enough to know the following:

On the Dart side, there are three classes:

• AppUsagePlatform - the "interface"/API of the plugin, which implements PlatformInterface.
• MethodChannelAppUsage - an implementation of AppUsagePlatform using method channels.
• AppUsage - the class exposing the methods to be used by any apps which need to use our plugin.

The Kotlin code generated is AppUsagePlugin.kt, which uses method channels. It is defined in our pubspec.yaml as the plugin class for the Android platform, so we'll still be needing it, though we will make some changes to it later. The same applies to the Swift code, which includes SwiftAppUsagePlugin.swift as well as AppUsagePlugin.h and AppUsagePlugin.m.

In this tutorial, we will write an implementation of AppUsagePlatform which uses Pigeon rather than method channels. We can delete MethodChannelAppUsage as we won't be needing it.

Note: the new plugin template using PlatformInterface introduces quite a bit of code that you might not really need if you just want to call some native code in your app. If you wanted, you could still use Pigeon without creating a plugin or a separate package, but that's what we'll be doing in this tutorial.

Using Pigeon

Installing the pigeon package

Let's install the package:

flutter pub add --dev pigeon

Alternatively, add this to your pubspec.yaml:

dev_dependencies:
  pigeon: ^3.2.3

Defining the App Usage API

The way Pigeon works is pretty simple; we define our API in a Dart class outside the lib folder (as Pigeon is a dev dependency). The API class should be an abstract class with the @HostApi() decorator, and its methods should have the @async decorator.

Let's define our App Usage API in a new directory named pigeons:

// pigeons/app_usage_api.dart
import 'package:pigeon/pigeon.dart';

enum State { success, error }

class StateResult {
  final State state;
  final String message;

  StateResult(this.state, this.message);
}

class UsedApp {
  final String id;
  final String name;
  final int minutesUsed;

  UsedApp(this.id, this.name, this.minutesUsed);
}

@HostApi()
abstract class AppUsageApi {
  @async
  String? getPlatformVersion();

  @async
  List<UsedApp> getApps();

  @async
  StateResult setAppTimeLimit(String appId, int minutesUsed);
}

Caveats and limitations

Defining the API was relatively simple, but there are a few things to mention:

Futures

We do not need to specify the return values as Futures, but in the generated code they will be. So getPlatformVersion will actually return a Future<String?> in the generated Dart code.

No imports allowed

No imports other than package:pigeon/pigeon.dart are allowed. This means EVERY model class should be defined in this Pigeon API file.

Supported data types

As mentioned before, only simple JSON-like values are supported. This means we can't use useful Dart types such as DateTime or Duration. Which means we might still need additional mapping logic to convert the Pigeon model to the model we want to use within the app. For minutesUsed in UsedApp, we'll need to manually create a Duration out of the minutes, though it would be nice to have this as a Duration in the first place.

Enums aren't yet supported for primitive return types

We cannot return an enum from a method, but we can have an enum as a method parameter. We can still return enums, but only if we wrap them in a separate class, like below.

// Not valid, enums cannot be returned.
enum ResultState { success, error }

@HostApi()
abstract class AppUsageApi {
  @async
  ResultState getState();
}

// Valid, enums can be method parameters and fields of returned objects.
enum ResultState { success, error }

class ApiResult {
  final ResultState state;
  final String message;

  ApiResult(this.state, this.message);
}

@HostApi()
abstract class AppUsageApi {
  @async
  ApiResult getResult();

  @async
  void setState(ResultState state);
}

Generics are supported, but can only be used with nullable types

We can still define them as non-nullable in our HostApi definition, e.g. List<Something>, but the generated Dart class will have List<Something?> instead.

Generating the code

Running the generator

After defining the API, we can generate code using flutter pub run pigeon. This command requires quite a few arguments:

flutter pub run pigeon \
  --input pigeons/app_usage_api.dart \
  --dart_out lib/app_usage_api.dart \
  --java_package "dev.dartling.app_usage" \
  --java_out android/src/main/java/dev/dartling/app_usage/AppUsage.java \
  --experimental_swift_out ios/Classes/AppUsage.swift

We will store this in a pigeon.sh file, just so it's easy to find and run in the future.

We're going with Swift which has experimental support for now rather than Objective-C, but for Objective-C we can simply drop the experimental_swift_out argument in favor of these three:

  --objc_header_out ios/Classes/AppUsageApi.h \
  --objc_source_out ios/Classes/AppUsageApi.m \
  --objc_prefix FLT

Dart

The input argument should be the file we defined the API in, and dart_out should be in our lib folder, as it's the code we'll actually be using in our app.

Java

java_package is the full package name, in this case dev.dartling.app_usage and java_out is the path to the Java file that will be generated.

Note: Make sure the generated Java class name does NOT match the name of the Pigeon HostApi. In our case, the generated Java class will be AppUsage, and will include a nested public AppUsageApi interface, taken from the HostApi class name defined in Dart. If we used the same names (which is what I did initially!), compilation will fail due to duplicate names.

Note: if your plugin template uses Kotlin, like we did in this one, you will need to create the java/dev/dartling/app_usage directory manually under src/main, as only kotlin/dev/dartling/app_usage was generated as part of the plugin template.

Swift

experimental_swift_out is the path to the Swift file that will be generated.

Objective-C

The objc_header_out and objc_source_out arguments determine the generated files on the Objective-C side, and the objc_prefix is optional and determines the prefix of the generated class names.

Understanding the generated code

The code generated by Pigeon after running flutter pub run pigeon is not something we should really have to look at often. All we need to know is that the Java class will have an AppUsageApi interface which our implementation class should implement; this can be both in either Java or Kotlin. In Objective-C, there will be a FLTAppUsageApi protocol equivalent (notice the FLT prefix which is an argument when running the generator), and in Swift an AppUsageApi protocol.

Native platform implementation

Android

We have our interface, now all we need to do is have an implementation for it. To keep things simple, we will simply the existing AppUsagePlugin Kotlin class to implement AppUsageApi, in addition to the existing FlutterPlugin interface.

Here is the full class:

// AppUsagePlugin.kt
class AppUsagePlugin : FlutterPlugin, AppUsageApi {
    val usedApps: MutableList<UsedApp> = mutableListOf(
        usedApp("com.reddit.app", "Reddit", 75),
        usedApp("dev.hashnode.app", "Hashnode", 37),
        usedApp("link.timelog.app", "Timelog", 25),
    )

    override fun onAttachedToEngine(@NonNull flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) {
        AppUsageApi.setup(flutterPluginBinding.binaryMessenger, this)
    }

    override fun getPlatformVersion(result: Result<String>?) {
        result?.success("Android ${android.os.Build.VERSION.RELEASE}")
    }

    override fun getApps(result: Result<MutableList<UsedApp>>?) {
        result?.success(usedApps);
    }

    override fun setAppTimeLimit(
        appId: String,
        durationInMinutes: Long,
        result: Result<TimeLimitResult>?
    ) {
        val stateResult = TimeLimitResult.Builder()
            .setState(ResultState.success)
            .setMessage("Timer of $durationInMinutes minutes set for app ID $appId")
            .build()
        result?.success(stateResult)
    }

    private fun usedApp(id: String, name: String, minutesUsed: Long): UsedApp {
        return UsedApp.Builder()
            .setId(id)
            .setName(name)
            .setMinutesUsed(minutesUsed)
            .build();
    }

    override fun onDetachedFromEngine(@NonNull binding: FlutterPlugin.FlutterPluginBinding) {
        AppUsageApi.setup(binding.binaryMessenger, null)
    }
}

The onAttachedToEngine and onDetachedFromEngine are from FlutterPlugin. Previously they set things up to work for the method channel implementation. Now, we are calling the AppUsageApi#setup method to get it to work with Pigeon's generated code.

The other three functions we override are from the AppUsageApi interface. These are actually void functions, and we "return" the results by making use of result, which was actually generated as nullable. To return, we simply use result?.success(...), and in case we want to throw an error, we can use result?.error(...) and pass a Throwable; this will be wrapped into a PlatformException on the Dart side.

iOS

Very similarly to Android, we will make the existing SwiftAppUsagePlugin implement the AppUsageApi protocol in addition to being a FlutterPlugin. Rather than result, we have completion which we call by passing the result as the argument. We also make some changes to register to use the static AppUsageApiSetup#setUp function to set things up with the generated file.

public class SwiftAppUsagePlugin: NSObject, FlutterPlugin, AppUsageApi {
    var usedApps = [
        UsedApp(id: "com.reddit.app", name: "Reddit", minutesUsed: 75),
        UsedApp(id: "dev.hashnode.app", name: "Hashnode", minutesUsed:37),
        UsedApp(id: "link.timelog.app", name: "Timelog", minutesUsed: 25)
    ]

    public static func register(with registrar: FlutterPluginRegistrar) {
        let messenger : FlutterBinaryMessenger = registrar.messenger()
        let api : AppUsageApi & NSObjectProtocol = SwiftAppUsagePlugin.init()
        AppUsageApiSetup.setUp(binaryMessenger: messenger, api: api)
    }

    func getPlatformVersion(completion: @escaping (String?) -> Void) {
        completion("iOS " + UIDevice.current.systemVersion)
    }

    func getApps(completion: @escaping ([UsedApp]) -> Void) {
        completion(usedApps)
    }

    func setAppTimeLimit(appId: String, durationInMinutes: Int32, completion: @escaping (TimeLimitResult) -> Void) {
        completion(TimeLimitResult(state: ResultState.success, message: "Timer of \(durationInMinutes) minutes set for app ID \(appId)"))
    }
}

Note: I've faced some weird issues with the iOS build sometimes not succeeding due to AppUsageApi not being found in the scope. If you run into the same issue, the quick hacky way is to copy everything in the generated AppUsage.swift into the existing SwiftAppUsagePlugin.swift file. Then it should work! If you figure out how/why this happens and how to fix it, please let me know in the comments!

Using the plugin

We now have everything in place. The native platform implementations are done, and the AppUsageApi Dart class can be used to communicate with the native platforms.

All we have to do is create an instance of AppUsageApi and invoke its method... but wait, we're building a plugin! We should not use AppUsageApi directly (though we could!). Remember the MethodChannelAppUsage Dart class we deleted a while ago? We need to introduce an alternative that will use Pigeon instead of method channels.

Firstly, let's add make sure all methods that are part of our Pigeon HostApi are also defined in our AppUsagePlatform.

abstract class AppUsagePlatform extends PlatformInterface {
  ...

  Future<String?> getPlatformVersion() {
    throw UnimplementedError('platformVersion() has not been implemented.');
  }

  Future<List<UsedApp>> get apps async {
    throw UnimplementedError('apps has not been implemented.');
  }

  Future<TimeLimitResult> setAppTimeLimit(String appId, Duration duration) async {
    throw UnimplementedError('setAppTimeLimit() has not been implemented.');
  }
}

Now, our AppUsagePlatform implementation with Pigeon is very simple. We're simply going to invoke the methods of AppUsageApi, which was generated by Pigeon.

// app_usage_pigeon.dart
/// An implementation of [AppUsagePlatform] that uses Pigeon.
class PigeonAppUsage extends AppUsagePlatform {
  final AppUsageApi _api = AppUsageApi();

  @override
  Future<String?> getPlatformVersion() {
    return _api.getPlatformVersion();
  }

  @override
  Future<List<UsedApp>> get apps {
    return _api
        .getApps()
        .then((apps) => apps.where((e) => e != null).map((e) => e!).toList());
  }

  @override
  Future<TimeLimitResult> setAppTimeLimit(String appId, Duration duration) async {
    return _api.setAppTimeLimit(appId, duration.inMinutes);
  }
}

Note that in apps we filter null values and use the ! operator, as AppUsageApi#getApps() returns List<UsedApp?>, due to Pigeon's current limitations.

Lastly, AppUsage, our main plugin class, should also be updated. All it does is delegate method calls to AppUsagePlatform.instance.

class AppUsage {
  Future<String?> getPlatformVersion() {
    return AppUsagePlatform.instance.getPlatformVersion();
  }

  Future<List<UsedApp>> get apps {
    return AppUsagePlatform.instance.apps;
  }

  Future<TimeLimitResult> setAppTimeLimit(String appId, Duration duration) {
    return AppUsagePlatform.instance.setAppTimeLimit(appId, duration);
  }
}

And let's not forget, that AppUsagePlatform.instance should now return an instance of PigeonAppUsage rather than MethodChannelAppUsage:

abstract class AppUsagePlatform extends PlatformInterface {
  ...

  static AppUsagePlatform _instance = PigeonAppUsage();

  /// The default instance of [AppUsagePlatform] to use.
  ///
  /// Defaults to [PigeonAppUsage].
  static AppUsagePlatform get instance => _instance;

  ...
}

I won't share snippets of the UI code and widgets, but you can take look at these here. Using the plugin in any app is simple; we initialize an instance of AppUsage and call its methods we need them.

Here is the final result:

Comparing Pigeon and method channels

We built an almost identical plugin and example app in a previous article, so we can compare Pigeon with using method channels.

Overall, Pigeon is definitely an improvement. We only have to define our API and models once; the generated Android/iOS will include these models for us.

We also don't have to worry about serializing data we want to pass to the platform side or deserialize data coming from the platform side, and the opposite for the platform side; we won't have to worry about deserializing data coming from the Dart side and serializing data we return to the Dart side.

Thanks to the two points above, we needed significantly less lines of code to write a plugin using Pigeon rather than method channels.

Wrapping up

In this tutorial, we introduced Pigeon as a way to simplify native platform communication, and created a custom Flutter plugin with Android and iOS implementations to call (fake) native functionality, using Pigeon rather than method channels.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email below.

In this blog post, we will enhance our app's theme to use dynamic colors taken from Material 3's OS-defined color scheme.

In Android 12, Material You, the third iteration of Material Design was introduced. One of the main features of Material 3 is Dynamic Color, which allows users to select their own color scheme for the whole OS, derived from the wallpaper.

This results in a set of primary, secondary and tertiary colors being consistent across the whole OS as well as built-in apps such as the clock, calculator, and even some Google apps such as Photos.

You may not always want implement this for your apps, especially if your app needs to follow specific brand guidelines (and if color is an important part of your brand). However, in some cases, supporting a dynamic color theme might make sense, depending on your app and brand.

In this post, we will enhance the default Flutter counter app with dynamic color, using the dynamic_color Flutter package provided by the Material team.

Using Material 3

For this tutorial, we will be working with the basic Flutter counter app example, but with one small change. We will change the provided theme from the below:

ThemeData(
    primarySwatch: Colors.blue,
)

To this:

ThemeData(
    colorScheme: ColorScheme.fromSwatch(primarySwatch: Colors.blue),
    useMaterial3: true,
)

We do this in order to enable Material 3 using the useMaterial3 flag. Not all widgets in Flutter are "Material 3-ready" as of yet, so we need to enable this explicitly.

We replace primarySwatch with colorScheme, but these actually do the same thing. However, colorScheme is now actually the preferred way to configure colors. We also do this because we will use colorScheme for the dynamic color.

We've also added three boxes showing the color scheme's primary, secondary and tertiary colors. This is so we can compare and see what happens to the color scheme once we've implemented dynamic color.

Here is how our app looks before and after this, if you're curious.

Using dynamic color

The dynamic_color package

The Material team has already created a package to help with this. It returns a Material color scheme based on a platform's implementation of dynamic color. This is actually not specific to just Material 3 and Android!

From the package's GitHub repo page, here is what you get from each platform:

• Android (12 and up) - color from the wallpaper
• Linux - GTK+ theme's @theme_selected_bg_color
• macOS - app accent color
• Windows - accent color or window/glass color

Let's install the package:

flutter pub add dynamic_color

Alternatively, add this to your pubspec.yaml:

dependencies:
  dynamic_color: ^1.4.0

The DynamicColorBuilder widget

Let's now make use of the dynamic_color package to actually use dynamic colors. We can do this with the DynamicColorBuilder, a builder widget that uses a plugin under the hood to fetch the dynamic color from the OS and returns a light and dark color scheme.

DynamicColorBuilder({
    Key? key,
    required this.builder,
})

DynamicColorBuilder accepts an optional key and requires a builder which should return whatever widget we want to enhance with dynamic colors. The builder widget's signature looks like this:

Widget Function(
    ColorScheme? lightDynamic,
    ColorScheme? darkDynamic,
)

We can return a widget, any widget, and the builder includes a light dynamic color scheme as well as a dark dynamic color scheme. Both color schemes are nullable; if the OS does not respond or the platform does not support dynamic color (like with older Android versions), it returns null.

Using dynamic color schemes

We now have the dynamic_color package installed, and know how the DynamicColorBuilder widget works. Let's use it to make use of the system's color scheme.

Here's what the build method of our root MyApp widget looks like now:

@override
Widget build(BuildContext context) {
  return DynamicColorBuilder(builder: (lightColorScheme, darkColorScheme) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: lightColorScheme ?? _defaultLightColorScheme,
        useMaterial3: true,
      ),
      darkTheme: ThemeData(
        colorScheme: darkColorScheme ?? _defaultDarkColorScheme,
        useMaterial3: true,
      ),
      themeMode: ThemeMode.dark,
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  });
}

We've wrapped the MaterialApp widget with DynamicColorBuilder. For the theme, we replaced the previous colorScheme with the light color scheme provided by the builder. We also provided a darkTheme in addition to theme, which uses the dark color scheme provided by the builder. Note that since both color schemes are nullable, we have default color schemes, which we've extracted to static constants.

static final _defaultLightColorScheme =
    ColorScheme.fromSwatch(primarySwatch: Colors.blue);

static final _defaultDarkColorScheme = ColorScheme.fromSwatch(
    primarySwatch: Colors.blue, brightness: Brightness.dark);

These are exactly what we had before, with additionally the dark color scheme which we define in exactly the same way, plus the dark brightness value.

And that's it! With just a trivial amount of lines of code added (less than 10 if you don't count the default color schemes), we have a theme with a color scheme which dynamically changes depending on your operating system's settings. Here's how it looks like now:

A small note if you're implementing this for your app. In debug mode, when the app loads for the first time you may quickly see the app load with the default color scheme for a split second before refreshing with the dynamic color scheme. Not to worry though, this won't be the case for your production app!

Wrapping up

In this tutorial, we showed how to implement dynamic color in themes in our Flutter app, to make use of the Material 3, or You, dynamic color feature available in Android 12.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email below.

Swipe actions, or swipe gestures, are something that's very common in mobile apps. In its most common form, the "swipe to dismiss" pattern is something you might have seen in email apps, for example, where you swipe left to delete an email. Some apps now even let you customize the action happening when you swipe left or right (hence swipe actions), and you don't necessarily have to dismiss something either; an example would be the "swipe to reply" pattern implemented in some messaging apps.

In this post, we will go over how to implement swipe actions in Flutter using the Dismissible widget. We will implement a "swipe to delete" action for a (very) simple messaging app, with a confirmation dialog, as well as a "swipe to star (favorite)" action.

In case you're still unsure about what a "swipe action" looks, here's what we'll be building in this post:

At the end, if actions for swiping left or right are not enough for you, we will show how to easily implement multiple "slide" actions with the flutter_slidable package.

The Dismissible widget

We can make any widget "dismissible" by wrapping it with the Dismissible widget:

Dismissible(
  key: UniqueKey(),
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

At a minimum, this widget requires a child, which can be any widget we want to dismiss/swipe/slide, as well as a key. With the above code snippet, what we have is a regular ListTile widget which disappears when swiped in any horizontal direction.

Directions

By default, a dismissible widget can be swiped left or right. But we can customize this.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
  },
  child: ...
),

With endToStart, our widget can only be swiped from its end to the start. In our case, this is a swipe to the left. However, this is either right-to-left or left-to-right depending on the reading direction of the Flutter app's locale. English is read from left to right, so endToStart is right to left.

Below are the possible DismissDirection values:

• endToStart - Can be swiped left (or right depending on reading direction).
• startToEnd - Can be swiped right (or left depending on reading direction).
• horizontal - Can be swiped both left and right.
• up - Can be swiped up.
• down - Can be swiped down.
• vertical - Can be swiped both up and down.
• none - Cannot be swiped, or dismissed.

The none value might seem a bit redundant, as you could just not wrap a widget with the Dismissible widget at all. But there might be cases where you have a list of dismissible widgets, and might want to dynamically choose whether a specific item in the list can be dismissed or not. In that case, you could use none.

The onDismissed callback is called after a widget is swiped and dismissed. It is called with the direction it was dismissed in. If your widget should only be swiped in one direction, you might not use this, but if you use the horizontal or vertical directions, you could check in which direction the widget was dismissed if you want to react differently for each direction.

Swipe, but don't dismiss

The "swipe to dismiss" part has been quite easy so far, it already works! But what if you don't want to dismiss? The confirmDismiss callback parameter is called before the widget is dismissed, and returns a Future<bool>. If false is returned, the widget is not dismissed.

This helps if, for example, you want to a confirm a dismissal or deletion; you could show a dialog so that the user can confirm their action. Or maybe your swipe action might never dismiss the widget at all; in that case you'd just always return false.

Implementing swipe actions

Now that we have a basic Dismissible widget working, let's implement some swipe actions for our messaging app. When swiping left, we want to delete a message. When swiping right, we want to "star"/favorite the message.

Swipe to delete

Here's our widget so far:

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
    // Your deletion logic goes here.
  },
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

This is really all we need for the "swipe to delete" action. The widget is dismissed as soon as we finish swiping, so for a basic demo this is enough. In a real app, you might have to add some additional logic in the onDismissed callback, for example to actually delete the message from your database.

Confirm dismissal/deletion

A problem with "destructive" swipe actions such as "swipe to delete" is that a user could easily swipe something left accidentally. For our deletion swipe action, we can make use of the confirmDismiss callback to ask the user if they really want to delete their message.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
    // Your deletion logic goes here.
  },
  confirmDismiss: (DismissDirection direction) async {
    final confirmed = await showDialog<bool>(
      context: context,
      builder: (context) {
        return AlertDialog(
          title: const Text('Are you sure you want to delete?'),
          actions: [
            TextButton(
              onPressed: () => Navigator.pop(context, false),
              child: const Text('No'),
            ),
            TextButton(
              onPressed: () => Navigator.pop(context, true),
              child: const Text('Yes'),
            )
          ],
        );
      },
    );
    log('Deletion confirmed: $confirmed');
    return confirmed;
  },
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

A bit lengthier than before, but if we extract the AlertDialog part to a method or widget, the code is not very complicated.

Background

Right now, it's not clear that swiping will actually delete the message, even if we do show a confirmation dialog. We can specify a background parameter, which is of course a widget, and show a colored background with an icon.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  ...
  background: const ColoredBox(
    color: Colors.red,
    child: Align(
      alignment: Alignment.centerRight,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.delete, color: Colors.white),
      ),
    ),
  ),
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

Here's how the deletion flow looks below, with the confirmation dialog.

Swipe to star

Now, here's where it gets a little trickier! For the "swipe to star" action, we don't want to dismiss the widget after swiping to the right, but we also want to behave differently depending on the swipe direction.

First, we change the direction of our Dismissible widget to horizontal, as we want to swipe both left as well as right. Second, both our onDismissed and confirmDismiss callback functions need to be updated.

For both functions, our deletion logic should only be called if the direction is endToStart. If not, we can assume it's startToEnd and include our starring logic.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.horizontal,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
    if (direction == DismissDirection.endToStart) {
      // Your deletion logic goes here.
    }
  },
  confirmDismiss: (DismissDirection direction) async {
    if (direction == DismissDirection.endToStart) {
      final confirmed = await _confirmDeletion(context);
      log('Deletion confirmed: $confirmed');
      return confirmed;
    } else {
      log('Starring');
      // The widget is never dismissed in this case. Your star logic goes here.
      setState(() {
        _isStarred = !_isStarred;
      });
      return false;
    }
  },
  background: const ColoredBox(
    color: Colors.red,
    child: Align(
      alignment: Alignment.centerRight,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.delete, color: Colors.white),
      ),
    ),
  ),
  child: ListTile(
    leading: const Icon(Icons.flutter_dash),
    title: const Text('Dash'),
    subtitle: const Text('Hello!'),
    trailing: Icon(_isStarred ? Icons.star : Icons.star_outline),
  ),
),

We've updated the message widget to show a filled star if it's starred, or an outlined star if not, and keep track of this with a simple boolean field in the state, just to keep things simple.

One thing to note here is that since we never want to dismiss the widget when we star a message, we always return false in confirmDismiss. Because of this, the onDismissed callback is never called, so our starring logic should be called in confirmDismiss, if the direction is what we expect.

Secondary background

There's one thing left; the background! We now show the red background with the trash icon when swiping both left and right. For starring, we would like to show an orange background with a star icon, and since we swipe right, the icon should be on the left. The Dismissible widget makes it very easy to have a separate background depending on the swipe direction.

For this case, we're going to have both a background and a secondaryBackground.

Dismissible(
  ...
  background: const ColoredBox(
    color: Colors.orange,
    child: Align(
      alignment: Alignment.centerLeft,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.star, color: Colors.white),
      ),
    ),
  ),
  secondaryBackground: const ColoredBox(
    color: Colors.red,
    child: Align(
      alignment: Alignment.centerRight,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.delete, color: Colors.white),
      ),
    ),
  ),
  child: ListTile(...),
),

Notice that the red deletion background is now actually the secondaryBackground, and the new orange background as the background, because of the directions.

Here is the "swipe to star" action implementation in action:

And that is all for the swipe-able message list tile! You can check out the full widget and app code in the source code here.

More on the Dismissible widget

We've gone over a lot of what the Dismissible widget can do, but its constructor accepts a few more optional arguments which we could make use of.

• VoidCallback onResize - A callback function called (multiple times) just before the widget is dismissed, while being resized (contracted). Note: it's actually the background you see being contracted.
• Duration? resizeDuration - The duration of the resizing/contracting that happens before the widget is dismissed. If you set this to a long enough duration, you can see the background widget slowly being "squeezed up" and disappearing. Set this to null and the background widget doesn't resize; it just stays there.
• Map<DismissDirection, double> dismissThresholds - This is a useful one. It's a map of directions to a "threshold" (defaults to 0.4), which means that you have to drag a widget at least 40% in a given direction to actually perform the dismissal and the callbacks to be called. So you could raise or reduce the "sensitivity" of your swipe-able widgets.
• Duration movementDuration - Not to be confused with resizeDuration, this is the duration of the widget sliding back to its place in case dismissal was not confirmed, or if you've already swiped past the threshold and the widget keeps moving on its own.
• DismissUpdateCallback? onUpdate - Is called while the widget is being dragged. The details include the direction as well as whether the threshold has been reached. A use case for this, mentioned in the documentation, is that you could dynamically change the background of the dismissible widget as soon as the threshold is reached, rather than always displaying it.

Slide actions with flutter_slidable

We can now implement swipe-able widgets with different actions depending on the direction. If you want to do even more actions with a swipe, you can try out the flutter_slidable package. On swiping/sliding, the background reveals multiple actions that can be done.

We won't go into the implementation details here; the pub.dev page is already quite helpful! But here is what these "slide actions" would look like using the package:

Wrapping up

In this tutorial, we showed how to implement swipe actions (or gestures) to swipe to delete or star a message.

We also dug a little deeper into the Dismissible widget and what it can do (but of course the documentation also goes a good job explaining this!).

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email below.

In this tutorial, we will create a Flutter plugin which targets the Android and iOS platforms, and show how to invoke different methods from Dart, pass arguments of different types, and receive and parse results from the host platforms. The platform code won't actually call any real native APIs, but rather return some hard-coded data. But by the end of this tutorial, doing that part should hopefully be easy!

Flutter is mainly a UI framework, and so for a lot platform-specific functionality, we usually use plugins, typically created by the Dart and Flutter community, to achieve things such as getting the current battery level, or displaying local notifications. However, in some cases, there might not be a plugin already available, or the platform we are targeting might not be supported. In such cases, writing our own custom plugin (or contributing to an existing plugin), might be our only option.

[Updated July 9th 2022] Made changes to reflect the updated plugin templates which use platform interfaces, and added a small section on tests.

Starting with the plugin template

To get started, we'll create a Flutter plugin using flutter create with the plugin template.

flutter create --org dev.dartling --template=plugin --platforms=android,ios app_usage

This will generate the code for the plugin, as well as an example project that uses this plugin. By default, the generated Android code will be in Kotlin, and iOS in Swift, but you can specify either Java or Objective-C with the -a and -i flags respectively. (-a java and/or -i objc).

Of course, you could target more platforms if you want. For this tutorial, we will only be targeting Android and iOS.

Next, let's take a look at the generated Dart, Kotlin and Swift code after running flutter create.

Dart code

This auto-generated plugin comes with three Dart files. First is AppUsagePlatform, which extends PlatformInterface. This defines the interface, or API, of your plugin.

// app_usage_platform_interface.dart
abstract class AppUsagePlatform extends PlatformInterface {
  /// Constructs a AppUsagePlatform.
  AppUsagePlatform() : super(token: _token);

  static final Object _token = Object();

  static AppUsagePlatform _instance = MethodChannelAppUsage();

  /// The default instance of [AppUsagePlatform] to use.
  ///
  /// Defaults to [MethodChannelAppUsage].
  static AppUsagePlatform get instance => _instance;

  /// Platform-specific implementations should set this with their own
  /// platform-specific class that extends [AppUsagePlatform] when
  /// they register themselves.
  static set instance(AppUsagePlatform instance) {
    PlatformInterface.verifyToken(instance, _token);
    _instance = instance;
  }

  Future<String?> getPlatformVersion() {
    throw UnimplementedError('platformVersion() has not been implemented.');
  }
}

There is a getPlatformVersion which throws an UnimplementedError which we should not touch; it should be overriden by classes extending this one.

Platform interface and federated plugins

PlatformInterface is used to support federated plugins, which allow to split support of different packages in separate platforms. For example, if we look at the battery_plus package, which can be used to access battery information on any platform, has every implementation as a separate package dependency, as well as a dependency on battery_plus_platform_interface.

You can take a look at the documentation if you're interested in learning more about federated plugins, but the general idea is that separate platform implementations can be separate packages and can be maintained independently.

Method channels

The second class is MethodChannelAppUsage, which extends AppUsagePlatform. It's an implementation of our platform interface which uses a MethodChannel. It overrides getPlatformVersion and invokes a specific method in this method channel, which is implemented in both Android and iOS to return the current platform version.

// app_usage_method_channel.dart
/// An implementation of [AppUsagePlatform] that uses method channels.
class MethodChannelAppUsage extends AppUsagePlatform {
  /// The method channel used to interact with the native platform.
  @visibleForTesting
  final methodChannel = const MethodChannel('app_usage');

  @override
  Future<String?> getPlatformVersion() async {
    final String? version =
        await methodChannel.invokeMethod('getPlatformVersion');
    return version;
  }
}

The MethodChannel constructor accepts a channel name, which is the name of the channel on which communication between the Dart code and the host platform will happen. This name is typically the plugin name, and this is what the generated code uses, but some plugins usually use a combination of the application package/ID or domain. So for this example we could go for something like dev.dartling.app_usage or dartling.dev/app_usage.

Let's dig a little deeper into MethodChannel#invokeMethod:

 Future<T?> invokeMethod<T>(String method, [ dynamic arguments ])

We can specify which type we expect to be returned by the method channel, and the future's result can always be null. So in the platformVersion getter above, we could be more explicit and use _channel.invokeMethod<String>('getPlatformVersion') instead.

Last but not least, we have the AppUsage class. This is what we'll actually be using in our apps, and in the example app. By default, in the plugin template, there is already an example sub-folder with a Flutter app showing how AppUsage#getPlatformVersion can be used.

// app_usage.dart
class AppUsage {
  Future<String?> getPlatformVersion() {
    return AppUsagePlatform.instance.getPlatformVersion();
  }
}

All this does is call the current instance of AppUsagePlatform and call the appropriate, or in this case the only, method: getPlatformVersion(). In AppUsagePlatform, you can see that instance is actually the implementation using method channels: MethodChannelAppUsage.

To sum up, the 3 classes generated by the plugin template are:

• AppUsagePlatform - A "platform" class which extends PlatformInterface, which defines the API of our plugin (i.e. methods are defined but throw UnimplementedErrors). The default instance (returned by the instance getter) of this class returns the default implementation.
• MethodChannelAppUsage - A class which extends AppUsagePlatform and overrides every unimplemented method in that class. It uses method channels for the method implementations. This is what is returned with AppUsagePlatform.instance.
• AppUsage - The actual class of our plugin to be used by anyone requiring the plugin's functionality. In the background, this invokes the methods of AppUsagePlatform.instance.

Kotlin code (Android)

// AppUsagePlugin.kt
class AppUsagePlugin : FlutterPlugin, MethodCallHandler {
    private lateinit var channel: MethodChannel

    override fun onAttachedToEngine(@NonNull flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) {
        channel = MethodChannel(flutterPluginBinding.binaryMessenger, "app_usage")
        channel.setMethodCallHandler(this)
    }

    override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
        if (call.method == "getPlatformVersion") {
            result.success("Android ${android.os.Build.VERSION.RELEASE}")
        } else {
            result.notImplemented()
        }
    }

    override fun onDetachedFromEngine(@NonNull binding: FlutterPlugin.FlutterPluginBinding) {
        channel.setMethodCallHandler(null)
    }
}

The onAttachedToEngine and onDetachedFromEngine methods are pretty standard and we won't have to touch them at all. One note about onAttachedToEngine, is the MethodChannel constructor which also accepts a channel name. This name should match whatever we pass in the constructor on the Flutter side of things, so if you decide to go with a different name, make sure you change it in the constructors of all platforms.

The onMethodCall method is where the bulk of the logic happens, and will happen, when we add more functionality to our plugin. This method accepts two parameters. The first, the MethodCall, contains the data we pass from the invokeMethod invocation in Dart. So, MethodCall#method will return the method name (String), and MethodCall#arguments contains any arguments we pass along with the invocation. arguments is an Object, and can be used in different ways, but more on that later.

The Result can be used to return data or errors to Dart. This must always be used, otherwise the Future will never complete, and the invocation would hang indefinitely. With result, we can use the success(Object) method to return any object, error(String errorCode, String errorMessage, Object errorDetails) to return errors, and notImplemented() if the method we are invoking is not implemented (this is what happens in the else block above).

Swift code (iOS)

// SwiftAppUsagePlugin.swift
public class SwiftAppUsagePlugin: NSObject, FlutterPlugin {
  public static func register(with registrar: FlutterPluginRegistrar) {
    let channel = FlutterMethodChannel(name: "app_usage", binaryMessenger: registrar.messenger())
    let instance = SwiftAppUsagePlugin()
    registrar.addMethodCallDelegate(instance, channel: channel)
  }

  public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
    result("iOS " + UIDevice.current.systemVersion)
  }
}

Note that in the generated Swift code, there are no checks for the getPlatformVersion method name. Let's make some changes to the handle method, to keep things consistent across the two platforms.

public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
if (call.method == "getPlatformVersion") {
    result("iOS " + UIDevice.current.systemVersion)
} else {
    result(FlutterMethodNotImplemented)
}

Similarly to Android/Kotlin, FlutterMethodCall has a method string and dynamic arguments. But FlutterResult is a bit different. For a "successful" return, you can just pass any value in result(...). If the method is not implemented, just pass FlutterMethodNotImplemented, as shown above. And for errors, pass FlutterError.init(code: "ERROR_CODE", message: "error message", details: nil).

Returning complex objects

Now that we've seen how the code looks across Dart and our target platforms, let's implement some new functionality. Let's say that our App Usage plugin should return a list of the used apps, showing how much time we spend on each app.

We need to update all 3 classes to support a new method, but all we need to do is add a new method in each class.

// app_usage_platform_interface.dart
Future<List<UsedApp>> get apps async {
  throw UnimplementedError('apps has not been implemented.');
}

// app_usage_method_channel.dart
@override
Future<List<UsedApp>> get apps async {
  final List<dynamic>? usedApps =
      await methodChannel.invokeListMethod<dynamic>('getUsedApps');
  return usedApps?.map(UsedApp.fromJson).toList() ?? [];
}

// app_usage.dart
Future<List<UsedApp>> get apps {
  return AppUsagePlatform.instance.apps;
}

// models.dart
class UsedApp {
  final String id;
  final String name;
  final Duration timeUsed;

  UsedApp(this.id, this.name, this.timeUsed);

  static UsedApp fromJson(dynamic json) {
    return UsedApp(
      json['id'] as String,
      json['name'] as String,
      Duration(minutes: json['minutesUsed'] as int),
    );
  }
}

It seems a little tedious to change 3 classes just to support one new method, but at least the idea is simple. The main logic is in MethodChannelAppUsage; in AppUsagePlatform we simply define the method signature and just throw an error, and in AppUsage we simply call the method.

Notice that we actually expect a List<dynamic> rather than List<UsedApp> when we invoke a method from the channel, and map these to UsedApp using the fromJson method. We cannot just cast complex objects, though this will work fine for simple types such as int, double, bool and String. This is because the standard platform channels only support specific data types, which you can read more about here.

Calling _channel.invokeMethod<UsedApp>(...) will result to this error:

The following _CastError was thrown building MyApp(dirty, state: _MyAppState#8bcb2):
type '_InternalLinkedHashMap<Object?, Object?>' is not a subtype of type 'UsedApp' in type cast

Also notice that we used the convenience invokeListMethod<T>, since we are expecting a list of items to be returned. The above method is equivalent to _channel.invokeMethod<List<dynamic>>(...). There is also the invokeMapMethod<K, V> if we are expecting a map.

Now, let's implement getUsedApps on the Android and iOS platforms. If we don't, and try to invoke this method from the example app (or any app), we will see this error:

Unhandled Exception: MissingPluginException(No implementation found for method getUsedApps on channel app_usage)

For Android, we have to update our onMethodCall function in AppUsagePlugin. We replace the if statement with a when, to make things a bit simpler.

// AppUsagePlugin.kt
class AppUsagePlugin : FlutterPlugin, MethodCallHandler {
    private var appUsageApi = AppUsageApi()

    override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
        when (call.method) {
            "getPlatformVersion" -> result.success("Android ${android.os.Build.VERSION.RELEASE}")
            "getUsedApps" -> result.success(appUsageApi.usedApps.stream().map { it.toJson() }
                .toList())
            else -> result.notImplemented()
        }
    }
}

When invoking getUsedApps, we simply use the AppUsageApi to return the used apps, map them to a list of JSON objects (actually just a map of string to a value), and return them with result.

This is what AppUsageApi looks like, if you're curious:

// AppUsageApi.kt
data class UsedApp(val id: String, val name: String, val minutesUsed: Int) {
    fun toJson(): Map<String, Any> {
        return mapOf("id" to id, "name" to name, "minutesUsed" to minutesUsed)
    }
}

class AppUsageApi {
    val usedApps: List<UsedApp> = listOf(
        UsedApp("com.reddit.app", "Reddit", 75),
        UsedApp("dev.hashnode.app", "Hashnode", 37),
        UsedApp("link.timelog.app", "Timelog", 25),
    )
}

Just a data class and some hard-coded values. We could have made this simpler and just returned a Map<String, Any> straight from here, but realistically, an API would return its own data classes/models.

Similarly, for iOS, we need to update the handle function in SwiftAppUsagePlugin.

// AppUsageApi
struct UsedApp {
    var id: String
    var name: String
    var minutesUsed: Int

    func toJson() -> [String: Any] {
        return [
            "id": id,
            "name": name,
            "minutesUsed": minutesUsed
        ]
    }
}

class AppUsageApi {
    var usedApps = [
        UsedApp(id: "com.reddit.app", name: "Reddit", minutesUsed: 75),
        UsedApp(id: "dev.hashnode.app", name: "Hashnode", minutesUsed: 37),
        UsedApp(id: "link.timelog.app", name: "Timelog", minutesUsed: 25)
    ]
}

// SwiftAppUsagePlugin.swift
public class SwiftAppUsagePlugin: NSObject, FlutterPlugin {
  private var appUsageApi = AppUsageApi()

  public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
    switch (call.method) {
        case "getPlatformVersion":
            result("iOS " + UIDevice.current.systemVersion)
        case "getUsedApps":
            result(appUsageApi.usedApps.map { $0.toJson() })
        default:
            result(FlutterMethodNotImplemented)
    }
  }
}

I will not be sharing many snippets from the example app and usages of the AppUsage functions, just to keep the tutorial shorter, but you can take a look at the source code here. But the actual usage of the plugin is quite simple. We are simply calling the static methods of AppUsage to get data from the host platform, and display it. But in case you're curious to see the method in action, this is how the example app looks like:

Passing arguments

So far, we've shown how to receive data from the host platform. Now what if we want to pass data instead? Let's introduce a new method to our App Usage API. Once again, 3 times!

// app_usage_platform_interface.dart
Future<String> setAppTimeLimit(String appId, Duration duration) async {
  throw UnimplementedError('setAppTimeLimit() has not been implemented.');
}

// app_usage_method_channel.dart
@override
Future<String> setAppTimeLimit(String appId, Duration duration) async {
  try {
    final String? result =
        await methodChannel.invokeMethod('setAppTimeLimit', {
      'id': appId,
      'durationInMinutes': duration.inMinutes,
    });
    return result ?? 'Could not set timer.';
  } on PlatformException catch (ex) {
    return ex.message ?? 'Unexpected error';
  }
}

// app_usage.dart
Future<String> setAppTimeLimit(String appId, Duration duration) {
  return AppUsagePlatform.instance.setAppTimeLimit(appId, duration);
}

The difference with the previous method is that we're now also passing parameters to invokeMethod, which is an optional field. While the type of parameters is dynamic, and so could be anything, it's recommended to use a map.

Since our implementation won't actually set any app time limits, it would still be nice to confirm that the host platform has properly received the passed parameters, in our case id and minutes. So to keep things simple, we just want to return a string containing a confirmation that the time limit was set for the given app ID and duration.

Here's the Android/Kotlin implementation:

// AppUsageApi.kt
fun setTimeLimit(id: String, durationInMinutes: Int): String {
    return "Timer of $durationInMinutes minutes set for app ID $id";
}

// AppUsagePlugin.kt
override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
    when (call.method) {
        ...
        "setAppTimeLimit" -> result.success(
            appUsageApi.setTimeLimit(
                call.argument<String>("id")!!,
                call.argument<Int>("durationInMinutes")!!
            )
        )
        else -> result.notImplemented()
    }
}

We get the arguments from the passed parameters using MethodCall#argument, and specify the type we expect the argument to have. This method only works if the parameters passed are either a map or a JSONObject. The method returns an optional result we could be null, hence the !! operator. If the argument for that key in the map is missing or has a different type, an exception is thrown.

Alternatively, we could return the whole map by using:

call.arguments()

We can also check if the argument exists by using:

call.hasArgument("id") // true
call.hasArgument("appId") // false

Next, the iOS/Swift code:

// AppUsageApi
func setTimeLimit(id: String, durationInMinutes: Int) -> String {
    return "Timer of \(durationInMinutes) minutes set for app ID \(id)"
}

// SwiftAppUsagePlugin.swift
public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
  switch (call.method) {
      ...
      case "setAppTimeLimit":
          let arguments = call.arguments as! [String: Any]
          let id = arguments["id"] as! String
          let durationInMinutes = arguments["durationInMinutes"] as! Int
          result(appUsageApi.setTimeLimit(id: id, durationInMinutes: durationInMinutes))
      default:
          result(FlutterMethodNotImplemented)
  }
}

Very similar, but unlike Kotlin, there are no convenience methods to get an argument by its key. Instead, we need to cast call.arguments to a map of String to Any, and then cast each argument to the type we expect it in. Both the arguments and any values in the map can be null, which is why we need the ! operator when casting.

And that's it for the platform implementations! In the example app, I've added an icon button which calls this method and displays snackbar with the result string.

// EXAMPLE APP: main.dart
IconButton(
  icon: const Icon(Icons.timer_outlined),
  onPressed: () async {
    // TODO: Set duration manually.
    final scaffoldMessenger = ScaffoldMessenger.of(context);
    final String result = await _appUsagePlugin.setAppTimeLimit(
        app.id, const Duration(minutes: 30));
    scaffoldMessenger
        .showSnackBar(SnackBar(content: Text(result)));
  },
)

Note: we store ScaffoldMessengerState in a variable (scaffoldMessenger) before awaiting for the plugin's setAppTimeLimit because we should not use BuildContext across async gaps.

Error handling

We've now learned how to read data returned from the host platform, and pass data to the host platform. For the last part, we'll return an error from the platform side and catch it.

For this example, we'll just be doing this on the Android side. Let's improve the implementation for setAppTimeLimit.

override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
    when (call.method) {
        ...
        "setAppTimeLimit" -> {
            if (!call.hasArgument("id") || !call.hasArgument("durationInMinutes")) {
                result.error(
                    "BAD_REQUEST",
                    "Missing 'id' or 'durationInMinutes' argument",
                    Exception("Something went wrong")
                )
            }
            result.success(
                appUsageApi.setTimeLimit(
                    call.argument<String>("id")!!,
                    call.argument<Int>("durationInMinutes")!!
                )
            )
        }
        else -> result.notImplemented()
    }

If either the id or durationInMinutes arguments are missing from the method call, we'll throw a more helpful exception. Otherwise, we'd just get a null pointer exception when calling call.argument<T>("key")!!.

This results in a PlatformException being thrown from invokeMethod on the Flutter side. To handle it, we could do the following.

static Future<String> setAppTimeLimit(String appId, Duration duration) async {
  try {
    final String? result = await _channel.invokeMethod('setAppTimeLimit', {
      'appId': appId,
      'durationInMinutes': duration.inMinutes,
    });
    return result ?? 'Could not set timer.';
  } on PlatformException catch (ex) {
    return ex.message ?? 'Unexpected error';
  }
}

In the snippet above we replaced the id argument with appId, which will lead to a platform exception.

Testing

The plugin templates already comes with tests for AppUsage as well as MethodChannelAppUsage. No tests necessary for AppUsagePlatform as all it does is throw errors!

They are both nicely set up and easy to extend; the test for AppUsage already provides a mock implementation of AppUsagePlatform and sets it as the default instance, and the test for MethodChannelAppUsage mocks the method call handler's return values.

Take a look at the tests in the source code to see how we tested the new methods added for our App Usage plugin.

Alternatives

One not-so-nice aspect of host platform to Flutter communication with MethodChannel is the serialization/deserialization part. When passing many arguments, we need to pass them in a map, and accessing them, casting them, and checking if they exist is not very nice. Same for parsing data returned from the method calls; for this tutorial we needed to map the UsedApp list to a JSON-like map from the Kotlin/Swift code, and then implement a method to create a UsedApp from the returned list on the Flutter side. This can be time-consuming, but also error-prone (all our fields/keys are hard-coded strings and have to be kept in sync across 3 different languages!).

Enter Pigeon, an alternative to MethodChannel for Flutter to host platform communication. It is a code generator tool which aims to make this type-safe, easier and faster. With Pigeon, you just have to define the communication interface, and code generation takes care of everything else. In this post, we explore using Pigeon as an alternative to method channels and build the exact same functionality as with this tutorial. If you're curious, check it out and see how it compares!

Wrapping up

In this tutorial, we created a custom Flutter plugin with both Android and iOS implementations to call (fake) native functionality. We showed how to send and retrieve data from the host platforms, as well as throw errors and handle them.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email below.

Introduction

Sometimes, in an app, you want to perform an asynchronous operation and want to prevent the user from tapping/using the app while this operation is in progress. A simple example would be when you create a new item/to-do in your to-do list app. After tapping on "save" or an equivalent button, the save operation would very likely be asynchronous; it might involve storing data to local storage, performing a network request, or both. This is usually a very quick operation, taking less than a second. But sometimes it could take a bit longer. During that time, you don't want users accidentally tapping the save button twice, or changing inputs.

The simplest solution to this would be to display a loading overlay while the operation is in progress. To do this, we're going to need a widget! And in this tutorial, we will do just that.

Defining a loading overlay, or progress HUD

To make sure we're on the same page, this is what the end result will be like:

Just a circular progress indicator with a semi-opaque dark background, covering the current screen and preventing any user input. This is typically called an overlay or a heads-up-display (HUD).

Re-inventing the wheel

Before we get started, you might not be interested in writing a custom solution for this and would rather use a package for this. If this is the case, there are tens of packages to do just this. Just search for "loading overlay", "loader overlay", or "progress hud" on pub.dev. I haven't used any personally, but loader_overlay looks well maintained and has a nice API.

At the same time, this is almost trivial to implement, so I'd encourage you to just use your own solution (or copy this one!), and simply adjust it to work for you. Introducing an entirely new package to only do this might be a bit too much.

Building the overlay in 2 steps

In this tutorial, we will build the loading overlay widget in 3 steps, building on top of the example Flutter counter app. In the first step, we'll simply make the overlay work on the main screen of the app, without any re-usable code. In the second step, we'll extract our overlay code to a new widget that we can re-use anywhere.

If you're just here for the code, just go ahead and skip to step #2, or see the code in the repository here.

Step #1: Using a Stack

In this tutorial we'll be working with the example Flutter app. If you want to follow along, you can create this with the following command:

flutter create <app_name>

The loading overlay widget is actually very simple; it is just the current screen/view/widget, wrapped in a Stack, with the semi-opaque overlay and a centered circular progress indicator at the top of the stack.

@override
Widget build(BuildContext context) {
  return Stack(
    children: [
      Scaffold(
        ...
      ),
      const Opacity(
        opacity: 0.8,
        child: ModalBarrier(dismissible: false, color: Colors.black),
      ),
      const Center(
        child: CircularProgressIndicator(),
      ),
    ],
  );
}

With the change above, we now have a permanent loading overlay in front of the Scaffold. Let's introduce a new state variable, _isLoading, and only show the Opacity and Center widgets if its value is true.

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;
  bool _isLoading = false;

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        Scaffold(
          ...
        ),
        if (_isLoading)
          const Opacity(
            opacity: 0.8,
            child: ModalBarrier(dismissible: false, color: Colors.black),
          ),
        if (_isLoading)
          const Center(
            child: CircularProgressIndicator(),
          ),
      ],
    );
  }
}

Let's make a small tweak to the _incrementCounter method to test this. When the method is called, we set _isLoading to true, wait 3 seconds, and then set it back to false and increment the counter.

void _incrementCounter() async {
  setState(() {
    _isLoading = true;
  });
  await Future.delayed(const Duration(seconds: 3));
  setState(() {
    _counter++;
    _isLoading = false;
  });
}

And that's it! Easy, right? Now, this loading overlay code is mixed up with the other view logic, and if we have to push a new view on top of this one (Navigator.push(context, ...)), we'd need to implement this all over again.

Step #2: Extracting the LoadingOverlay widget

// loading_overlay.dart
class LoadingOverlay extends StatefulWidget {
  const LoadingOverlay({Key? key, required this.child}) : super(key: key);

  final Widget child;

  static _LoadingOverlayState of(BuildContext context) {
    return context.findAncestorStateOfType<_LoadingOverlayState>()!;
  }

  @override
  State<LoadingOverlay> createState() => _LoadingOverlayState();
}

class _LoadingOverlayState extends State<LoadingOverlay> {
  bool _isLoading = false;

  void show() {
    setState(() {
      _isLoading = true;
    });
  }

  void hide() {
    setState(() {
      _isLoading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        widget.child,
        if (_isLoading)
          const Opacity(
            opacity: 0.8,
            child: ModalBarrier(dismissible: false, color: Colors.black),
          ),
        if (_isLoading)
          const Center(
            child: CircularProgressIndicator(),
          ),
      ],
    );
  }
}

Notice the LoadingOverlay.of() function, which actually returns _LoadingOverlayState. In the state we expose two public functions, show and hide, which respectively show and hide the loading overlay.

The context.findAncestorStateOfType<T>() function returns any ancestor matching this state class, which can be null if there is no such ancestor. In this example, we can simply assume there will always be one and use !. Or, we could assert it is not null before returning it, throwing an error with a useful message.

Now, in order for _LoadingOverlayState to be an "ancestor" in our app's widget tree, we need to wrap our main view with the LoadingOverlay widget, by making the following changes:

// MyApp
@override
Widget build(BuildContext context) {
  return MaterialApp(
    title: 'Flutter Demo',
    theme: ThemeData(
      primarySwatch: Colors.blue,
    ),
    home: const LoadingOverlay(
      child: MyHomePage(title: 'Loading Overlay'),
    ),
  );
}

Note that we reverted the changes initially made in _MyHomePageState, as the Stack and overlay widgets have now been moved to the LoadingOverlay widget.

By simply passing MyHomePage as a child in LoadingOverlay, we can toggle the loading overlay at any point within the MyHomePage widget or any of its child widgets by calling LoadingOverlay.of(context).

To see our changes in action, let's change the _incrementCounter method again.

void _incrementCounter() async {
  LoadingOverlay.of(context).show();
  await Future.delayed(const Duration(seconds: 3));
  setState(() {
    _counter++;
  });
  LoadingOverlay.of(context).hide();
}

We now have a reusable LoadingOverlay widget that we can use any time we want to toggle such an overlay. No external packages needed, and all in a stateless widget of less than 50 lines of code.

Note that if we push a new view/widget on top of this one, the context there will not have a LoadingOverlay ancestor. So we'd need to wrap any newly pushed views with another LoadingOverlay.

Navigator.push(
    context,
    MaterialPageRoute(
        builder: (_) => const LoadingOverlay(child: NewPage())));

And that's it for the main part of this tutorial. Next, we will make some small improvements to the LoadingOverlay widget and make it more customizable. After that, in the following step, we will make the widget stateless rather than stateful. If you're not interested, feel free to skip ahead to the end of the post.

Improvement #1: Tweaks

In some cases, the operations you show the loading overlay for might take less than a second, or even half a second. In such cases, you might still want to show an overlay to block user interactions, but not the spinner/circular progress indicator.

We can make a small tweak to our LoadingOverlay widget to delay the circular progress indicator by a duration of our choice, by using a FutureBuilder.

class LoadingOverlay extends StatefulWidget {
  const LoadingOverlay({
    Key? key,
    required this.child,
    this.delay = const Duration(milliseconds: 500),
  }) : super(key: key);

  final Widget child;
  final Duration delay;

  ...
}

// _LoadingOverlayState
...
Center(
  child: FutureBuilder(
    future: Future.delayed(widget.delay),
    builder: (context, snapshot) {
      return snapshot.connectionState == ConnectionState.done
          ? const CircularProgressIndicator()
          : const SizedBox();
    },
  ),
),
...

The delay parameter is optional and defaults to 500 milliseconds.

Another change we can do is blur the background when we show the overlay. This can be done, of course, with another widget; BackdropFilter and ImageFilter.blur.

BackdropFilter(
  filter: ImageFilter.blur(sigmaX: 4.0, sigmaY: 4.0),
  child: const Opacity(
    opacity: 0.8,
    child: ModalBarrier(dismissible: false, color: Colors.black),
  ),
),

Another potential tweak would be to show something else rather than a CircularProgressIndicator. If you want this to vary depending on what you use it for, it could just be an additional Widget parameter that you can simply pass when you create a LoadingOverlay. Or it could even be optional and default to CircularProgressIndicator.

Improvement #2: Going stateless

I'm a big fan of stateless widgets, and try to avoid stateful widgets when I can. For this loading overlay widget, the only state we need to manage and change is a boolean value that determines whether the overlay is shown or not. Rather than with a stateful widget, we could achieve this by using a ValueNotifier and a ValueListenableBuilder.

class LoadingOverlayAlt extends StatelessWidget {
  LoadingOverlayAlt({Key? key, required this.child})
      : _isLoadingNotifier = ValueNotifier(false),
        super(key: key);

  final ValueNotifier<bool> _isLoadingNotifier;
  final Widget child;

  static LoadingOverlayAlt of(BuildContext context) {
    return context.findAncestorWidgetOfExactType<LoadingOverlayAlt>()!;
  }

  void show() {
    _isLoadingNotifier.value = true;
  }

  void hide() {
    _isLoadingNotifier.value = false;
  }

  @override
  Widget build(BuildContext context) {
    return ValueListenableBuilder<bool>(
      valueListenable: _isLoadingNotifier,
      child: child,
      builder: (context, isLoading, child) {
        return Stack(
          children: [
            child!,
            if (isLoading)
              const Opacity(
                opacity: 0.8,
                child: ModalBarrier(dismissible: false, color: Colors.black),
              ),
            if (isLoading)
              const Center(
                child: CircularProgressIndicator(),
              ),
          ],
        );
      },
    );
  }
}

We simply initialize the value notifier with a default false value, and expose methods that update its value. The ValueListenableBuilder will be rebuilt every time the notifier's value changes, so we end up with the same result as doing a setState with a stateful widget.

Note that we now use context.findAncestorWidgetOfExactType<T>() instead of context.findAncestorStateOfType<T>(), as the widget is now stateless, and the show and hide methods are part of this stateless widget.

Surprisingly (for me, at least!), switching from a stateful to a stateless widget does not really decrease the lines of code in the widget by a lot. And since we initialize the ValueNotifier in the constructor, the constructor can no longer be constant. So in the end, this might be less of an improvement but more of a matter of preference.

Wrapping up

In this tutorial, we created a loading overlay widget and implemented functionality to easily display and hide it, without external packages and less than 70 lines of code. Without the spinner delay and blur filter tweaks, this is even less, at around 50 lines.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email below.

If you've been using Flutter for a while, you already know theming with Flutter is very easy, and switching between light and dark mode is available out-of-the-box, something which can be a pain to implement with other frameworks if you don't build your app with this in mind.

But what if light and dark mode is not enough for you? What if you want to implement a "true black", "true dark", "lights out" or "OLED dark mode", or whatever the proper name for this extra mode is...?

This is not trivial to do, but if you really wanted, you could configure ThemeData to have darker colors and use the "true" black color (Color(0xFF000000), or Colors.black in the material library). Theming in Flutter is easy, after all!

But there's a simpler, even easier way to implement this mode. Enter flex_color_scheme.

The flex_color_scheme package

flex_color_scheme is a package that allows you to easily build color scheme based Flutter themes. It has lots of beautiful built-in themes available, but you can also easily create your own by specifying a primary color and an optional secondary color. With this package, enabling "true black" mode is as simple as setting a value to true.

Installing the package

Run this in your terminal to install the package:

flutter pub add flex_color_scheme

Or just add the dependency in pubspec.yaml:

dependencies:
  flex_color_scheme: ^4.1.1

As of the time of writing of this post, the current version is 4.1.1.

Using the package

Now, let's set up a theme with flex_color_scheme. For this tutorial, I'll be using the default Flutter counter starter app.

Let's apply a new theme by updating the main build method:

@override
Widget build(BuildContext context) {
  return MaterialApp(
    title: 'Theming Tutorial',
    theme: FlexThemeData.light(scheme: FlexScheme.hippieBlue),
    darkTheme: FlexThemeData.dark(scheme: FlexScheme.hippieBlue),
    themeMode: ThemeMode.dark,
    home: const MyHomePage(),
  );
}

I'm a fan of the built-in Hippie Blue scheme, so I'll be using that one. FlexThemeData provides convenience extensions to return a ThemeData object given a scheme or colors.

You can specify your own colors which will override the scheme colors by using the FlexSchemeColor#of constructor and specifying a primary and an optional secondary color. The default scheme is FlexScheme.material.

FlexThemeData.light(colors: FlexSchemeColor.from(primary: Colors.blue, secondary: Colors.green))

Below is what our app looks like right now. Strangely, there is no blue in "hippie blue" dark mode! This is because, though the app bar is actually blue (primary color) in light mode, it's black in dark mode, as per the Material guidelines.

True black mode

Switching from dark mode to true black mode is easy. Simply set the darkIsTrueBlack in your flex theme data to true.

darkTheme: FlexThemeData.dark(
  scheme: FlexScheme.hippieBlue,
  darkIsTrueBlack: true,
),

Save your change, watch your app hot-reload, and... ta-da! Dark mode is now true black. On OLED screens, this can also preserve battery.

What does this flag actually do? It sets the scaffold background to black, as well as making other surfaces 8% darker.

Note: the darkIsTrueBlack flag is only available in FlexThemeData#dark. There is a lightIsTrueWhite equivalent in FlexThemeData#light, but is not as useful. Similarly to the dark flag, it sets the scaffold background to white, and other surfaces 8% lighter.

Supporting both dark and true black mode

So far, we've shown how to easily set up "true black" mode in our Flutter app. If that's all you're here for, feel free to skip this and jump to the conclusion!

But what if you'd like to support both "regular" dark mode, as well as "true black"? If your app has plenty of users, surely there will be preferences for both. Some users might find "true black" too dark, while others will want to take advantage of their device's OLED screen and use true black.

To support theme changing in the app, it's time to manage some state!

Switching between light and dark theme mode

Before adding this third theme option, we should note that there is an additional theme mode: ThemeMode.system. This will use the user's system theme: it may be light or dark. To get started, let's implement the option to switch between these 3 theme modes (light, dark, and system) in our app.

To implement this, I will use a ValueNotifier, along with a ValueListenableBuilder, just to keep things simple. You could instead do this with e.g. a ThemeController with the ChangeNotifier mixin, which could additionally store the user's selection to local storage (e.g. shared_preferences). Or, you could use a state management package of your choice. But this is outside the scope of this tutorial!

This is what our root widget looks like now:

void main() {
  // This could be loaded from storage e.g. with `shared_preferences`
  const themeMode = ThemeMode.system;
  runApp(MyApp(theme: themeMode));
}

class MyApp extends StatelessWidget {
  MyApp({Key? key, required ThemeMode theme})
      : _themeNotifier = ValueNotifier(theme),
        super(key: key);

  final ValueNotifier<ThemeMode> _themeNotifier;

  @override
  Widget build(BuildContext context) {
    return ValueListenableBuilder<ThemeMode>(
      valueListenable: _themeNotifier,
      child: MyHomePage(onThemeUpdate: onThemeUpdate),
      builder: (context, theme, child) {
        return MaterialApp(
          title: 'Theming Tutorial',
          theme: FlexThemeData.light(scheme: FlexScheme.hippieBlue),
          darkTheme: FlexThemeData.dark(
            scheme: FlexScheme.hippieBlue,
            darkIsTrueBlack: true,
          ),
          themeMode: theme,
          home: child,
        );
      },
    );
  }

  void onThemeUpdate(ThemeMode themeMode) {
    _themeNotifier.value = themeMode;
  }
}

We wrapped our MaterialApp with a ValueListenableBuilder. The value listenable of this builder is a ValueNotifier, initialized with the theme mode we passed when creating the root widget.

Every time we want to change the theme, we will change the value of _themeNotifier, which will trigger the builder and rebuild our MaterialApp widget.

Notice that we're now passing the function that will change the notifier's value down to the home page widget. Whenever we want to change the theme, we can use this function.

To change the theme, let's add a new action in the app bar.

return Scaffold(
  appBar: AppBar(
    title: Text(widget.title),
    actions: [
      IconButton(
        onPressed: _selectTheme,
        icon: const Icon(Icons.brightness_4_outlined),
      )
    ],
  ),
  ...
);

Future<void> _selectTheme() async {
  final theme = await _showThemePicker();
  if (theme != null) {
    widget.onThemeUpdate(theme);
  }
}

Future<ThemeMode?> _showThemePicker() {
  return showModalBottomSheet<ThemeMode>(
    context: context,
    builder: (context) {
      return SafeArea(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            ListTile(
              title: const Text('Light'),
              leading: const Icon(Icons.brightness_7_outlined),
              onTap: () {
                Navigator.pop(context, ThemeMode.light);
              },
            ),
            ListTile(
              title: const Text('Dark'),
              leading: const Icon(Icons.brightness_2_outlined),
              onTap: () {
                Navigator.pop(context, ThemeMode.dark);
              },
            ),
            ListTile(
              title: const Text('System'),
              leading: const Icon(Icons.settings_outlined),
              onTap: () {
                Navigator.pop(context, ThemeMode.system);
              },
            ),
          ],
        ),
      );
    },
  );
}

Lots of duplicate code, but I'll leave the refactoring up to you if you plan to use the same approach to theme changing!

When we tap on the "brightness" icon in the app bar, we are shown a modal bottom sheet with our 3 choices. By tapping on any of the themes, we call our function which updates the value of the ValueNotifier. This causes the app to rebuild, and we can see the theme changing.

Note 1: showModalBottomSheet can always also return null, for example when the user taps outside the modal or presses the back button. If it does, we don't do anything.

Note 2: We use SafeArea to wrap the body of the modal. This avoids intrusions by the operating system. For example, since this is a bottom sheet, a phone's notch could be hiding its contents, but wrapping the bottom sheet in a SafeArea widget will give it sufficient padding to avoid this (but only if there is a notch!).

Switching between light, dark, and true black mode

Now, to support a fourth option, true black mode, we can't keep using ThemeMode. Let's introduce a new ThemeOption enum.

enum ThemeOption { light, dark, system, trueBlack }

extension ThemeOptionUtils on ThemeOption {
  ThemeMode get themeMode {
    switch (this) {
      case ThemeOption.light:
        return ThemeMode.light;
      case ThemeOption.dark:
      case ThemeOption.trueBlack:
        return ThemeMode.dark;
      case ThemeOption.system:
        return ThemeMode.system;
    }
  }
}

ThemeOption.trueBlack will still map to ThemeMode.dark, but we'll get to this in a bit.

Let's also extract all the themes to a separate class, just to keep things simpler.

// app_theme.dart
class AppTheme {
  static const _scheme = FlexScheme.hippieBlue;

  static final light = FlexThemeData.light(scheme: _scheme);
  static final dark = FlexThemeData.dark(scheme: _scheme);
  static final trueBlack =
      FlexThemeData.dark(scheme: _scheme, darkIsTrueBlack: true);
}

Now, all that's left is to simply switch our value notifier from ThemeMode to ThemeOption. This is quite an easy change so I won't share the whole code as it's identical to the snippets share previously, but you can check the source code out on GitHub.

The only additional changes were the extra "true black" option in the theme picker, as well as the way the theme in MaterialApp is determined.

// _MyHomePageState#_showThemePicker
...
ListTile(
  title: const Text('True black'),
  leading: const Icon(Icons.brightness_1_outlined),
  onTap: () {
    Navigator.pop(context, ThemeOption.trueBlack);
  },
),
...

// MyApp
@override
Widget build(BuildContext context) {
  return ValueListenableBuilder<ThemeOption>(
    valueListenable: _themeNotifier,
    child: MyHomePage(onThemeUpdate: onThemeUpdate),
    builder: (context, themeOption, child) {
      return MaterialApp(
        title: 'Theming Tutorial',
        theme: AppTheme.light,
        darkTheme: themeOption == ThemeOption.trueBlack
            ? AppTheme.trueBlack
            : AppTheme.dark,
        themeMode: themeOption.themeMode,
        home: child,
      );
    },
  );
}

Very similar to what we had before, except now that the value listenable's value is of type ThemeOption, we need to map the option to ThemeMode to pass it as a MaterialApp argument. And the main change, to support true black mode, is to check whether the option is trueBlack, and if it is, use the appropriate darkTheme. And that's it! We can now choose between 4 different options.

Wrapping up

In this tutorial, we showed how to easily enable true black mode in a Flutter app with the flex_color_scheme package.

We also showed how to support both dark and true black modes (in addition to light mode, of course!) in the same app.

You can find the full source code here.

I am typically against introducing a new dependency just to introduce a small new feature. However, there is much more to flex_color_scheme than true black mode! I encourage you to take a look at the example, and dig deeper into the package.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email below.

In the previous part of this tutorial series, we went over what Supabase is, and started building a simple notes app with Supabase. So far, we got authentication working.

In this part, we will go over Supabase's Database offering. We will create a table to hold all the users' notes, and display them in the app, as well as let users create, edit and delete notes.

Code snippets for both widgets and services will be shared along the tutorial, but you can find the full source code here.

Postgres and Supabase

Supabase is built on top of Postgres, a relational database. Some basic knowledge of relational databases and SQL would help, but is not required, as Supabase makes it easy to view the database, its tables, and run queries through its admin interface.

We'll be making use of the SQL editor on Supabase's admin interface to run the SQL queries to create the tables we need.

Supabase also provides a nice "table editor" which lets you create tables without needing to write SQL. However, for the tutorial, it's actually easier to share SQL queries to run directly from the SQL editor. If you'll be working with Supabase, I'd recommend getting familiar with SQL anyway.

With the Supabase client, we can access the database with two ways:

• RESTful API - This uses PostgREST behind the scenes, which is a thin API layer on top of Postgres, which allows you to write your queries straight from the client side of the code (our Flutter app). This is what we'll be using in this tutorial.
• Realtime API - You can also listen to database changes over WebSockets with Supabase's Realtime server. We won't be using this in this tutorial.

Tables

A table is a collection of structured data that lives in the Postgres database. When using Supabase's authentication, when a user signs up, the user data is stored as a row in a users table. Each row has several columns, containing information such as email, creation date, etc. Note that the users table managed by Supabase is off-limits and cannot be accessed from the client. If we want to store additional user data, we'd need to create a new, separate table.

A table column has a type restriction: it can be a number, text, or something else. Once we create a table, this is not straight-foward to change, so we should think of our data model carefully first. But we can always add more columns later!

Each table has a column that is a primary key, a unique identifier which we can use to update or fetch specific rows from the table.

There are lots of useful resources on SQL, Postgres and relational databases out there if you're not familiar/comfortable with the concepts, but this tutorial should be easy to follow either way.

Data types

Postgres supports several data types, but we'll mostly be using integer and varchar/text. Once we create a table with columns of these data types, this schema is enforced and we cannot, for example, insert a string value in an integer column.

Another notable data type is Postgres' jsonb, which allows you to store JSON strings containing multiple fields of your data in a column. This is very flexible and useful if we're not sure how our data is going to look like in the beginning. You could start with a jsonb column and eventually move to something more structured. However, while it's more flexible, there's also no enforced schema on the data stored inside the column, so if you know what data you'll be storing in advance, it's recommended to just use multiple columns for each field.

One good use case of the jsonb data type would be if you're migrating from a non-relational database (e.g. Firebase) to Supabase. You could map all your documents to a row containing an ID (the primary key), and a jsonb column containing all the document data in JSON.

Part 2: Database

Creating our first database

The first table we'll be needing for this note app, is a notes table! For starters, our notes will have a title, optional content, and creation and modification timestamps. Since we're building a Flutter app, let's start with the Dart model first.

// models/note.dart
class Note {
  final int id;
  final String title;
  final String? content;
  final DateTime createTime;
  final DateTime modifyTime;

  Note(this.id, this.title, this.content, this.createTime, this.modifyTime);
}

We also need an id field so we can edit and delete notes.

Now that we have the model, let's create a table in Supabase. From the admin interface, select your project, and then the SQL editor tab. On the top left you should see a "New query" option. We can pass raw SQL queries in this editor and run them against our database. We'll do this for creating tables, and can also do this when having to quickly check out some data, or run some migrations.

Let's run the following query to create the notes table.

create table notes (
  id bigserial primary key,
  title text not null,
  content text,
  create_time timestamptz default now() not null,
  modify_time timestamptz default now() not null,
  user_id uuid references auth.users (id) default auth.uid() not null
);

Our first table is ready! In the Database tab, you can now see the notes table in the public schema.

The id field is a bigserial, which is a bigint that is generated automatically if left blank, and the values are incremented automatically. The timestamp fields default to the current time.

Every field is required except content, which is optional. The user_id field is not part of our model, but we need this on the database side as we'll need this field so we can return the correct data when fetching notes for a specific user.

The user_id column has a foreign key constraint and it references auth.users (id). This means each note created needs to have a user_id field that matches an id field in the users table in the auth schema in our database. If the user ID provided does not match an existing user, we won't be able to insert this note to our database.

The user_id value defaults to auth.uid(), which is a special function in Postgres, provided by Supabase, that returns the current user by extracting it from the JSON web token (discussed in the previous part about authentication).

The auth schema is used by Supabase for authentication. All tables we create for the notes app will be created in a separate public schema.

Note that we could omit the (id) in the SQL query above, as if there is no column specified as reference the primary key of that table is used, which in our case is id.

Fetching data

Now we want to fetch the notes of the currently signed in user to display in the app. We can do this directly from the Supabase client, which uses PostgREST behind the scenes.

Let's create a NotesService which will use the Supabase client to fetch the notes, and map them to our Note model.

Here is our updated Services inherited widget which will also now contain the NotesService so we can retrieve it from any widgets that need it.

class Services extends InheritedWidget {
  final AuthService authService;
  final NotesService notesService;

  Services._({
    required this.authService,
    required this.notesService,
    required Widget child,
  }) : super(child: child);

  factory Services({required Widget child}) {
    final client = SupabaseClient(supabaseUrl, supabaseKey);
    final authService = AuthService(client.auth);
    final notesService = NotesService(client);
    return Services._(
      authService: authService,
      notesService: notesService,
      child: child,
    );
  }

  @override
  bool updateShouldNotify(InheritedWidget oldWidget) {
    return false;
  }

  static Services of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<Services>()!;
  }
}

And here is the NotesService:

class NotesService {
  static const notes = 'notes';

  final SupabaseClient _client;

  NotesService(this._client);

  Future<List<Note>> getNotes() async {
    final response = await _client.from(notes).select().execute();
    if (response.error == null) {
      final results = response.data as List<dynamic>;
      return results.map((e) => toNote(e)).toList();
    }
    log('Error fetching notes: ${response.error!.message}');
    return [];
  }

  Note toNote(Map<String, dynamic> result) {
    return Note(
      result['id'],
      result['title'],
      result['content'],
      DateTime.parse(result['create_time']),
      DateTime.parse(result['modify_time']),
    );
  }
}

By using select(), we return all columns of the notes table in the results. Since we actually don't need the user_id field, we can select only the fields we actually need.

Future<List<Note>> getNotes() async {
  final response = await _client
      .from(notes)
      .select('id, title, content, create_time, modify_time')
      .execute();
  if (response.error == null) {
    final results = response.data as List<dynamic>;
    return results.map((e) => toNote(e)).toList();
  }
  log('Error fetching notes: ${response.error!.message}');
  return [];
}

This query selects all notes, for all users. It would make sense for our query to have a where clause with the condition that the user_id field of the note matches the one of the currently signed in user. However, this query is run from the client, NOT the server. Which means, potentially, one could accidentally (or not) fetch notes of other users. This is one of the drawbacks of not having a back-end server, as all the data is available to all users by default. This is a huge issue, but the solution is actually pretty simple. Enter Policies.

Policies

Policies are a a PostgreSQL feature that allows you to define row level security policies for tables. This means, that even with the ability to run any query for a table, no rows will be visible or updatable unless the policy allows it.

To understand this better, let's create a policy:

create policy "Users can only view their own notes"
on notes
for select
using (auth.uid() = user_id);

This is a SQL query, which you can run from Supabase's admin interface. Now let's dig into the query. We're creating a policy with a useful description, on the notes table. This policy is for select statements. The condition for this policy, is that auth.uid() is the same as the user_id field of a note. As mentioned before, auth.uid() always returns the currently signed in user's ID.

This means, that even if we no longer filter on the user ID to fetch the notes for a user, only the notes of the current user will be returned. It's basically an automatic where clause! That's quite powerful, since if you set up your policies right, you don't have to worry about accidentally exposing data to the wrong users, or users updating or deleting data that is not their own.

Now, we've restricted users from selecting other users' notes, but what about other commands? There is still insert, update, and delete. But we can also use all for a policy, which will apply it to all commands.

create policy "Users can only view and update their own notes"
on notes
for all
using (auth.uid() = user_id)

That should do it! With this policy, we no longer need the previous one, as it's already covered by all.

Displaying notes

Now that our getNotes() function returns all notes for the current user, let's update our NotesPage widget to display them.

Just for testing, if you're curious if this is working as intended, we can add a note manually through a SQL query. Feel free to skip this part though, since next up we'll add functionality to actually create new notes.

To create a note manually, let's get our user's ID from the database with the following query.

select id from auth.users;

And let's insert a note for this user.

insert into notes values (1, 'My note', 'Note content', now(), now(), '2cb4a80a-3c75-4d80-86b0-d76a094cf915')

You could also add a note without needing SQL through the table editor.

Here is the updated NotesPage widget:

class NotesPage extends StatefulWidget {
  const NotesPage();

  @override
  _NotesPageState createState() => _NotesPageState();
}

class _NotesPageState extends State<NotesPage> {
  Future<void> _signOut() async {
    final success = await Services.of(context).authService.signOut();
    if (success) {
      Navigator.pushReplacement(
          context, MaterialPageRoute(builder: (_) => HomePage()));
    } else {
      ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('There was an issue logging out.')));
    }
  }

  Future<void> _addNote() async {
    // TODO
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Supanotes'),
        actions: [_logOutButton(context)],
      ),
      body: ListView(
        children: [
          FutureBuilder<List<Note>>(
            future: Services.of(context).notesService.getNotes(),
            builder: (context, snapshot) {
              final notes = (snapshot.data ?? [])
                ..sort((x, y) =>
                    y.modifyTime.difference(x.modifyTime).inMilliseconds);
              return Column(
                children: notes.map(_toNoteWidget).toList(),
              );
            },
          ),
        ],
      ),
      floatingActionButton: FloatingActionButton.extended(
        label: Text('Add note'),
        icon: Icon(Icons.add),
        onPressed: _addNote,
      ),
    );
  }

  Widget _logOutButton(BuildContext context) {
    return IconButton(
      onPressed: _signOut,
      icon: Icon(Icons.logout),
    );
  }

  Widget _toNoteWidget(Note note) {
    return ListTile(
      title: Text(note.title),
      subtitle: Text(note.content ?? ''),
    );
  }
}

We use a FutureBuilder to load the notes from the NotesService, and display the notes in a column. The notes are sorted by modify time (latest one first). We also changed the sign out button to be an action in the AppBar instead of a button in the page.

This was previously a stateless widget, but has been converted to a stateful widget for convenience; we will use setState after creating or changing notes to refresh the page.

If your notes page looks like in the screenshot below, you did everything correctly! Next, we're going to implement the logic to add a new note, which will be done through the FAB button that currently doesn't do anything.

Creating notes

Now, let's create the NotePage, where we'll be able to create a new note.

class NotePage extends StatefulWidget {
  const NotePage();

  @override
  _NotePageState createState() => _NotePageState();
}

class _NotePageState extends State<NotePage> {
  final _titleController = TextEditingController();
  final _contentController = TextEditingController();

  Future<void> _saveNote_() async {
    if (_titleController.text.isEmpty) {
      _showSnackBar('Title cannot be empty.');
    }
    final note = await Services.of(context)
        .notesService
        .createNote(_titleController.text, _contentController.text);
    if (note != null) {
      Navigator.pop(context, note);
    } else {
      _showSnackBar('Something went wrong.');
    }
  }

  void _showSnackBar(String text) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(text)));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('New note'),
      ),
      body: Column(
        children: <Widget>[
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: TextField(
              controller: _titleController,
              decoration: InputDecoration(hintText: 'Title'),
            ),
          ),
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: TextField(
              controller: _contentController,
              decoration: InputDecoration(hintText: 'Content'),
            ),
          ),
        ],
      ),
      floatingActionButton: FloatingActionButton.extended(
        onPressed: _saveNote,
        icon: Icon(Icons.save),
        label: Text('Save'),
      ),
    );
  }

  @override
  void dispose() {
    _titleController.dispose();
    _contentController.dispose();
    super.dispose();
  }
}

This page widget is simple. Two text fields, one for the title and one for the content. Pressing the FAB button saves the note to the database. When saving, we check that the title is not empty, and show a simple snackbar otherwise.

One thing to note is that since creating the note might take a while, we don't want the users to accidentally tab the "Add note" button twice and create duplicate notes. So we should introduce some mechanism to disable the button until we get the result from the notes service, but that's outside of the scope of this tutorial.

Here is the createNote function in NotesService:

// NotesService
Future<Note?> createNote(String title, String? content) async {
  final response = await _client
      .from(notes)
      .insert({'title': title, 'content': content}).execute();
  if (response.error == null) {
    final results = response.data as List<dynamic>;
    return toNote(results[0]);
  }
  log('Error creating note: ${response.error!.message}');
  return null;
}

Since most values are generated by default, with the exception of the title and content, all we need to pass to our insert query is these two fields. The response contains a list of all inserted records, which in our case is just the one note, which we return in this function, if there were no issues.

Now let's go back to the NotesPage and implement the _addNote_ function.

// NotesPage
Future<void> _addNote() async {
  final note = await Navigator.push<Note?>(
    context,
    MaterialPageRoute(builder: (context) => NotePage()),
  );
  if (note != null) {
    setState(() {});
  }
}

If a note is returned from the NotePage, we use setState to force the widget to reload, fetching all notes from the database again. We could optimize this part by maybe saving the notes in the widget's state, and rather than loading all notes from the database again, simply appending the new note. But let's keep it this way for simplicity!

Editing notes

In order to edit notes, let's change the NotePage a bit to support both creating and editing notes. We can pass an optional note to this widget, and if present, we can display its contents in the text fields, and call a function to edit the note rather than create a new one. Here's the updated constructor for NotePage widget:

class NotePage extends StatefulWidget {
  final Note? note;

  const NotePage({this.note});

  @override
  _NotePageState createState() => _NotePageState();
}

In the state widget, we override the initState method to populate the text fields with the note title and content if a note was passed in the constructor. The _saveNote function is updated to either create a new note, or update it. We also set the AppBar title accordingly.

// _NotePageState
@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: Text(widget.note != null ? 'Edit note' : 'New note'),
    ),
    ...
  );
}

@override
void initState() {
  super.initState();
  if (widget.note != null) {
    _titleController.text = widget.note!.title;
    _contentController.text = widget.note!.content ?? '';
  }
}

Future<void> _saveNote() async {
  final title = _titleController.text;
  final content = _contentController.text;
  if (title.isEmpty) {
    _showSnackBar('Title cannot be empty.');
    return;
  }
  final note = await _createOrUpdateNote(title, content);
  if (note != null) {
    Navigator.pop(context, note);
  } else {
    _showSnackBar('Something went wrong.');
  }
}

Future<Note?> _createOrUpdateNote(String title, String content) {
  final notesService = Services.of(context).notesService;
  if (widget.note != null) {
    return notesService.updateNote(widget.note!.id, title, content);
  } else {
    return notesService.createNote(title, content);
  }
}

And here is the service function to update the note:

// NotesService
Future<Note?> updateNote(int id, String title, String? content) async {
  final response = await _client
      .from(notes)
      .update({'title': title, 'content': content, 'modify_time': 'now()'})
      .eq('id', id)
      .execute();
  if (response.error == null) {
    final results = response.data as List<dynamic>;
    return toNote(results[0]);
  }
  log('Error editing note: ${response.error!.message}');
  return null;
}

The above function updates the title, content, and modify time fields for the note with the above ID. Because of the policy we set up before, the update will only happen if the note with the given ID was created by the current user. Passing now() in the modify time field will set the current time.

Now, let's make it so that if you tap on any note, the edit page will show up:

// NotesPage
Future<void> _editNote(Note note) async {
  final updatedNote = await Navigator.push<Note?>(
    context,
    MaterialPageRoute(builder: (context) => NotePage(note: note)),
  );
  if (updatedNote != null) {
    setState(() {});
  }
}

Widget _toNoteWidget(Note note) {
  return ListTile(
    title: Text(note.title),
    subtitle: Text(note.content ?? ''),
    onTap: () => _editNote(note),
  );
}

Very similarly to the creating notes implementation, if the NotePage is popped with a note, it means the note was updated, so we can rebuild the widget to display the changes.

When tapping on a note, you should now see this:

Deleting notes

So far, we can create new notes, and edit them. The next, and final step for this tutorial, is to delete them!

We'll wrap the note widgets in a Dismissible and call the delete function in the confirmDismiss function. If deletion is successful, we call setState on dismissal to rebuild the widget.

// NotesPage
Widget _toNoteWidget(Note note) {
  return Dismissible(
    key: ValueKey(note.id),
    direction: DismissDirection.endToStart,
    confirmDismiss: (_) =>
        Services.of(context).notesService.deleteNote(note.id),
    onDismissed: (_) => setState(() {}),
    background: Container(
      padding: const EdgeInsets.all(16.0),
      color: Theme.of(context).errorColor,
      alignment: Alignment.centerRight,
      child: Icon(Icons.delete),
    ),
    child: ListTile(
      title: Text(note.title),
      subtitle: Text(note.content ?? ''),
      onTap: () => _editNote(note),
    ),
  );
}

// NotesService
Future<bool> deleteNote(int id) async {
  final response = await _client.from(notes).delete().eq('id', id).execute();
  if (response.error == null) {
    return true;
  }
  log('Error deleting note: ${response.error!.message}');
  return false;
}

And that's it!

Wrapping up

In this part of the tutorial, we showed how to create a table in Supabase, and how to create, read, update and delete records from our Flutter app using the Supabase client. We also discussed policies, a powerful feature by Postgres that makes sure data from the database is secured and cannot be accessed by the wrong users through the Supabase client.

Next up, we'll dive into Supabase's Storage offering. We'll make use of this feature by implementing the functionality to attach files to notes. To do this, we will also introduce a simple one-to-many relationship between the notes table and a new attachments table.

If you'd like to be notified when the next part of this series is published, and for any future tutorials, please sign up with your email below.

In this tutorial series, we will build a simple notes app, powered by Supabase. Supabase is a product similar to Firebase, which provides services such as authentication and a database, as well as a client which allows you to authenticate and query the database directly from your Flutter app. By combining Flutter with Supabase, you could build production-ready* apps without having to write or maintain a back-end server.

This series will consist of three parts, each one going over a specific service by Supabase. First, we'll start with Authentication, which will allow users to sign in the app. Then, we'll move on to the Database, where we'll create a simple schema for our notes app, and allow users to create and view their notes. Last, we'll check out Storage, which we'll make use of by allowing users to attach files to their notes.

This tutorial assumes you already have some experience with Flutter (if not, go here to get started!). Code snippets will be shared as we go along, but you can also check out the full source code at the repository linked at the end of this post.

* Note that Supabase is still in public beta phase. However, it's still an exciting service, and now is a good time to experiment with it!

What is Supabase?

Supabase calls itself an open source alternative to Firebase. It offers several things: a relational database which you can access directly from the client, built-in user authentication so you can manage users and permissions, as well as storage so you can store large files. Functions are also in the works, which will allow you to run your own code without needing a server.

Why not Firebase?

While Supabase is considered an alternative, it's also very different. As always, there is no one right choice, and the best service to use depends on your use case. But Supabase has two stand-out features that Firebase does not have, which a lot of developers might prefer.

• Relational database: Supabase is built on top of PostgreSQL, a powerful relational database that has been around for over 30 years. Firebase's Firestore and Realtime Database offerings are non-relational, so the choice between Supabase and Firebase might be as easy as relational vs non-relational, though there's more to it than that. Firebase is not open source, and has not been around as long as Postgres.
• It's all open source: Supabase is built on top of other popular open-source packages, such as PostgREST for accessing your database directly from the client, and GoTrue for user authentication. All that, along with a nice admin interface so you can manage everything. If you wanted, you could host and manage these services on your own. If PostgREST does not fit your use case, you could host a server that will communicate with your Postgres database directly. And if you ever decide that Supabase is not for you, you could always migrate all your data somewhere else. At the end of the day, it's all in a Postgres database.

Getting Started

Setting up Supabase

Getting started with Supabase is simple, so we won't go into much detail about its setup. Just head to the Supabase website and create a project.

You can spend some time to get familiar with the admin interface, but we won't be needing it a lot for this first part. All we will need is your Supabase project's URL and API key, which you can find your project's API settings.

In auth settings, you can also have some options to change your site URL, which is included in emails sent by Supabase when a user signs up (which you can disable), as well as customize the email templates sent for password resets, magic links(!), and invitations.

You can also set up and run Supabase locally for local development by following the guide here.

Creating a new Flutter app

Now that we've got Supabase all set up, it's time to start building the app. Let's create a new Flutter app. Since this is a notes app built on Supabase, I'll be calling it Supanotes!

flutter create supanotes

Note: if null safety was not already enabled by default, you can do this by running the command below.

cd supanotes
dart migrate --apply-changes

We'll be making use of Dart's null safety features, but it for whatever reason you don't want to enable it for your app, you should still be able to follow along.

Part 1: Authentication

Now, let's make a very simple login page. Here is the UI code so far:

class SupanotesApp extends StatelessWidget {
  static const supabaseGreen = Color.fromRGBO(101, 217, 165, 1.0);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Supanotes',
      theme: ThemeData(
        brightness: Brightness.dark,
        primarySwatch: toMaterialColor(supabaseGreen),
      ),
      home: HomePage(),
    );
  }
}

class HomePage extends StatefulWidget {
  const HomePage();

  @override
  _HomePageState createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();

  void _signUp() {
    // Sign up logic will go here
  }

  void _signIn() {
    // Sign in logic will go here
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).primaryColor,
        title: Text('Supanotes'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: TextField(
                controller: _emailController,
                keyboardType: TextInputType.emailAddress,
                decoration: InputDecoration(hintText: 'Email'),
              ),
            ),
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: TextField(
                controller: _passwordController_,
                obscureText: true,
                decoration: InputDecoration(hintText: 'Password'),
              ),
            ),
            ElevatedButton.icon(
              onPressed: _signIn,
              icon: Icon(Icons.login),
              label: Text('Sign in'),
            ),
            ElevatedButton.icon(
              onPressed: _signUp,
              icon: Icon(Icons.app_registration),
              label: Text('Sign up'),
            ),
          ],
        ),
      ),
    );
  }

  @override
  void dispose() {
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }
}

The toMaterialColor function is taken from this post here (thanks Filip!).

Adding the Supabase package

Let's implement the logic for sign in and sign up. First, we add the supabase package to our app.

flutter pub add supabase

Next, we'll create an AuthService that will handle anything auth related. In order to pass this service to any widget that needs it, we'll create an InheritedWidget that will hold all services we might need.

class Services extends InheritedWidget {
  final AuthService authService;

  Services._({
    required this.authService,
    required Widget child,
  }) : super(child: child);

  factory Services({required Widget child}) {
    final client = SupabaseClient(supabaseUrl, supabaseUrl);
    final authService = AuthService(client.auth);
    return Services._(authService: authService, child: child);
  }

  @override
  bool updateShouldNotify(InheritedWidget oldWidget) {
    return false;
  }

  static Services of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<Services>()!;
  }
}

In this InheritedWidget, we initialize the Supabase client, and create the AuthService. To initialise the SupabaseClient, simply pass the URL and API keys from the API settings on the Supabase admin interface.

The GoTrue client

Supabase uses GoTrue for authentication. client.auth returns the GoTrue client, which is all the AuthService will need.

class AuthService {
  final GoTrueClient _client;

  AuthService(this._client);

  Future<bool> signUp(String email, String password) {
    // sign up logic goes here
  }

  Future<bool> signIn(String email, String password) {
    // sign in logic goes here
  }

  Future<bool> signOut() {
    // sign out logic goes here
  }
}

All three functions will return true if the response was successful, otherwise false.

Let's start with the signUp function:

// AuthService
Future<bool> signUp(String email, String password) async {
  final response = await _client.signUp(email, password);
  if (response.error == null) {
    log('Sign up was successful for user ID: ${response.user!.id}');
    return true;
  }
  log('Sign up error: ${response.error!.message}');
  return false;
}

This function will accept the email and password which we will pass from the text field widgets, and create a user. The client will return a GotrueSessionResponse, which will contain an error if something goes wrong, or a User and Session object.

We don't currently need to do anything with the User and Session objects, though it contains useful information we could make use of, such as the user's ID, last sign in date, and email confirmation date. However, these will always be accessible through GoTrueClient#currentUser and GoTrueClient#currentSession so we can grab them from the client when we need them.

Below are also the signIn and signOut functions, which are very similar to signUp.

// AuthService
Future<bool> signIn(String email, String password) async {
  final response = await _client.signIn(email: email, password: password);
  if (response.error == null) {
    log('Sign in was successful for user ID: ${response.user!.id}');
    return true;
  }
  log('Sign in error: ${response.error!.message}');
  return false;
}

Future<bool> signOut() async {
  final response = await _client.signOut();
  if (response.error == null) {
    return true;
  }
  log('Log out error: ${response.error!.message}');
  return false;
}

Now, let's call these AuthService functions in HomePage. Since the service is part of the Services InheritedWidget, we can freely access it through Services.of(context).authService. But to do that, we should first wrap MaterialApp with the Services widget. Our top level app widget should look like this:

class SupanotesApp extends StatelessWidget {
  static const supabaseGreen = Color.fromRGBO(101, 217, 165, 1.0);

  const SupanotesApp();

  @override
  Widget build(BuildContext context) {
    return Services(
      child: MaterialApp(
        title: 'Supanotes',
        theme: ThemeData(
          brightness: Brightness.dark,
          primarySwatch: toMaterialColor(supabaseGreen),
        ),
        home: HomePage(),
      ),
    );
  }
}

Now, we can call AuthService functions from any widget. Let's start with the logic for sign up.

// HomePage
void _signUp() async {
  final success = await Services.of(context)
      .authService
      .signUp(_emailController.text, _passwordController.text);
  if (success) {
    await Navigator.pushReplacement(
        context, MaterialPageRoute(builder: (_) => NotesPage()));
  } else {
    ScaffoldMessenger.of(context)
        .showSnackBar(SnackBar(content: Text('Something went wrong.')));
  }
}

If the response was successful, we navigate to a new page, the NotesPage, where we will display the user's notes. We call pushReplacement rather than push, since we don't want the user pressing back and ending up in the home page by mistake.

If the response fails, we just show a generic snack bar. This could display more useful information, based on the actual error.

The function for signing in is pretty much the same. We can reuse some of the code for both functions, and our code now looks like this:

// HomePage
void _signUp() async {
  final success = await Services.of(context)
      .authService
      .signUp(_emailController.text, _passwordController.text);
  await _handleResponse(success);
}

void _signIn() async {
  final success = await Services.of(context)
      .authService
      .signIn(_emailController.text, _passwordController.text);
  await _handleResponse(success);
}

Future<void> _handleResponse(bool success) async {
  if (success) {
    await Navigator.pushReplacement(
        context, MaterialPageRoute(builder: (_) => NotesPage()));
  } else {
    ScaffoldMessenger.of(context)
        .showSnackBar(SnackBar(content: Text('Something went wrong.')));
  }
}

Now let's build the NotesPage. For now, it'll just be an empty page, with a button to sign out. Here's the full code:

class NotesPage extends StatelessWidget {
  const NotesPage();

  Future<void> _signOut(BuildContext context) async {
    final success = await Services.of(context).authService.signOut();
    if (success) {
      Navigator.pushReplacement(
          context, MaterialPageRoute(builder: (_) => HomePage()));
    } else {
      ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('There was an issue logging out.')));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Supanotes'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: Text('Your notes will show up here.'),
            ),
            ElevatedButton.icon(
              onPressed: () async {
                await _signOut(context);
              },
              icon: Icon(Icons.login),
              label: Text('Sign out'),
            ),
          ],
        ),
      ),
    );
  }
}

And that's it! We now have a proper authentication system set up for our Supanotes app. Now any requests to the Supabase client will include the signed in user info as well, so we can continue with the next part: creating and listing notes.

GoTrue and JSON Web Tokens

GoTrue uses JSON Web Tokens (JWT) for authentication. On a successful sign in/sign up, the response contains an access token, and a refresh token. The access token is included in every request to Supabase. When decoded, this token contains the user's unique ID, and this is how Supabase knows which user is performing the request. Access tokens are short-lived, and expire by default every one hour (you can configure this through the admin interface, but only do this if you have a good reason). You can read more about JWT here.

The access token is only valid for a short time, and we definitely don't want the user having to sign in every one hour. This is what the refresh token is for. The refresh token is valid for longer than an hour, and can be used to request new tokens. Let's take a look at some of the source code of the GoTrueClient:

void _saveSession(Session session) {
  currentSession = session;
  currentUser = session.user;
  final tokenExpirySeconds = session.expiresIn;

  if (autoRefreshToken && tokenExpirySeconds != null) {
    if (_refreshTokenTimer != null) _refreshTokenTimer!.cancel();

    final timerDuration = Duration(seconds: tokenExpirySeconds - 60);
    _refreshTokenTimer = Timer(timerDuration, () {
      _callRefreshToken();
    });
  }
}

If autoRefreshToken is set to true, a timer is set to automatically "refresh" the tokens by using the refresh token, one minute before the access token expires. autoRefreshToken is true by default, and can be changed through an optional parameter in the GoTrueClient constructor.

Now, what happens if the user exits the app? We lose access to both tokens, and have no way of requesting new tokens either, so the user would have to sign in again.

Keeping users signed in

To keep users signed in even after re-opening the app, we need to somehow request new tokens. GoTrueClient has a recoverSession function, which uses the refresh token mentioned before to request new tokens.

In order to recover the session, we need to persist the session data of a successful sign in. In this example, we'll use the shared_preferences package, but you might also want to use something like flutter_secure_storage if there are security concerns. Data stored in shared preferences is only accessible by the app which stored them, but this is not the case for rooted devices.

flutter pub add shared_preferences

Conveniently, the Session object in the GoTrueResponse contains a function to get the JSON string to persist. So all we have to do is store this string in SharedPreferences, and fetch it when we want to recover the session. Here's the updated signUp and signIn functions:

// AuthService
static const supabaseSessionKey = 'supabase_session';

Future<bool> signUp(String email, String password) async {
  final response = await _client.signUp(email, password);
  if (response.error == null) {
    log('Sign up was successful for user ID: ${response.user!.id}');
    _persistSession(response.data!);
    return true;
  }
  log('Sign up error: ${response.error!.message}');
  return false;
}

Future<bool> signIn(String email, String password) async {
  final response = await _client.signIn(email: email, password: password);
  if (response.error == null) {
    log('Sign in was successful for user ID: ${response.user!.id}');
    _persistSession(response.data!);
    return true;
  }
  log('Sign in error: ${response.error!.message}');
  return false;
}

Future<void> _persistSession(Session session) async {
  final prefs = await SharedPreferences.getInstance();
  log('Persisting session string');
  await prefs.setString(supabaseSessionKey, session.persistSessionString);
}

Note that it might make sense to initialize SharedPreferences once and pass it to any services that might need it, but let's keep it like this for simplicity.

Okay, so we have all we need to recover the session after the user exists the app. What now? In order to decide which page widget to show (HomePage if user is not signed in, NotesPage otherwise), we can check if there is a persisted session string, and attempt to recover the session with GoTrueClient#recoverSession. If there's no session string stored, or if recovering the session fails, then we can show the HomePage. If recovering the session works, then the user is successfully signed in! We can go straight to the NotesPage.

Let's introduce a new function in AuthService, that will attempt to recover the session.

// AuthService
Future<bool> recoverSession() async {
  final prefs = await SharedPreferences.getInstance();
  if (prefs.containsKey(supabaseSessionKey)) {
    log('Found persisted session string, attempting to recover session');
    final jsonStr = prefs.getString(supabaseSessionKey)!;
    final response = await _client.recoverSession(jsonStr);
    if (response.error == null) {
      log('Session successfully recovered for user ID: ${response.user!.id}');
      _persistSession(response.data!);
      return true;
    }
  }
  return false;
}

Next, let's call this function to decide which page to show first. Here's the updated build function of the root SupanotesApp widget:

@override
Widget build(BuildContext context) {
  return Services(
    child: MaterialApp(
      title: 'Supanotes',
      theme: ThemeData(
        brightness: Brightness.dark,
        primarySwatch: toMaterialColor(supabaseGreen),
      ),
      home: Builder(
        builder: (context) {
          return FutureBuilder<bool>(
            future: Services.of(context).authService.recoverSession(),
            builder: (context, snapshot) {
              final sessionRecovered = snapshot.data ?? false;
              return sessionRecovered ? NotesPage() : HomePage();
            },
          );
        },
      ),
    ),
  );
}

Note that we are wrapping the FutureBuilder with a Builder, as the Services object will not be available in the context of SupanotesApp.

And that's it! If you now try to perform a hot restart, or exit and re-open the app, you'll see that you'll still be signed in! If the refresh token has expired, the recoverSession function will attempt to refresh the tokens, otherwise it will resume with the persisted session.

The GoTrueClient is not a big class, so I'd recommend taking a better look at the source code if you're interested in seeing how it all works behind the scenes.

There is one more thing we need to do. When a user signs out, we should clear this persisted session string. Otherwise, if a user signs out and then re-opens the app, they could be signed back in!

Here's the updated signOut function:

Future<bool> signOut() async {
  final response = await _client.signOut();
  if (response.error == null) {
    log('Successfully logged out; clearing session string');
    final prefs = await SharedPreferences.getInstance();
    prefs.remove(supabaseSessionKey);
    return true;
  }
  log('Log out error: ${response.error!.message}');
  return false;
}

More auth features

Supabase authentication also supports third party logins, but we won't show an example of how to use this functionality in this post. These OAuth providers are supported:

• Google
• GitHub
• GitLab
• Azure
• Facebook
• BitBucket
• Apple
• Twitter

There is also support for magic links! If you call the GoTrueClient#signIn function without a password, this will send the user an email with a one-time login link. Both third party logins and magic links could be good potential blog posts, so watch this space!

Wrapping up

That's all for the first part of this tutorial series on Supabase with Flutter, focusing on Authentication. You can find the full code on GitHub. I hope you found it helpful, and would love it if you could share some feedback in the comments! In the next part, we will take a look at Supabase's Database offering.

If you'd like to be notified when the next part of this series is published, and for any future tutorials, please sign up with your email below.