FlutterFlow + PowerSync Legacy Guide

Used in conjunction with FlutterFlow, PowerSync enables developers to build local-first apps that are robust in poor network conditions and that have highly responsive frontends while relying on Supabase for their backend. This guide provides instructions for how to configure PowerSync for use with your FlutterFlow project that has Supabase integration enabled.

​

Guide Overview

This guide takes 30-40 minutes to complete.

1. Configure Supabase and PowerSync prerequisites
2. Initialize your FlutterFlow project
3. Build a sign-in screen
4. Initialize PowerSync
5. Reading data
6. Creating data
7. Deleting data
8. Signing out
9. Securing your app
   1. Enable RLS in Supabase
   2. Update Sync Rules in PowerSync

​

Configure Supabase

1. Create a new project in Supabase.
2. PowerSync uses the Postgres Write Ahead Log (WAL) to replicate data changes in order to keep PowerSync SDK clients up to date. Run the below SQL statement in your Supabase SQL Editor:

create table
  public.lists (
    id uuid not null default gen_random_uuid (),
    created_at timestamp with time zone not null default now(),
    name text not null,
    owner_id uuid not null,
    constraint lists_pkey primary key (id),
    constraint lists_owner_id_fkey foreign key (owner_id) references auth.users (id) on delete cascade
  ) tablespace pg_default

1. Create a Postgres publication using the SQL Editor. This will enable data to be replicated from Supabase so that your FlutterFlow app can download it.

create publication powersync for table public.lists;

​

Configure PowerSync

​

Create a PowerSync Cloud Instance

1. In the Overview workspace of the PowerSync Dashboard, you will be prompted to create your first instance:

2. Give your instance a name, such as “Testing”.
3. [Optional] You can change the default cloud region from US to EU, JP (Japan), AU (Australia) or BR (Brazil) if desired.
   • Note: Additional cloud regions will be considered on request, especially for customers on our Enterprise plan. Please contact us if you need a different region.
4. [Optional] You can opt in to using the Next version of the Service, which may contain early access or experimental features. Always use the Stable version in production.
5. Click Next.

​

Connect PowerSync to Your Supabase

1. From your Supabase Dashboard, select Connect in the top navigation bar (or follow this link):

2. In the Direct connection section, copy the complete connection string (including the [YOUR-PASSWORD] placeholder)

3. Back in the PowerSync Dashboard, paste the connection string into the URI field. PowerSync will automatically parse this URI to populate the database connection details.

4. Update the Username and Password fields to use the powersync_role and password you created when configuring your Supabase for PowerSync (see Source Database Setup).

5. Note: PowerSync includes Supabase’s CA certificate by default, so you can use verify-full SSL mode without additional configuration.

6. Your connection settings should look similar to this:

7. Verify your setup by clicking Test Connection and resolve any errors.
8. Click Next.
9. PowerSync will detect the Supabase connection and prompt you to enable Supabase auth. To enable it, copy your JWT Secret from your project’s settings (JWT Keys section in the Supabase dashboard) and paste it here:
10. Click Enable Supabase auth to finalize your connection settings.

PowerSync will now create an isolated cloud environment for your instance. This typically takes a minute or two.

​

Configure Sync Rules

Sync Rules allow developers to control which data gets synced to which user devices using a SQL-like syntax in a YAML file. For the demo app, we’re going to specify that each user can only see their own to-do lists and list items.

1. To update your Sync Rules, open the sync-rules.yaml file.

1. Replace the sync-rules.yaml file’s contents with the below:

bucket_definitions:
    global:
        data:
            - SELECT * FROM lists

For additional information on PowerSync’s Sync Rules, refer to the Sync Rules documentation.

If you’re wondering how Sync Rules relate to Supabase Postgres RLS, see this subsection.

​

Initialize Your FlutterFlow Project

1. Create a new Blank app, give it a name, and disable Firebase.
2. Under “App Settings” -> “Integrations”, enable Supabase. Enter your “API URL” (from the Project URL section in the Supabase dashboard) and “Anon Key” (API Keys section in the Supabase dashboard) and click “Get Schema”.
3. Under “App Values” -> “Constants”, click “Add App Constant”.
   1. For Constant Name, enter PowerSyncUrl.
   2. For Constant Value, copy and paste your instance URL from the PowerSync Dashboard:

You should now see this under App Constants:

​

Build A Sign-In Screen

1. Under Pages, click “Add Page, Component or Flow”.

2. Select the Auth1 template and name the page “Login”.
3. Delete the Sign Up, Forgot Password and Social Login buttons — we will only be supporting Login for this demo app.

