Supabase Flutter

https://github.com/supabase/supabase-flutter
Admin
Supabase Flutter is a client library that allows Flutter developers to easily integrate with...
Tokens:64,282
Snippets:514
Trust Score:10
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run the example launcher

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/database_crud/README.md

From the examples directory, run the launcher and pick database_crud.

```bash
./run.sh
```

--------------------------------

### Run the example with the examples launcher

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/passkeys/README.md

Boots a local Supabase stack and runs the example with the right credentials. Requires the examples launcher script.

```bash
cd examples
./run.sh
```

--------------------------------

### Run an example directly with dart-define

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/README.md

Runs the passkeys example directly against any project by passing SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY as --dart-define values.

```bash
cd examples/passkeys
flutter run -d chrome \
  --dart-define=SUPABASE_URL=https://YOUR_PROJECT.supabase.co \
  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
```

--------------------------------

### Run the example directly with Flutter

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/database_crud/README.md

Run the app directly against any project, providing the Supabase URL and publishable key as dart-define values.

```bash
flutter run \
  --dart-define=SUPABASE_URL=https://YOUR_PROJECT.supabase.co \
  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
```

--------------------------------

### Start local Supabase stack

Source: https://github.com/supabase/supabase-flutter/blob/main/README.md

Start the local Supabase stack for running tests of the postgrest, supabase_auth, supabase_realtime, and supabase_storage packages. Requires Docker and the Supabase CLI.

```bash
supabase start
```

--------------------------------

### Install Melos and Bootstrap Dependencies

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Install Melos globally and bootstrap dependencies for all packages in the monorepo. Use `melos bs` as a shorthand for `melos bootstrap`.

```bash
# Install Melos globally (if not already installed)
dart pub global activate melos

# Bootstrap dependencies for all packages
melos bootstrap
# or shorthand:
melos bs

```

--------------------------------

### PostgREST Query Example

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Example of a PostgREST query using the supabase-dart client. Chains select, filter, and limit operations on the 'users' table.

```dart
supabase.from('users').select('id, name').eq('id', 1).limit(10)
```

--------------------------------

### Generate platform folders with flutter create

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter_web_auth/example/README.md

Run this command in the project root to generate platform folders (android/, ios/, etc.) that are not checked in. Required before running the example.

```sh
flutter create .
```

--------------------------------

### AsyncJsonCodec implementation example

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/yet_another_json_isolate/README.md

Implements AsyncJsonCodec to wrap another codec and measure its operations. Useful for custom JSON processing or benchmarking the default implementation.

```dart
class TimedJsonCodec implements AsyncJsonCodec {
  TimedJsonCodec(this._inner);

  final AsyncJsonCodec _inner;

  @override
  Future<dynamic> decode(String json) => _time(() => _inner.decode(json));

  @override
  Future<dynamic> decodeBytes(Uint8List encodedJson) =>
      _time(() => _inner.decodeBytes(encodedJson));

  @override
  Future<String> encode(Object? json) => _time(() => _inner.encode(json));

  @override
  Future<void> dispose() => _inner.dispose();
}
```

--------------------------------

### Replace Supabase.initialize debug flag with Logger.root.onRecord listener

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the migration from the removed `debug` flag to manual logging via `package:logging`. The `Supabase.initialize` call no longer accepts `debug` and never prints logs; you must listen to `Logger.root.onRecord` and filter by the `supabase.` logger hierarchy. The example includes the before and after code in one block.

```dart
// Before
await Supabase.initialize(
  url: supabaseUrl,
  publishableKey: supabaseKey,
  debug: true,
);

// After
Logger.root.onRecord.listen((record) {
  if (record.loggerName.startsWith('supabase.')) {
    debugPrint('${record.loggerName}: ${record.level.name}: '
        '${record.message} ${record.error ?? ''}');
  }
});
await Supabase.initialize(
  url: supabaseUrl,
  publishableKey: supabaseKey,
);
```

--------------------------------

### Register Public API in sdk-compliance.yaml

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Example entry in sdk-compliance.yaml for registering a new public API symbol. The status is 'implemented', with the main symbol under 'symbols' and supporting types under 'supporting_symbols'.

```yaml
auth.mfa_recovery_codes.generate:
  status: implemented
  symbols:
    - AuthClient.generateMfaRecoveryCodes
  supporting_symbols:
    - MFARecoveryCodesGenerateResponse
```

--------------------------------

### Test backend packages with local Supabase stack

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Run tests for packages that require a backend (postgrest, supabase_auth, supabase_realtime, supabase_storage). Start the local Supabase stack from the repository root, run tests sequentially with `dart test -j 1` from the package directory, then stop the stack. The `-j 1` flag is required because tests share the same backend.

```bash
supabase start

```

```bash
cd packages/<package>
dart test -j 1

```

```bash
supabase stop

```

--------------------------------

### Run all package tests with melos test

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Run `dart test`/`flutter test` in each package that has a test/ directory. Start the local Supabase stack first so the backend packages pass.

```bash
melos test

```

--------------------------------

### Run integration tests with local Supabase

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_realtime/README.md

