FlutterFlow + PowerSync

​

Guide Overview

1. Configure Supabase and PowerSync Prerequisites
2. Initialize Your FlutterFlow Project
3. Build a Sign-in Screen
4. Read Data
5. Create Data
6. Update Data (Guide coming soon)
7. Delete Data
8. Sign Out
9. (New) Display Connectivity and Sync Status
10. Secure Your App
11. Enable RLS in Supabase
12. Update Sync Rules in PowerSync

​

Configure Supabase

1. Create a new project in Supabase.
2. To set up the Postgres database for our demo app, we will create a lists table. The demo app will have access to this table even while offline. Run the below SQL statement in your Supabase SQL Editor:
   Copy

   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
   

3. 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 to create a Postgres role/user with replication privileges:
   Copy

   -- Create a role/user with replication privileges for PowerSync
   CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
   -- Set up permissions for the newly created role
   -- Read-only (SELECT) access is required
   GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  
   

   To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication mentioned in the next step (as well as for any other publications that may exist).
4. 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.
   Copy

   -- Create a publication to replicate tables. 
   -- Specify a subset of tables to replicate if required.
   -- The publication must be named "powersync"
   CREATE PUBLICATION powersync FOR ALL TABLES;
   

​

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:

If you’ve previously created an instance in your project, you can create an additional instance by navigating to Manage instances and clicking Create new instance:You can also create an entirely new project with its own set of instances. Click on the PowerSync icon in the top left corner of the Dashboard or on Admin Portal at the top of the Dashboard, and then click on Create Project.

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.

You can update your instance settings by navigating to the Manage instances workspace, opening your instance options and selecting Edit instance.

​

Configure Sync Rules

1. To update your Sync Rules, open the sync-rules.yaml file.
   
2. Replace the sync-rules.yaml file’s contents with the below:
   Copy

   # This will sync the entire table to all users - we will refine this later
   bucket_definitions:
      global:
         data:
               - SELECT * FROM lists
   

3. In the top right, click “Validate sync rules” and ensure there are no errors. This validates your sync rules against your Postgres database.
4. In the top right, click “Deploy sync rules” and select your instance.
5. Confirm in the dialog and wait a couple of minutes for the deployment to complete.

​

Initialize Your FlutterFlow Project

1. Create a new Blank project in FlutterFlow.
2. Under “App Settings” -> “Integrations”, enable “Supabase”.
   1. Enter your Supabase “API URL” and public “Anon Key”. You can find these under “Project Settings” -> “API Keys” -> anon public in your Supabase dashboard.
   2. Click “Get Schema”.
3. Add the PowerSync Library to your FlutterFlow account.
4. Under “App Settings” -> “Project Dependencies” -> “FlutterFlow Libraries” click “Add Library”.
   1. Select the “PowerSync” library.
   2. Add your schema:
      1. On the PowerSync Dashboard, right-click on your instance and select “Generate Client-Side Schema” and select “FlutterFlow” as the language.
      
      2. Copy and paste the generated schema into the “PowerSyncSchema” field.
   3. Copy and paste your PowerSync instance URL into the “PowerSyncUrl” field.
   
   4. Note: The default path for the “HomePage” field under “Library Pages” can be left as is and ignored. FlutterFlow does not currently provide a way to remove it.
   5. Close the library config.
5. Under “Custom Pub Dependencies”, add a dependency on powersync_core:1.3.0:

​

Build A Sign-In Screen

1. Under the “Page Selector”, click “Add Page, Component, or Flow”.
   
2. Select the “Auth 1” template and name the page Login.
3. Delete the Sign Up, Forgot Password and Social Login buttons — we will only be supporting Sign In for this demo app.

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

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

6. Test your app with test mode:

Click on 'Test'

Checkpoint: You should now be able to log into the app using the Supabase user account you just created. After logging in you should see a blank screen.

For once, a blank screen means success!

​

Read Data

1. Auto-updating queries for Layout Elements with Dynamic Children e.g. the ListView Element
   • This uses the library’s PowerSyncQuery component.
2. Auto-updating queries for basic Layout Elements e.g. Text Elements.
   • This uses the library’s PowerSyncStateUpdater component.
3. Once-off reads for static data.
   • This uses the library’s PowerSyncQueryOnce custom action.

​

Prepare Supabase Tables for Reads