4. Under “App Settings” -> “App Settings” -> “Authentication”:
   1. Enable Authentication.
   2. Set Supabase as the Authentication Type.
   3. Set the Login page you just created as the Entry Page.
   4. Set HomePage as the Logged In Page:

5. In your Supabase Dashboard, under “Authentication”, click on “Add User” -> “Create new user” and create a user for yourself to test with:

6. Launch your app on a physical or simulator device:

For once, a blank screen means success:

​

Initialize PowerSync

1. Click on “Custom Code” -> “Add” -> “Action”.
2. Name the Custom Action initpowersync.
   1. NOTE: use all lowercase for this Custom Action is important due to naming conversion that FF performs behind the scenes.
3. Copy and paste the custom action code from here:https://github.com/powersync-ja/powersync-flutterflow-template/blob/flutterflow/lib/custom_code/actions/initpowersync.dart
4. Import your schema:
   1. On the PowerSync Dashboard, right-click on your instance and select “Generate Client-Side Schema” and select Dart as the language.
   2. Paste this into your Custom Action code on line 27 after the equals sign.
   3. Due to a limitation in FF, you now need to prefix each instance of Schema, Column and Table with powersync.
   4. Your custom action schema definition should now look like this:
5. Under “Action Settings” on the right, add this dependency into “Pubspec Dependencies”: powersync: ^1.8.4
   1. FlutterFlow imports an old version of sqflite by default and it’s not possible to remove it, so you also need to add this dependency: sqflite: ^2.3.3
   2. Your dependencies should now look as follows:

1. Save your new custom action
2. Still in Custom Actions, under “Custom Files” click on main.dart and set your new Custom Action as a Final Action and click Save.

flutter: [PowerSync] FINE: 2024-04-16 13:47:52.259974: Credentials: PowerSyncCredentials

flutter: [PowerSync] FINE: 2024-04-16 13:47:52.607802: Applied checkpoint 2

​

Reading Data

We will now create our first UI and bind it to the data in the local SQLite database on the device.

​

Create a Custom Action to Stream all Lists

1. Create a new Custom Action and call it watchLists and paste the below code:

// Automatic FlutterFlow imports
import '/backend/supabase/supabase.dart';
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

import 'package:powersync/powersync.dart' as powersync;
import '/custom_code/actions/initpowersync.dart';
import 'package:supabase_flutter/supabase_flutter.dart';
import 'dart:async';

Future<void> watchLists(
    Future Function(List<ListsRow>? result) callback) async {
  var stream = db.watch('SELECT * FROM lists');
  listsSubscription?.cancel(); //it's important to clean up any existing subscriptions otherwise app performance will degrade
  listsSubscription = stream.listen((data) {
    callback(
        data.map((json) => ListsRow(Map<String, dynamic>.from(json))).toList());
  });
}

2. Hit Save and click “Yes” on the popup to set the Action Arguments for you:

3. Your Action Arguments should now look as follows:

4. Create the second Custom Action called getLists and paste the following code into it:

// Automatic FlutterFlow imports
import '/backend/supabase/supabase.dart';
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

import 'package:powersync/powersync.dart' as powersync;
import '/custom_code/actions/initpowersync.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

Future<List<ListsRow>?> getLists(List<ListsRow>? results) async {
  return results;
}

1. Hit Save and click “Yes” on the popup to set the Action Arguments for you:

2. Your Action Arguments should now look as follows:

3. On the HomePage page, you will create a placeholder Page State variable required for the next step.
   1. Click on State Management.
   2. Add a dummy variable called “notused” or similar and click Confirm:

4. Still on the HomePage page, select Actions and open “Action Flow Editor”.
   1. Add the watchLists Custom Action.
   2. Click “Open” to edit the callback Argument for watchLists.
   3. Add the getLists Custom Action and set the results Action Argument to result and click “Confirm”:

4. Set the “Action Output Variable Name” to allLists and you should now see this:

5. Add a second action to the chain, and set it to “Update Page State” and “Rebuild Current Page”. This is to ensure the page gets redrawn when the database updates. Your callback action should now look like this:

6. Click “Close” to exit the Action Flow Editor.
7. In the UI Builder on the HomePage page, add a ListView component and add a ListTile inside the ListView.
8. On the ListView component, click “Generate Dynamic Children”. Enter a variable name of boundLists and set its value to allLists (no further changes). Click Save.
9. On the ListTile component, set the Title field to “Set from Variable” and then get the name field from the boundLists variable:

10. Do the same for the Subtitle field of the ListTile component, and set it to created_at.
11. Hot reload your app and the screen will still be blank. This is because the lists table is empty in Supabase. Create a test row in the table by clicking on “Insert” -> “Insert Row” in your Supabase Table Editor.
12. Leave id and created_at blank.
13. Enter a name such as “Test from Supabase”.
14. Click “Select Record” for owner_id and select your test user.

​

Creating Data

You will now update the app so that we can capture new list entries.

1. Create a new Custom Action called createListItem and paste the following code:

// Automatic FlutterFlow imports
import '/backend/supabase/supabase.dart';
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

// Set your action name, define your arguments and return parameter,
// and then add the boilerplate code using the green button on the right!
import 'package:powersync/powersync.dart' as powersync;
import '/custom_code/actions/initpowersync.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

Future createListItem(String name) async {
  var supaUserId = await Supabase.instance.client.auth.currentUser?.id;

  final results = await db.execute('''
      INSERT INTO
        lists(id, created_at, name, owner_id)
        VALUES(uuid(), datetime(), ?, ?)
      ''', [name, supaUserId]);
}

1. Hit Save and click “Yes” on the popup to set the Action Arguments for you:

2. There should now be one argument for the Custom Action called name of type String and not nullable.
3. In the Widget Tree view, select the HomePage page and navigate to State Management.
4. Create a new State Field called fabClicked and set the type to boolean and toggle the “Initial Field Value” toggle twice to initialize the field to false.
6. In the Widget Tree view, drop a Floating Action Button (FAB) onto the page.
7. Click on the FAB and Open the Action Flow Editor.
8. Add an action to Update Page State.
9. Set the fabClicked value to true and click Close.

10. On the Widget Palette again, add a Container child to the Column Widget.
11. Now add a Column Widget to this Container.
12. Add a TextField and a Button to this Column Widget.
13. Your homepage layout should now look like this:

11. Set the Container and TextField widgets to have a width of 100%.
12. Click on the Container and enable Conditional Visibility for fabClicked.

13. Change the Button text to “Add”.
14. Open the Action Flow Editor for the Add button:
15. Add a Custom Action call to createListItem.
16. Set the “name” Argument to Widget State -> TextField 1.
17. Chain another Action of “Clear Text Fields / PIN Codes” to clear the TextField_1 field.
18. Chain another Action to Update Page State and set fabClicked to false.
19. Your Action Editor should now look like this:

​

Deleting Data

In this section we will add the ability to swipe on a ListTile to delete it.

1. Create a new Custom Action called deleteListItem and paste the below code:

// Automatic FlutterFlow imports
import '/backend/supabase/supabase.dart';
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

import 'package:powersync/powersync.dart' as powersync;
import '/custom_code/actions/initpowersync.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

Future deleteListItem(ListsRow row) async {
  await db.execute('DELETE FROM lists WHERE id = ?', [row.id]);
}

1. Hit Save and click “Yes” on the popup to set the Action Arguments for you:

2. The Custom Action Arguments should now look as follows:

3. In the Widget Tree select the ListTile and enable Slidable.
4. Select the SlidableActionWidget from the Widget Tree and set the values to the following:

5. Click on Action Editor and click Add Action, passing in boundLists to deleteListItem as follows:

​

Updating Data

In this section we will add the ability to update a list item. It entails:

• A custom action to handle updating the data
• Setting and using state fields to show/hide UI dynamically and reference the list item to edit
• A button to edit a list item (set up similar to the Delete button in the previous section)
• UI to enter and save the new item name (set up similar to the Create functionality we covered earlier)

1. Create a new Custom Action called updateListItem and paste the below code:

// Automatic FlutterFlow imports
import '/backend/supabase/supabase.dart';
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

// Set your action name, define your arguments and return parameter,
// and then add the boilerplate code using the green button on the right!
import 'package:powersync/powersync.dart' as powersync;
import '/custom_code/actions/initpowersync.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

Future updateListItem(String name, ListsRow row) async {
  await db.execute('UPDATE lists SET name = ? WHERE id = ?', [name, row.id]);
}

1. Hit Save and click “Yes” on the popup to set the Action Arguments for you:

1. The Custom Action Arguments should now look as follows:

1. In the Widget Tree view, select the HomePage page and navigate to State Management.
2. Create a new State Field called editClicked, set the type to Boolean and toggle the “Initial Field Value” toggle twice to initialize the field to false.
3. Create another new State Field called listItemIndex, set the type to Integer. Click Confirm.

4. In the Widget Tree select the ListTile.
5. Under Slidable Properties click Add Action.
6. Select the new SlidableActionWidget from the Widget Tree and set its properties to the following:

7. Open the Action Flow Editor.
8. Add an action to Update Page State.
9. Add Field: Set the editClicked value to true.
10. Add Field: Set the value of listItemIndex to the “Index in List” of the boundLists Item and click Close.