Starts the local Supabase stack, runs the full test suite (including integration tests), and stops the stack. The integration tests in test/realtime_integration_test.dart run against a real Supabase Realtime server and exercise both protocol versions, 1.0.0 and 2.0.0.

```bash
supabase start
```

```bash
dart test
```

```bash
supabase stop
```

--------------------------------

### Catching AuthApiException with statusCode

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Before and after examples showing how to catch a rate-limit error. The before version uses AuthException with a String statusCode, the after version uses AuthApiException with an int statusCode.

```dart
// Before
try {
  await supabase.auth.signInWithPassword(email: email, password: password);
} on AuthException catch (error) {
  if (error.statusCode == '429') {
    // ...
  }
}

// After
try {
  await supabase.auth.signInWithPassword(email: email, password: password);
} on AuthApiException catch (error) {
  if (error.statusCode == 429) {
    // ...
  }
}
```

--------------------------------

### Mock SharedPreferencesAsync in widget tests

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Required setup for widget tests that call Supabase.initialize, because SharedPreferences.setMockInitialValues() only mocks the legacy API. Without this, the new storage throws StateError: The SharedPreferencesAsyncPlatform instance must be set. Add shared_preferences_platform_interface as a dev_dependency for the import.

```dart
import 'package:shared_preferences_platform_interface/in_memory_shared_preferences_async.dart';
import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';

setUp(() {
  SharedPreferences.setMockInitialValues({});
  SharedPreferencesAsyncPlatform.instance =
      InMemorySharedPreferencesAsync.empty();
});
```

--------------------------------

### Run on a different device

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/README.md

Forwards arguments to flutter run, replacing the default -d chrome --web-port 3000. Only override the device for examples that do not use passkeys, as the passkeys example needs the fixed origin.

```bash
./run.sh -d macos
```

--------------------------------

### Postgres Changes with onPostgresChanges

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Subscribe to database changes on a specific table using Postgres Changes. The example listens to all events on the 'countries' table in the 'public' schema.

```dart
final myChannel = supabase.channel('my_channel');

myChannel
    .onPostgresChanges(
      event: PostgresChangeEvent.all,
      schema: 'public',
      table: 'countries',
    )
    .listen((payload) {
      // Do something fun or interesting when there is a change on the database
    });

myChannel.subscribe();
```

--------------------------------

### Select and insert data with supabase.from

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Perform basic CRUD operations using the Supabase REST API. The example shows selecting rows with equality and inequality filters, and inserting a new row into the 'cities' table.

```dart
// Select data with filters
final data = await supabase
  .from('cities')
  .select()
  .eq('country_id', 1) // equals filter
  .neq('name', 'The shire'); // does not equal filter

// Insert a new row
await supabase
  .from('cities')
  .insert({'name': 'The Shire', 'country_id': 554});
```

--------------------------------

### Rename GoTrueClient to AuthClient

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the type rename from GoTrueClient to AuthClient when migrating from v2 to v3. The before and after lines are shown together as a single example.

```dart
// Before
final GoTrueClient auth = supabase.auth;

// After
final AuthClient auth = supabase.auth;
```

--------------------------------

### Get catalog from Supabase analytics bucket

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/iceberg/README.md

Use this snippet to obtain an Iceberg catalog from a Supabase analytics bucket using the StorageClient. It creates a namespace in the catalog.

```dart
final catalog = supabase.storage.analyticsCatalog('my-analytics-bucket');
await catalog.createNamespace(['my_namespace']);
```

--------------------------------

### Migrate onAuthStateChange listener to sealed AuthState subtypes

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Migration example showing how to update an onAuthStateChange listener when AuthState becomes a sealed class. The 'Before' block uses event comparison and null-checks; the 'After' block uses pattern matching on the new AuthState subtypes. Note that signOutReason moved to AuthSignedOut.reason and AuthState can no longer be constructed directly.

```dart
// Before
supabase.auth.onAuthStateChange.listen((state) {
  if (state.event == AuthChangeEvent.signedOut) {
    if (state.signOutReason == SignOutReason.sessionExpired) {
      showSessionExpired();
    }
    showLogin();
  } else if (state.session != null) {
    showHome(state.session!.user);
  }
});
```

```dart
// After
supabase.auth.onAuthStateChange.listen((state) {
  switch (state) {
    case AuthSignedOut(reason: SignOutReason.sessionExpired):
      showSessionExpired();
      showLogin();
    case AuthSignedOut():
    case AuthInitialSession(session: null):
      showLogin();
    case AuthInitialSession(session: final session?):
    case AuthSignedIn(:final session):
    case AuthTokenRefreshed(:final session):
    case AuthUserUpdated(:final session):
    case AuthPasswordRecovery(:final session):
    case AuthMfaChallengeVerified(:final session):
      showHome(session.user);
  }
});
```

--------------------------------

### Broadcast events with onBroadcast and sendBroadcastMessage

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Broadcast low-latency messages between connected clients without touching the database. This example listens for 'cursor-pos' events and sends a message with coordinates.