1. Navigate to “Custom Code” and add a Custom Function.
2. Name the function supabaseRowsToList (if your Supabase table name is “Customers”, you would name this supabaseRowsToCustomers).
3. Under Function Settings on the right, set the “Return Value” to Supabase Row
   1. Check “Is List”.
   2. Uncheck “Nullable”.
   3. Under “Table Name”, select lists.
4. Also under Function Settings, click “Add Arguments”.
   1. Set its “Name” to supabaseRows
   2. Set its “Type” to “JSON”.
   3. Check “Is List”.
   4. Uncheck “Nullable”.
5. In the Function Code, paste the following code:
   Copy

   /// MODIFY CODE ONLY BELOW THIS LINE
   return supabaseRows.map((r) => ListsRow(r)).toList();
   

6. Click “Save Function”.

Custom function to map the lists table from Supabase

​

1. Auto-updating queries for Layout Elements with Dynamic Children

​

Create a Component to display List Items

1. Under the “Page Selector”, click “Add Page, Component, or Flow”.
2. Select the “New Component” tab.
3. Select “Create Blank” and call the component ListItems.
4. Under the “Widget Palette”, drag a “ListView” widget into the ListItems component.
5. Still under the “Widget Palette”, drag a “ListTile” into the ListView widget.
   

   The ListItems component should now look like this
6. Under the “Widget Tree”, select the ListItems component.
   1. At the top right under “Component Parameters” click “Add Parameters”.
   2. Click “Add Parameter”.
   3. Set its “Name” to lists.
   4. Set its “Type” to Supabase Row.
   5. Check “Is List”.
   6. Under “Table Name”, select lists.
   7. Click “Confirm”.
7. Still under the “Widget Tree”, select the “ListView” widget.
   1. Select the “Generate Dynamic Children” panel on the right.
   2. Set the “Variable Name” to listItem.
   3. Set the “Value” to the component parameter created in the previous step (lists).
   4. Click “Confirm”.
   5. Click “Save”.
   6. Click “Ok” when being prompted about the widget generating its children dynamically.
   

   The ListItems component should now look like this
8. Still under the “Widget Tree”, select the ListTile widget.
   1. In the “Properties” panel on the right, under “Title”, click on the settings icon next to “Text”.
   2. Set as “listItem Item”.
   3. Under “Available Options”, select “Get Row Field”.
   4. Under “Supabase Row Fields”, select “name”.
   5. Click “Confirm”.
   

   Set the list item title text
9. Repeat Step 8 above for the “Subtitle”, setting it to “created_at”.

The ListItems component should now look like this

​

Display the List Component and populate it with Data

1. Under the “Page Selector”, select your HomePage.
2. Under the “Widget Palette”, select the “Components and custom widgets imported from library projects” panel.
   
3. Drag the PowerSyncQuery library component into your page.
4. In the Properties panel on the right, under “Component Parameters” -> “child”:
   
   1. Click on “Unknown”.
   2. Select ListItems we previously created.
   3. Click on lists.
   4. Set the “Value” to “Custom Functions” -> supabaseRowsToList we created previously.
   5. Under the supabaseRows argument, set the “Value” to “Widget Builder Parameters” -> rows.
   6. Click “Confirm”.
   7. Click “Confirm”.
5. Still under “Component Parameters” add the SQL query to fetch all list items from the SQLite database:
   1. Paste the following into the “sql [String]” field: select * from lists order by created_at;
   2. For this query there are no parameters - this will be covered further down in the guide.
6. Still under “Component Parameters”, check “watch [Boolean]”. This ensures that the query auto-updates.

​

Test your App

1. Check that there are no project issues or errors.
2. Reload your app or start another test session.
3. Notice that your homepage is still 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.
   1. Leave id and created_at blank.
   2. Enter a name such as “Test from Supabase”.
   3. Click “Select Record” for owner_id and select your test user.

Checkpoint: You should now see your single test row magically appear in your app:

​

2. Auto-updating queries for basic Layout Elements

​

Create a Page Parameter

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

2. Create a blank page and name it Todos.
3. Under the “Widget Tree”, select your Todos page.
4. At the top right of the “Properties” panel on the right, click on the plus icon for Page Parameters.
5. Click “Add Parameter”.
6. Set the “Parameter Name” to id.
7. Set the “Type” to “String”.
8. Click “Confirm”.

​

Create a Local Page State Variable