1. Chain another Action to “Set Form Field” -> TextField_2. This will initialize the text field to the current list item’s name.
   1. Set the variable to the boundLists Item
   2. Under Available Options, select “Get Row Field”
   3. Under Supabase Row Field, select “name”
   4. Your action should look like this:

2. On the Widget Palette again, add a Container child to the Column Widget.
   1. Now add a Column Widget to this Container.
   2. Add a TextField and a Button to this Column Widget.
   3. Your homepage layout should now look like this:

3. Set the Container and TextField widgets to have a width of 100%.
4. Click on the Container and enable Conditional Visibility for editClicked.

5. Change the Button text to “Save”
6. Open the Action Flow Editor for the Save button.
   1. Add a Custom Action call to updateListItem.
   2. Set the “name” Argument to Widget State -> TextField 2.
   3. Set the “row” Argument:
      1. Select Action Outputs -> allLists.
      2. Under Available Options select “Item at Index”.
      3. Under List Index Options select “Specific Index”.
      4. Set the Index value to the listItemIndex Page State variable

5. Click Confirm
6. Chain another Action of “Clear Text Fields / PIN Codes” to clear the TextField_2 field.
7. Chain another Action to “Update Page State”.
8. Add Field: Set editClicked to false.
9. Add Field: Set listItemIndex to Reset Value.
10. Your Action Editor should now look like this:

7. Close the Action Flow Editor.

​

Signing Out

1. Create a new Custom Action called signOut without Arguments or Return Values and paste the below code:

// Automatic FlutterFlow imports
import '/backend/supabase/supabase.dart';
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

// Set your action name, define your arguments and return parameter,
// and then add the boilerplate code using the green button on the right!
import 'package:powersync/powersync.dart' as powersync;
import '/custom_code/actions/initpowersync.dart';

Future signOut() async {
  listsSubscription?.cancel(); //close any open subscriptions from watch() queries
  await db.disconnectAndClear();
}

1. Click Save Action.
2. In the Widget Tree, drag a Button onto the right of your App Bar.
3. Rename the button text to “Sign Out”.
4. Open Action Editor and click Open to launch the editor.
5. Add a call to the signOutCustom Action.
6. Chain another call to Auth -> Log Out:

7. Click Close

​

Securing Your App

PowerSync’s Sync Rules and Supabase’s support for Row Level Security (RLS) can be used in conjunction. Here are some high level similarities and differences:

• RLS should be used as the authoritative set of security rules applied to your users’ CRUD operations that reach Postgres.
• Sync Rules are only applied for data that is to be downloaded to clients — they do not apply to uploaded data.
  • Sync Rules can typically be considered to be complementary to RLS, and will generally mirror your RLS setup.

​

Enable RLS in Supabase

Run the below in your Supabase console to ensure that only list owners can perform actions on the lists table where owner_id matches their user id:

alter table public.lists
  enable row level security;

create policy "owned lists" on public.lists for ALL using (
  auth.uid() = owner_id
)

​

Update Sync Rules

Currently all lists are synced to all users, regardless of who the owner of the list is. You will now update this so that only a user’s lists are synced to their device:

1. Navigate to the PowerSync Dashboard and open your sync-rules.yaml file.
2. Delete the existing content and paste the below contents:

bucket_definitions:
  user_lists:
    parameters: select request.user_id() as user_id
    data:
      - select * from lists where owner_id = bucket.user_id

1. Click on “Validate”.
2. Click on “Deploy sync rules”.
3. Wait for the deploy to complete.

​

Known Issues, Limitations and Gotchas

Below is a list of known issues and limitations.

1. It’s not currently possible to use the FlutterFlow Web Editor to test your app due to limitations with FlutterFlow.
2. When trying to compile any of the PowerSync Custom Actions, you will see errors — these can be safely ignored:

3. Using watch() queries creates a StreamSubscription and it’s important to regularly call .cancel() on these to avoid multiple subscriptions for the same query running.
4. Deploying to the Apple App Store currently requires some workarounds due to limitations in FlutterFlow:
   1. Download the code from FlutterFlow
   2. Open the Podfile located in the ios/directory
   3. The following option in the Podfile needs to be updated from use_frameworks! :linkage => :static to use_frameworks! (remove everything after the exclamation sign)
   4. After removing that option, clean the build folder and build the project again.
   5. You should now be able to submit to the App Store
5. Exporting the code from FlutterFlow using the “Download Code” action in FlutterFlow requires the same workaround listed in 4. above.
6. Other common issues and troubleshooting techniques are documented here: Troubleshooting