```dart
final myChannel = supabase.channel('my_channel');

// Listen to `cursor-pos` broadcast events
myChannel.onBroadcast(event: 'cursor-pos').listen((payload) {
  // Do something fun or interesting with the received message
});

myChannel.subscribe();

// Send a broadcast message to other connected clients
await myChannel.sendBroadcastMessage(
  event: 'cursor-pos',
  payload: {'x': 30, 'y': 50},
);
```

--------------------------------

### Replace SupabaseClient isolate parameter with jsonCodec

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Migrates from the `isolate:` parameter to `jsonCodec:` when constructing a `SupabaseClient`. The `YAJsonIsolate` is still used but now must be passed as an `AsyncJsonCodec`. The example shows the before and after in one block.

```dart
// Before
final client = SupabaseClient(url, key, isolate: YAJsonIsolate()..initialize());

// After
final client = SupabaseClient(url, key, jsonCodec: YAJsonIsolate()..initialize());
```

--------------------------------

### Windows runner CMake configuration

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/example/windows/runner/CMakeLists.txt

CMake configuration for the Windows runner of a Flutter application. It defines the executable target with the required source files, applies standard build settings, disables the NOMINMAX macro, links the Flutter libraries, and adds the flutter_assemble dependency. This file is part of the standard Flutter Windows runner setup.

```cmake
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)

# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})

# Disable Windows macros that collide with C++ standard library functions.
target_compile_definitions(${BINARY_NAME} PRIVATE "NOMINMAX")

# Add dependency libraries and include directories. Add any application-specific
# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")

# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Create profiles table, RLS policies, Realtime, and Storage

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/example/README.md

Run this SQL in the Supabase SQL editor to create the profiles table with row level security policies, enable Realtime, and set up the avatars storage bucket with public access policies.

```sql
-- Create a table for Public Profiles
create table profiles (
  id uuid references auth.users not null,
  updated_at timestamp with time zone,
  username text unique,
  avatar_url text,
  website text,

  primary key (id),
  unique(username),
  constraint username_length check (char_length(username) >= 3)
);

alter table profiles
  enable row level security;

create policy "Public profiles are viewable by everyone." on profiles
  for select using (true);

create policy "Users can insert their own profile." on profiles
  for insert with check (auth.uid() = id);

create policy "Users can update own profile." on profiles
  for update using (auth.uid() = id);

-- Set up Realtime!
begin;
  drop publication if exists supabase_realtime;
  create publication supabase_realtime;
commit;
alter publication supabase_realtime
  add table profiles;

-- Set up Storage!
insert into storage.buckets (id, name)
  values ('avatars', 'avatars');

create policy "Avatar images are publicly accessible." on storage.objects
  for select using (bucket_id = 'avatars');

create policy "Anyone can upload an avatar." on storage.objects
  for insert with check (bucket_id = 'avatars');

create policy "Anyone can update an avatar." on storage.objects
  for update with check (bucket_id = 'avatars');
```

--------------------------------

### Initialize Supabase for Local Testing

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Initializes the Supabase client to point to a local instance for integration testing. Replace the URL and key with your local Supabase credentials.

```dart
await Supabase.initialize(
  url: 'http://localhost:54321',
  publishableKey: 'your-local-supabase-key',
);
```

--------------------------------

### Run the integration test

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/database_crud/README.md

Run the end-to-end test against the local stack, passing the same defines and specifying a device (e.g., macos).

```bash
flutter test integration_test/tasks_test.dart -d macos \
  --dart-define=SUPABASE_URL=http://localhost:54321 \
  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_LOCAL_PUBLISHABLE_KEY
```

--------------------------------

### Run a single test file or test case

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Run a single test file from the package directory. Use the `-n` flag to run a specific test case matching a name pattern.

```bash
dart test test/specific_test.dart

```

```bash
dart test test/specific_test.dart -n "test name pattern"

```

--------------------------------

### Configure RealtimeClientOptions in SupabaseClient

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows how to pass the heartbeat interval and reconnect backoff through `RealtimeClientOptions` when the client is managed by a `SupabaseClient`. Headers are passed through `SupabaseClient.headers`.

```dart
final supabase = SupabaseClient(
  supabaseUrl,
  supabaseKey,
  realtimeClientOptions: const RealtimeClientOptions(
    heartbeatInterval: Duration(seconds: 60),
  ),
);
```

--------------------------------

### Run storage_transforms integration test

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/storage_transforms/README.md

Run the integration test against the local stack, passing the same defines the app uses and specifying a device (e.g., -d macos).

```bash
flutter test integration_test/storage_test.dart -d macos \
  --dart-define=SUPABASE_URL=http://localhost:54321 \
  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_LOCAL_PUBLISHABLE_KEY
```

--------------------------------

### Supabase Authentication Basics

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Shows basic Supabase authentication flows: email/password sign-up and login, magic link login, and listening to auth state changes. The auth state listener uses pattern matching on AuthSignedIn and AuthSignedOut events.

```dart
final supabase = Supabase.instance.client;

// Email and password sign up
await supabase.auth.signUp(
  email: email,
  password: password,
);

// Email and password login
await supabase.auth.signInWithPassword(
  email: email,
  password: password,
);