1. Still in the “Widget Tree” with the Todos page selected:
2. Select the “State Management Panel” on the right.

3. Click on “Add Field”.
4. Set “Field Name” to list.
5. Set the “Type” to “Supabase Row”.
6. Under “Table Name”, select lists.
7. Click “Confirm”.

​

Bind the Page Title to the Page State

1. Under the “Widget Palette”, select the “Components and custom widgets imported from library projects” panel.
   
2. Drag the PowerSyncStateUpdater library component into your page.
3. Under the “Widget Tree”, select the PowerSyncStateUpdater component.
4. In the “Properties” panel on the right, under “Component Parameters”:
   1. Add the SQL query to fetch the selected list from the SQLite database. Paste the following into the “sql [String]” field: select * from lists where id = :id;
   2. Click on “parameters [Json]” select “Create Map (JSON)” as the variable.
      1. Under “Add Map Entries”, click “Add Key Value Pair”.
      2. Set the “Key” to id.
      3. Set the “Value” to the page parameter created previously called id.
      4. Check “watch [Boolean]”. This ensures that the query auto-updates.
      5. Click “Confirm”.
      
5. Still under “Component Parameters”, configure the “onData” action:
   1. Open the “Action Flow Editor”.
   2. Select the “Callback” trigger type.
   3. Click “Add Action”.
   4. Search for “update page” and select “Update Page State”.
   5. Click “Add Field”.
   6. Select your list page state variable.
   7. Set “Select Update Type” to “Set Value”.
   8. Set “Value to set” to “Custom Functions” -> supabaseRowsToList.
   9. Set the “Value” to “Callback Parameters” -> rows
   10. Click “Confirm”.
   11. Under “Available Options”, select “Item at Index”.
   12. Set “List Index Options” to “First”
   13. Click “Confirm”.
   
   14. Close the Action Flow Editor.
6. Still under the “Widget Tree”, select the “AppBar” -> “Text” widget.
   1. In the “Properties” panel on the right, click on settings icon next to “Text”.
   2. Click on “Page State” -> “List”.
   3. Set “Supabase Row Fields” to “name”.
   4. (Optional) Set the “Default Variable Value” to List Name.
   5. Click “Confirm”.

​

Make the ListView Component Clickable

1. Under the “Page Selector”, select your ListItems component.
2. Under the “Widget Tree”, select the ListTile widget.
3. In the “Actions” panel on the right, click “Add Action”. “On Tap” should be selected by default.
4. In the “Navigation” subsection, select “Navigate To”.
5. Select the “Todos” page.
6. Under “Parameters” click “Pass”.
7. “id” should be auto-selected, click on it.
8. Click on the settings icon next to “Value”
9. Set it to “listItem Item”.
10. Under “Available Options” select “Get Row Field”
11. Under “Supabase Row Fields” select “id”.
12. Click “Confirm”.
13. (Optional) Enable the back button to navigate back:
    1. Under the “Page Selector”, select your Todos page.
    2. Under the “Widget Tree”, select the “AppBar” component.
    3. In the “Properties” panel on the right, enable “Show Default Button”.

​

Test your App

Checkpoint: You should now be able to click on a list item and it should navigate you to a new page showing the name of the list in the title bar:

​

3. Once off reads for static data

​

Create Data

1. Under the “Page Selector”, select your HomePage page.
2. Under the “Widget Palette”, search for “float” and drag the “FAB” widget onto your page.
3. In the “Actions” panel on the right, click “Add Action”.
   1. Under “Custom Action” -> “PowerSync”, select “powersyncWrite”.
   2. Under the “Set Action Arguments” -> “sql” section, add the SQL query to create a new list item. For the purpose of this guide we are hardcoding the list’s name, normally you would build UI for this.
      1. Paste the following into the “Value” field: INSERT INTO lists(id, created_at, name, owner_id) VALUES(uuid(), datetime(), 'new item', :userId);
   3. Under the “parameters” section, set the userId parameter we’re using the above query:
      1. Click on “UNSET”.
      2. Select “Create Map (JSON)” as the variable.
      3. Under “Add Map Entries”, click “Add Key Value Pair”.
      4. Set the “Key” to userId.
      5. Set the “Value” to “Authenticated User” -> “User ID”.
      6. Click “Confirm”.

Checkpoint: Reload your app and click on the + floating action button. A new list item should appear, which also automatically syncs to Supabase:

​

Update Data

​

Delete Data

1. Under the “Page Selector”, select your ListItems component.
2. Under the “Widget Tree”, select the ListTile widget.
3. In the “Properties” panel on the right, enable “Slidable”.
4. Click “Open Slidable”.
5. Select the “SlidableActionWidget”.
   
6. In the “Actions” panel on the right, click “Add Action”.
   1. Under “Custom Action” -> “PowerSync”, select “powersyncWrite”.
   2. Under the “Set Action Arguments” -> “sql” section, add the SQL query to delete the list item.
      1. Paste the following into the “Value” field: delete from lists where id = :id;
   3. Under the “parameters” section, set the id parameter we’re using the above query:
      1. Click on “UNSET”.
      2. Select “Create Map (JSON)” as the variable.
      3. Under “Add Map Entries”, click “Add Key Value Pair”.
      4. Set the “Key” to id.
      5. Set the “Value” to “listItem Item”.
      6. Under “Available Options” select “Get Row Field”.
      7. Under “Supabase Row Fields” select “id”.
      8. Click “Confirm”.
      9. Click “Confirm”.

​

Sign Out

1. Navigate to “Custom Code” and 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 "package:power_sync_b0w5r9/backend/schema/structs/index.dart"
    as power_sync_b0w5r9_data_schema;
import 'package:ff_theme/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:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart'
    as ps;

Future signOut() async {
  final database = await ps.getOrInitializeDatabase();
  //await database.disconnectAndClear(); // this will completely delete all the local data, use with caution as there may be items still in the upload queue
  await database
      .disconnect(); //this will simply disconnect from the PowerSync Service and preserve all local data
}

// Set your action name, define your arguments and return parameter,
// and then add the boilerplate code using the green button on the right!

2. Click “Save Action”.
3. Under the “Page Selector”, select your HomePage page.
4. Under the “Widget Palette”, drag a “Button” onto the right of your “AppBar”.
   
5. In the “Properties” panel on the right, rename the “Button Text” to Sign Out.
6. Switch to the “Actions” panel and open the “Action Flow Editor”.
7. Select “On Tap” as the action trigger.
8. Click “Add Action” and add a call to the signOut Custom Action.
9. Chain another Action and call to “Supabase Authentication” -> “Log Out”:

10. Click “Close”.

​

(Optional) Display Connectivity and Sync Status

1. Under the Widget Palette, select the “Components and custom widgets imported from library projects” panel.
   
2. Drag the PowerSyncConnectivity component into your home page’s “AppBar”.
   

​

Secure Your App

• 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

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

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

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

​

Arrays, JSON and Other Types

CREATE TABLE public.lists (
  # ... existing columns,
  tags text[] DEFAULT '{"default", "tags"}'
);

/// MODIFY CODE ONLY BELOW THIS LINE
return supabaseRows.map((r) {
  return ListsRow({
    ...r,
    'tags': jsonDecode(r['tags'] as String),
  });
}).toList();

import 'package:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart';

Future applyPowerSyncOptions() async {
  // Add your function code here!
  powerSyncOptions.transformData = (table, data) {
    switch (table) {
      case 'lists':
        data['tags'] = jsonDecode(data['tags'] as String);
    }
  };
}

​

Custom Backend Connectors

import 'package:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart';
import 'package:powersync/powersync.dart' as ps;

Future applyPowerSyncOptions() async {
  // Disable the default Supabase integration
  powerSyncOptions.useSupabaseConnector = false;
  final db = await getOrInitializeDatabase();

  // TODO: Write your own connector and call connect/disconnect when a user logs
  // in.
  db.connect(connector: _MyCustomConnector());
}

final class _MyCustomConnector extends ps.PowerSyncBackendConnector {
  @override
  Future<ps.PowerSyncCredentials?> fetchCredentials() {
    // TODO: implement fetchCredentials
    throw UnimplementedError();
  }

  @override
  Future<void> uploadData(ps.PowerSyncDatabase database) {
    // TODO: implement uploadData
    throw UnimplementedError();
  }
}

​

Known Issues, Limitations and Gotchas

1. 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.
2. Exporting the code from FlutterFlow using the “Download Code” action in FlutterFlow requires the same workaround listed above.
3. Other common issues and troubleshooting techniques are documented here: Troubleshooting.