// Magic link login
await supabase.auth.signInWithOtp(email: 'my_email@example.com');

// Listen to auth state changes
supabase.auth.onAuthStateChange.listen((state) {
  switch (state) {
    case AuthSignedIn(:final session):
      print('Signed in as ${session.user.email}');
    case AuthSignedOut(:final reason):
      print('Signed out, reason: ${reason?.name}');
    default:
      print('Auth event: ${state.event.name}');
  }
});
```

--------------------------------

### Constructing User with AppMetadata before and after migration

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows how to construct a User object before and after the migration. After the change, appMetadata takes an AppMetadata object and userMetadata is optional and non-nullable.

```dart
// Before
final user = User(
  id: id,
  appMetadata: {'provider': 'email'},
  userMetadata: null,
  audience: 'authenticated',
  createdAt: createdAt,
);

// After
final user = User(
  id: id,
  appMetadata: const AppMetadata(provider: 'email', providers: ['email']),
  audience: 'authenticated',
  createdAt: createdAt,
);
```

--------------------------------

### Presence with onPresenceSync, onPresenceJoin, onPresenceLeave

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Implement presence to show who is online. Listen to sync, join, and leave events, and track the user's state after subscribing.

```dart
final myChannel = supabase.channel('my_channel');

// Listen to presence events
myChannel.onPresenceSync.listen((payload) {
  final onlineUsers = myChannel.presenceState();
  // handle sync event
});
myChannel.onPresenceJoin.listen((payload) {
  // New users have joined
});
myChannel.onPresenceLeave.listen((payload) {
  // Users have left
});

myChannel.onStatusChange.listen((change) async {
  if (change.status == RealtimeSubscribeStatus.subscribed) {
    // Send the current user's state upon subscribing
    await myChannel.track({'online_at': DateTime.now().toIso8601String()});
  }
});

myChannel.subscribe();
```

--------------------------------

### Run tests with coverage

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Run tests with coverage from a package directory. Generates coverage data in the `coverage` directory.

```bash
cd packages/<package>
dart test --coverage=coverage

```

--------------------------------

### Create IcebergRestCatalog with iceberg package

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Use this snippet to instantiate an IcebergRestCatalog when depending on the 'iceberg' package directly. Requires a base URL, headers (e.g., Authorization), and a warehouse name.

```dart
final catalog = IcebergRestCatalog(
  baseUrl: 'https://example.com/iceberg',
  headers: {'Authorization': 'Bearer $token'},
  warehouse: 'my-warehouse',
);
```

--------------------------------

### Run authentication integration test with local Supabase

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/authentication/README.md

Runs the end-to-end authentication integration test against the local Supabase stack. Requires the local stack to be running and a device (e.g., -d macos). The SUPABASE_URL must be reachable from the device; on Android emulators use 10.0.2.2 or adb reverse, and on physical devices use the host machine's LAN IP.

```bash
flutter test integration_test/authentication_test.dart -d macos \
  --dart-define=SUPABASE_URL=http://localhost:54321 \
  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_LOCAL_PUBLISHABLE_KEY
```

--------------------------------

### Migrate TracePropagationOptions to require traceContextProvider

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the migration from `TracePropagationOptions.enabled` to a required `traceContextProvider`. Passing options turns propagation on; a `TracePropagationOptions()` with no provider, or `enabled: false` next to a provider, no longer compiles.

```dart
// Before
tracePropagationOptions: TracePropagationOptions(
  enabled: true,
  traceContextProvider: () => TraceContext.fromCarrier(carrier),
),

// After
tracePropagationOptions: TracePropagationOptions(
  traceContextProvider: () => TraceContext.fromCarrier(carrier),
),
```

--------------------------------

### Upgrade and check dependencies with dart pub

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Upgrade dependencies across the whole workspace with `dart pub upgrade` (run at the repository root). Check for outdated dependencies with `dart pub outdated`.

```bash
dart pub upgrade

```

```bash
dart pub outdated

```

--------------------------------

### Supabase.initialize: replace anonKey with publishableKey

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the required change from 'anonKey' to 'publishableKey' in Supabase.initialize. The old anon key value is still valid but must be passed under the new parameter name.

```dart
// Before
await Supabase.initialize(url: url, anonKey: anonKey);

// After
await Supabase.initialize(url: url, publishableKey: anonKey);
```

--------------------------------

### MockSupabaseHttpClient.stubStorageDownload

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_test/README.md

Registers a stub for storage downloads.

```APIDOC
## MockSupabaseHttpClient.stubStorageDownload

### Description
Registers a stub for storage downloads. It knows the path and response shape of the storage download API.

### Method
N/A (SDK method)

### Endpoint
`/storage/v1/object/<bucket>/<path>` (implied)

### Parameters
- **bucket** (String) - Required - The bucket name.
- **path** (String) - Required - The object path.
- **bytes** (Uint8List) - Optional - The bytes to return as the response body.
- **times** (int) - Optional - Limits how many times the stub answers.
- **statusCode** (int) - Optional - The HTTP status code to return.

### Request Example
```dart
httpClient.stubStorageDownload('avatars', 'me.png', bytes: pngBytes);
```

### Response
#### Success Response (200)
- **body** (Uint8List) - The stubbed bytes.

#### Response Example
```dart
Uint8List.fromList([137, 80, 78, 71]);
```
```

--------------------------------

### Initialize Supabase in Flutter

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Initializes Supabase with your project URL and publishable key before running the app. Also extracts the Supabase client instance for later use.

```dart
import 'package:supabase_flutter/supabase_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Supabase.initialize(
    url: SUPABASE_URL,
    publishableKey: SUPABASE_KEY,
  );

  runApp(MyApp());
}

// It's handy to then extract the Supabase client in a variable for later uses
final supabase = Supabase.instance.client;
```

--------------------------------

### Test packages without a backend

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Run tests for packages without a backend requirement. Execute from the package directory.

```bash
cd packages/<package>
dart test

```

--------------------------------

### Run the integration test with flutter test

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/realtime_room/README.md

Runs the integration test on a device (e.g., macOS, emulator, or real device) against the local stack. Requires the local stack to be running and the same defines as the app.

```bash
flutter test integration_test/room_test.dart -d macos \
  --dart-define=SUPABASE_URL=http://localhost:54321 \
  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_LOCAL_PUBLISHABLE_KEY
```

--------------------------------

### Migrate createSignedUrls to SignedUrlSuccess/SignedUrlFailure

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the migration from the old `createSignedUrls` returning `List<SignedUrl>` to the new behavior returning a list of `SignedUrlSuccess` and `SignedUrlFailure`. The separate `createSignedUrlsResult` method is removed; drop the `Result` suffix if you used it. The new pattern uses a switch to handle success and failure cases.

```dart
// Before
final urls = await supabase.storage
    .from('avatars')
    .createSignedUrls(['a.png', 'b.png'], 60);
for (final url in urls) {
  print(url.signedUrl);
}

// After
final results = await supabase.storage
    .from('avatars')
    .createSignedUrls(['a.png', 'b.png'], 60);
for (final result in results) {
  switch (result) {
    case SignedUrlSuccess(:final signedUrl):
      print(signedUrl);
    case SignedUrlFailure(:final path, :final error):
      print('could not sign $path: $error');
  }
}
```

--------------------------------

### Run unit tests

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_realtime/README.md

Runs the unit tests without any external services.

```bash
dart test -x integration
```

--------------------------------

### Native Google sign-in with Supabase using google_sign_in

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Performs native Google sign-in on Android and iOS using the google_sign_in package, then signs in with Supabase using the obtained ID and access tokens. Requires a web client ID and an iOS client ID; replace the placeholders with your own. The Supabase dashboard must have the web client ID configured under Authentication -> Providers -> Google with 'Skip nonce check' enabled for iOS.

```dart
import 'package:google_sign_in/google_sign_in.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

...

Future<Session> _googleSignIn() async {
  /// TODO: update the Web client ID with your own.
  ///
  /// Web Client ID that you registered with Google Cloud.
  const webClientId = 'my-web.apps.googleusercontent.com';

  /// TODO: update the iOS client ID with your own.
  ///
  /// iOS Client ID that you registered with Google Cloud.
  const iosClientId = 'my-ios.apps.googleusercontent.com';

  // Google sign in on Android will work without providing the Android
  // Client ID registered on Google Cloud.

  final GoogleSignIn signIn = GoogleSignIn.instance;

  // At the start of your app, initialize the GoogleSignIn instance
  unawaited(
    signIn.initialize(clientId: iosClientId, serverClientId: webClientId));

  // Perform the sign in
  final googleAccount = await signIn.authenticate();
  final googleAuthorization = await googleAccount.authorizationClient.authorizationForScopes([]);
  final googleAuthentication = googleAccount!.authentication;
  final idToken = googleAuthentication.idToken;
  final accessToken = googleAuthorization.accessToken;

  if (idToken == null) {
    throw 'No ID Token found.';
  }

  return supabase.auth.signInWithIdToken(
    provider: OAuthProvider.google,
    idToken: idToken,
    accessToken: accessToken,
  );
}
...
```

--------------------------------

### Pass custom AsyncJsonCodec to Supabase.initialize

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows how to pass a custom `AsyncJsonCodec` to `Supabase.initialize` via the new `jsonCodec:` parameter. This replaces the old `isolate:` parameter and allows the application to control JSON encoding and decoding.

```dart
await Supabase.initialize(
  url: url,
  publishableKey: publishableKey,
  jsonCodec: myJsonCodec,
);
```

--------------------------------

### Stub storage operations with storage shorthands

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_test/README.md

Uses storage shorthands that know the paths and response shapes of the storage API. Covers upload, download, signed URL, list, and remove operations for a given bucket and object.

```dart
httpClient
  ..stubStorageUpload('avatars', 'me.png')
  ..stubStorageDownload('avatars', 'me.png', bytes: pngBytes)
  ..stubStorageSignedUrl('avatars', 'me.png')
  ..stubStorageList('avatars', objects: [storageObjectJson('me.png')])
  ..stubStorageRemove('avatars', paths: ['me.png']);
```

--------------------------------

### Set codec via RealtimeClientOptions

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Sets a custom codec on SupabaseClient via RealtimeClientOptions without constructing a RealtimeClient manually.

```dart
await Supabase.initialize(
  url: url,
  publishableKey: publishableKey,
  realtimeClientOptions: RealtimeClientOptions(
    encode: (message) => isolate.encode(message.toJson()),
    decode: (frame) async =>
        RealtimeMessage.fromJson(await isolate.decode(frame as String)),
  ),
);
```

--------------------------------

### Initialize Supabase with FlutterWebAuth2OAuthLauncher

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter_web_auth/README.md

Initialize Supabase with the FlutterWebAuth2OAuthLauncher to use system web authentication for OAuth, SSO, and linkIdentity flows. The launcher auto-dismisses the browser after redirect and shares cookies with the system browser on iOS/macOS and Android.

```dart
import 'package:supabase_flutter/supabase_flutter.dart';
import 'package:supabase_flutter_web_auth/supabase_flutter_web_auth.dart';

await Supabase.initialize(
  url: 'https://your-project.supabase.co',
  publishableKey: 'your-publishable-key',
  authOptions: const FlutterAuthClientOptions(
    oauthLauncher: FlutterWebAuth2OAuthLauncher(),
  ),
);
```

--------------------------------

### Test SupabaseClient with MockSupabaseHttpClient

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_test/README.md

Creates a test SupabaseClient with a mocked HTTP client, stubs the 'todos' table, and verifies the select query returns the expected row. Dispose the client with addTearDown(supabase.dispose).

```dart
import 'package:supabase_test/supabase_test.dart';
import 'package:test/test.dart';

void main() {
  test('loads the open todos', () async {
    final httpClient = MockSupabaseHttpClient()
      ..stubTable('todos', rows: [
        {'id': 1, 'task': 'Ship it', 'status': false},
      ]);
    final supabase = testSupabaseClient(httpClient: httpClient);
    addTearDown(supabase.dispose);

    final todos = await supabase.from('todos').select();

    expect(todos, hasLength(1));
  });
}
```

--------------------------------

### Stub error, stall, and status sequences

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_test/README.md

Use stubError to throw a ClientException for the first two requests, stubStall to leave a request unanswered, and stubStatuses to return a sequence of status codes (503, 503, then 200) for a specific path.

```dart
httpClient
  // The first two requests throw, the ones after them are answered.
  ..stubError(ClientException('Offline'), times: 2)
  // Never answered, so only a timeout or an abort ends the request.
  ..stubStall(path: '/functions/v1/slow')
  // 503, 503, then 200 for this request and every one after it.
  ..stubStatuses([503, 503, 200], body: [], path: '/rest/v1/todos');
```

--------------------------------

### MockSupabaseHttpClient.stubStorageUpload

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_test/README.md

Registers a stub for storage uploads.

```APIDOC
## MockSupabaseHttpClient.stubStorageUpload

### Description
Registers a stub for storage uploads. It knows the path and response shape of the storage upload API.

### Method
N/A (SDK method)

### Endpoint
`/storage/v1/object/<bucket>/<path>` (implied)

### Parameters
- **bucket** (String) - Required - The bucket name.
- **path** (String) - Required - The object path.
- **times** (int) - Optional - Limits how many times the stub answers.
- **statusCode** (int) - Optional - The HTTP status code to return.

### Request Example
```dart
httpClient.stubStorageUpload('avatars', 'me.png');
```

### Response
#### Success Response (200)
- **Key** (String) - The key of the uploaded object.

#### Response Example
```json
{"Key": "avatars/me.png"}
```
```

--------------------------------

### RealtimeClient connection callbacks to streams

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the migration from the four connection callbacks on RealtimeClient to the two broadcast streams onStatusChange and onMessage. Connection errors are emitted as stream errors on onStatusChange.

```dart
// Before
client.onOpen(() => print('open'));
client.onClose((event) => print('closed: $event'));
client.onError((error) => print('error: $error'));
client.onMessage((message) => print('message: $message'));

// After
client.onStatusChange.listen(
  (change) => switch (change.status) {
    RealtimeConnectionStatus.open => print('open'),
    RealtimeConnectionStatus.closed => print('closed: ${change.closeEvent}'),
  },
  onError: (error) => print('error: $error'),
);
client.onMessage.listen((message) => print('message: $message'));
```

--------------------------------

### RealtimeChannel onPostgresChanges and onBroadcast to streams

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Migrates RealtimeChannel.onPostgresChanges and onBroadcast from callback-based chaining to typed streams. The streams must be created before subscribe() but can be listened to at any time; repeated calls with the same arguments return the same stream.

```dart
// Before
supabase
    .channel('room')
    .onPostgresChanges(
      event: PostgresChangeEvent.insert,
      schema: 'public',
      table: 'messages',
      callback: (payload) => print(payload),
    )
    .onBroadcast(
      event: 'cursor-pos',
      callback: (payload) => print(payload),
    )
    .subscribe();

// After
final channel = supabase.channel('room');
channel
    .onPostgresChanges(
      event: PostgresChangeEvent.insert,
      schema: 'public',
      table: 'messages',
    )
    .listen(print);
channel.onBroadcast(event: 'cursor-pos').listen(print);
channel.subscribe();
```

--------------------------------

### Migrate SupabaseStreamBuilder.execute() to direct listen

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the migration from the removed `SupabaseStreamBuilder.execute()` method. `SupabaseStreamBuilder` is itself a `Stream`, so you can listen to it directly without calling `execute()`.

```dart
// Before
supabase.from('users').stream(primaryKey: ['id']).execute().listen(handle);

// After
supabase.from('users').stream(primaryKey: ['id']).listen(handle);
```

--------------------------------

### Run supabase_typegen to generate Dart types for Postgres databases

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_typegen/README.md

Commands to generate Dart types from a database connection or via the Supabase CLI. The first block shows the direct connection modes (--local, --linked, --project-ref, --db-url); the second shows the future CLI path that reads from stdin. All write lib/supabase_schema.g.dart unless --output is given.

```sh
# The database of the running local Supabase stack (`supabase start`).
dart run supabase_typegen --local

# The project linked with `supabase link`, or any project by ref.
dart run supabase_typegen --linked
dart run supabase_typegen --project-ref abcdefghijklmnopqrst

# Any Postgres database.
dart run supabase_typegen --db-url 'postgresql://postgres:…@db.…supabase.co:5432/postgres'
```

```sh
supabase gen types --lang dart --local > lib/supabase_schema.g.dart
```

--------------------------------

### Include analysis_options_flutter.yaml for Flutter packages

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_lints/README.md

Includes the shared lint rules for a Flutter package by referencing the analysis_options_flutter.yaml file from the supabase_lints package.

```yaml
include: package:supabase_lints/analysis_options_flutter.yaml
```

--------------------------------

### Stub table and query with supabase_test

Source: https://github.com/supabase/supabase-flutter/blob/main/README.md

Stub a database table and run queries against a real SupabaseClient without a running stack. Uses MockSupabaseHttpClient and testSupabaseClient from supabase_test; disposes the client with addTearDown.

```dart
final httpClient = MockSupabaseHttpClient()
  ..stubTable('todos', rows: [
    {'id': 1, 'task': 'Ship it', 'status': false},
  ]);
final supabase = testSupabaseClient(httpClient: httpClient);
addTearDown(supabase.dispose);

final todos = await supabase.from('todos').select();
expect(todos, hasLength(1));
```

--------------------------------

### Migrate retry parameters to SupabaseRetryOptions

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the migration from the old retry parameters to the unified SupabaseRetryOptions for both PostgrestClientOptions and StorageClientOptions. The count value carries over unchanged because the old retryAttempts counted the same way.

```dart
// Before
postgrestOptions: const PostgrestClientOptions(retryCount: 5),
storageOptions: const StorageClientOptions(retryAttempts: 5),

// After
postgrestOptions: const PostgrestClientOptions(
  retryOptions: SupabaseRetryOptions(count: 5),
),
storageOptions: const StorageClientOptions(
  retryOptions: SupabaseRetryOptions(count: 5),
),
```

--------------------------------

### Migrate RealtimePresence to channel API

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows the migration from the internal RealtimePresence class to the new channel-based API. The 'After' section uses onPresenceJoin, onPresenceLeave, onPresenceSync streams and presenceState() method.

```dart
// Before
channel.presence.onJoin((key, current, joined) { /* ... */ });
channel.presence.onLeave((key, current, left) { /* ... */ });
channel.presence.onSync(() { /* ... */ });
final Map<String, List<Presence>> state = channel.presence.state;

// After
channel.onPresenceJoin.listen((payload) { /* ... */ });
channel.onPresenceLeave.listen((payload) { /* ... */ });
channel.onPresenceSync.listen((payload) { /* ... */ });
final List<SinglePresenceState> state = channel.presenceState();
```

--------------------------------

### Opting into cross-tab session sync with persistSession

Source: https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md

Shows how to enable cross-tab session sync by setting persistSession to true in AuthClientOptions. Before, every client synced by default; after, it is opt-in.

```dart
// Before: every client synced its session across tabs.
final client = SupabaseClient(
  url,
  publishableKey,
  authOptions: AuthClientOptions(asyncStorage: MemoryAuthAsyncStorage()),
);

// After: opt in where the session should be shared.
final client = SupabaseClient(
  url,
  publishableKey,
  authOptions: AuthClientOptions(
    asyncStorage: MemoryAuthAsyncStorage(),
    persistSession: true,
  ),
);
```

--------------------------------

### Include analysis_options.yaml for Dart packages

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_lints/README.md

Includes the shared lint rules for a Dart package by referencing the analysis_options.yaml file from the supabase_lints package.

```yaml
include: package:supabase_lints/analysis_options.yaml
```

--------------------------------

### Initialize supabase_flutter for widget tests with initializeTestSupabase

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_test/README.md

Initializes supabase_flutter for widget tests using initializeTestSupabase from package:supabase_flutter/testing.dart. Applies the same test defaults as testSupabaseClient and takes the same mock HTTP client. The returned supabase instance should be disposed via addTearDown.

```dart
import 'package:supabase_flutter/testing.dart';

final supabase = await initializeTestSupabase(httpClient: httpClient);
addTearDown(supabase.dispose);
```

--------------------------------

### Register, sign in, and manage passkeys with supabase.auth

Source: https://github.com/supabase/supabase-flutter/blob/main/examples/passkeys/README.md

Shows the core passkey API calls: registerPasskey, signInWithPasskey, and the passkey management methods (list, update, delete). The WebAuthn ceremony is handled by supabase_flutter, including the platform prompt.

```dart
// Register a passkey for the signed in user.
await supabase.auth.registerPasskey();

// Sign in with a passkey.
await supabase.auth.signInWithPasskey();

// Manage passkeys with the server side API.
final passkeys = await supabase.auth.passkey.list();
await supabase.auth.passkey.update(passkeyId: passkeys.first.id, friendlyName: 'My phone');
await supabase.auth.passkey.delete(passkeyId: passkeys.first.id);
```

--------------------------------

### Lint and format the workspace with melos

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Run the analyzer across the whole workspace with `melos analyze`. Format code with `melos format`, which uses an 80-character line length configured in the root pubspec.yaml.

```bash
melos analyze

```

```bash
melos format

```

--------------------------------

### Native Apple Sign In with sign_in_with_apple

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_flutter/README.md

Performs native Apple sign-in on iOS or macOS using the sign_in_with_apple package. Requires adding the app's bundle ID to the Supabase dashboard under Authentication -> Providers -> Apple. Generates a raw nonce, hashes it, and exchanges the Apple ID token for a Supabase session.

```dart
import 'package:sign_in_with_apple/sign_in_with_apple.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

/// Performs Apple sign in on iOS or macOS
Future<Session> signInWithApple() async {
  final rawNonce = supabase.auth.generateRawNonce();
  final hashedNonce = sha256.convert(utf8.encode(rawNonce)).toString();

  final credential = await SignInWithApple.getAppleIDCredential(
    scopes: [
      AppleIDAuthorizationScopes.email,
      AppleIDAuthorizationScopes.fullName,
    ],
    nonce: hashedNonce,
  );

  final idToken = credential.identityToken;
  if (idToken == null) {
    throw const AuthException(
        'Could not find ID Token from generated credential.');
  }

  return signInWithIdToken(
    provider: OAuthProvider.apple,
    idToken: idToken,
    nonce: rawNonce,
  );
}
```

--------------------------------

### MockSupabaseHttpClient.stubTable

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase_test/README.md

Registers a stub for database reads and writes on the `/rest/v1/<table>` endpoint.

```APIDOC
## MockSupabaseHttpClient.stubTable

### Description
Registers a stub for database reads and writes on the `/rest/v1/<table>` endpoint. The stub answers requests with the provided rows, optionally filtered by query parameters and limited by `times`.

### Method
N/A (SDK method)

### Endpoint
`/rest/v1/<table>`

### Parameters
- **table** (String) - Required - The name of the table to stub.
- **rows** (List<Map<String, dynamic>>) - Optional - The rows to return. Can be a list of maps or a single map for error responses.
- **query** (Map<String, String>) - Optional - Query parameters that must match for the stub to answer.
- **schema** (String) - Optional - The schema to match. If omitted, the stub answers for any schema.
- **times** (int) - Optional - Limits how many times the stub answers.
- **statusCode** (int) - Optional - The HTTP status code to return. Defaults to 200.
- **count** (int) - Optional - The count to return when the query requests a count.

### Request Example
```dart
httpClient.stubTable('todos', rows: [
  {'id': 1, 'task': 'Ship it', 'status': false},
]);
```

### Response
#### Success Response (200)
- **rows** (List<Map<String, dynamic>>) - The stubbed rows.

#### Response Example
```json
[
  {"id": 1, "task": "Ship it", "status": false}
]
```

### Error Handling
- If `statusCode` is set, the stub returns that status code with the provided error body. For example, a 403 with `{'message': 'permission denied', 'code': '42501'}` causes `PostgrestApiException`.
```

--------------------------------

### Configure HTTP client with 60-second idle timeout

Source: https://github.com/supabase/supabase-flutter/blob/main/packages/supabase/README.md

Create an IOClient with a custom idle timeout of 60 seconds to keep connections open longer than the default 15 seconds. This is useful when sharing a single http.Client across multiple SupabaseClient instances.

```dart
import 'dart:io';

import 'package:http/io_client.dart';

final httpClient = IOClient(
  HttpClient()..idleTimeout = const Duration(seconds: 60),
);
```

--------------------------------

### Update versions and generate changelogs with melos

Source: https://github.com/supabase/supabase-flutter/blob/main/AGENTS.md

Update version.dart files for all packages with `melos run update-version`. Version packages and generate changelogs with `melos version` (handled by melos).

```bash
melos run update-version

```

```bash
melos version

```
Tokens:
Raw