supabase/supabase-flutter

This system is a comprehensive Dart and Flutter SDK for interacting with Supabase services, providing clients for authentication, database queries, real-time subscriptions, storage, and edge functions. It features a modernized v3 architecture with typed query builders, stream-based APIs, and support for advanced capabilities like passkeys, vector search, and Iceberg analytics. The repository also includes a suite of example applications and testing utilities to facilitate local development and integration testing against a Supabase stack.

24 changes.

This period focused on migrating the SDK to version 3 by restructuring the codebase into a Melos monorepo and introducing a typed PostgREST client with compile-time safety. The work involved removing legacy singleton patterns and deep-linking helpers while adding comprehensive test coverage and cross-platform support for the example applications.

35 changes.

This period focused on modernizing the Supabase Dart SDK by introducing shared infrastructure, rewriting the Realtime client for protocol v2, and adding new packages for Iceberg and passkeys. It also significantly expanded the developer experience by providing a comprehensive suite of runnable examples and a local testing launcher for all major Supabase features.

The example application now includes the necessary Linux platform files (CMake build configuration, GTK application entry points, and plugin registrants) to be built and run as a native Linux desktop application.

_packages/supabase\flutter/example/linux · high confidence

An example file demonstrating how to initialize the PostgrestClient, query a table, and handle PostgrestApiException has been added to the package.

packages/postgrest/example · high confidence

The example application directory now includes essential configuration files to support development and analysis. A \.gitignore\ file is added to exclude standard build artifacts and IDE-specific files, while a \.metadata\ file tracks the Flutter project version and migration state for supported platforms. An \analysis\_options.yaml\ file configures the Dart analyzer to use \supabase\_lints\ and explicitly disables the single-widget-per-file rule to accommodate the demo's structure. Additionally, a \README.md\ provides setup instructions, including SQL scripts for creating the necessary database tables, policies, and storage buckets required for the profile management demo.

_packages/supabase\flutter/example · high confidence

An example file has been added to the yet\_another\_json\_isolate package, showing how to initialize a YAJsonIsolate instance, decode a JSON string, encode the resulting object back to JSON, and properly dispose of the isolate.

_packages/yet\_another\_json\isolate/example · high confidence

The macOS platform is now supported in the \supabase\_flutter\ example application. This change introduces the complete native Xcode project structure, including the \Runner\ target, app icons, and menu bar interface, along with the necessary Flutter configuration files (xcconfigs) and entitlements for sandboxing. It also registers native plugins such as \app\_links\, \shared\_preferences\_foundation\, and \url\_launcher\_macos\ via the generated plugin registrant, enabling users to test the library's functionality on macOS.

_packages/supabase\flutter/example/macos · high confidence

A new internal mapper in the passkey module converts WebAuthn registration and authentication options from the Supabase API into formats compatible with the underlying \passkeys\ plugin. This ensures that challenges and credential IDs have base64url padding stripped and that all credentials include a required \transports\ list, preventing validation errors during passkey ceremonies.

_packages/supabase\flutter/lib/src/passkey · high confidence

A new web example has been added to the Supabase package, providing a complete, runnable demonstration of the client library in a browser environment. The example includes an HTML entry point, CSS styling, and a Dart entry point that showcases core Supabase capabilities such as querying and mutating data, using real-time change listeners, leveraging data streams, and performing file uploads and downloads via the Storage API.

packages/supabase/example/web · high confidence

The example application now includes a complete Windows runner, enabling users to build and run the app on Windows desktop. This addition provides the necessary CMake build configuration, a Win32 window implementation with high-DPI awareness, and automatic registration of the \app\_links\ and \url\_launcher\_windows\ plugins.

_packages/supabase\flutter/example/windows · high confidence

A new script, scripts/customer\_testing.dart, has been added to support the Flutter tests registry. This script enables the supabase-flutter repository to be tested as a presubmit against changes in the flutter/flutter framework. It performs static analysis on the entire repository and runs unit tests specifically for the supabase\_flutter package, excluding other packages that require a live backend to ensure hermetic execution.

scripts · high confidence

A new \supabase\_lints\ package has been added to provide a centralized linting configuration for Supabase Dart and Flutter packages. It includes a base \analysis\_options.yaml\ that extends \package:lints/recommended.yaml\ and enables specific rules such as \unawaited\_futures\, \discarded\_futures\, \lines\_longer\_than\_80\_chars\, and \sort\_constructors\_first\. It also configures the Dart Code Metrics (DCM) \recommended\ preset, specifically enforcing WASM compatibility by banning \dart:html\, \dart:js\, \dart:js\_util\, and \dart:ffi\ imports in library code (except conditional \\_io.dart\ files). A separate \analysis\_options\_flutter.yaml\ is provided for Flutter packages, which includes the base Dart config plus \package:flutter\_lints/flutter.yaml\.

_packages/supabase\lints/lib · high confidence

The \supabase\_functions\ package now provides a standalone \FunctionsClient\ for invoking Edge Functions, independent of the main Supabase client. This client supports per-request access token resolution, configurable JSON encoding via \AsyncJsonCodec\, and request abortion via \abortSignal\. Error handling is unified under a new sealed \FunctionException\ hierarchy, allowing users to distinguish between network failures (\FunctionsFetchException\), API errors (\FunctionsApiException\), and relay errors (\FunctionsRelayException\).

_packages/supabase\functions/lib · high confidence

The repository now includes the \supabase\_test\ package, providing test helpers like \MockSupabaseHttpClient\ and \testSupabaseClient\ to simplify testing applications against the SDK without a running backend. This is documented in the updated README, which also clarifies local development setup using Melos and the Supabase CLI. Additionally, the repository now contains \AGENTS.md\ for AI assistant guidance, \MIGRATION.md\ for v2-to-v3 breaking changes, \.coderabbit.yaml\ for code review configuration, and \.sdk-parse-ignore\ to refine the public API capability matrix scan.

(repo-wide) · high confidence

The new \supabase\_test\ package provides a \MockSupabaseHttpClient\ and \MockRealtimeTransport\ to allow testing Supabase-dependent code without a live backend. It includes a \testSupabaseClient\ helper for wiring mocks, shorthands for stubbing PostgREST tables and RPCs, and fixtures for generating test JWTs and session data.

_packages/supabase\test/lib · high confidence

Added a new Flutter example application in \examples/edge\_functions\ that demonstrates how to invoke Supabase Edge Functions using \supabase.functions.invoke(...)\. The app showcases calling functions with JSON bodies over POST, passing query parameters over GET, sending custom headers, handling plain text responses, and managing errors via \FunctionException\. It includes a \FunctionsRepository\ to separate API logic from the UI, along with a full end-to-end integration test suite (\functions\_test.dart\ and \invoke\_test.dart\) that verifies request methods, body types, response formats, and error handling against a local Supabase stack.

_examples/edge\functions · high confidence

This release introduces the \iceberg\ package, providing a Dart client for the Apache Iceberg REST Catalog exposed by Supabase Storage. The library includes the \IcebergRestCatalog\ class to manage namespaces and tables within an analytics bucket, along with comprehensive type definitions for schemas, table updates, and requirements. It features a structured error hierarchy (e.g., \IcebergNotFoundException\, \IcebergConflictException\) for robust error handling and integrates with the Supabase logging hierarchy for consistent observability.

packages/iceberg/lib · high confidence

Added a new Flutter example application (\examples/realtime\_room\) that showcases Supabase Realtime's three core features in a live chat room interface. The app uses Postgres Changes to keep the message log in sync across clients, Broadcast for ephemeral typing indicators, and Presence to track the online user roster. The example includes a complete implementation with a \RoomChannel\ for realtime subscriptions, a \RoomRepository\ for database operations, and an end-to-end integration test (\integration\_test/room\_test.dart\) that validates the full user flow.

_examples/realtime\room · high confidence

Added a new Flutter example application in \examples/storage\_transforms\ that demonstrates uploading images to a Supabase Storage bucket, listing them, and applying server-side image transformations (resizing, cropping, quality adjustment) via \TransformOptions\ when generating public URLs or downloading files. The example includes a gallery UI, a detail view showing multiple transformation variants, and an end-to-end integration test verifying the upload, transform, download, and delete workflow.

_examples/storage\transforms · high confidence

The \examples/authentication\ directory now contains a complete Flutter application that serves as a reference for implementing Supabase authentication. This example demonstrates every \supabase\_flutter\ sign-in method except passkeys, including email & password, magic links, email OTP, phone SMS OTP, OAuth social providers (Google, GitHub, Apple), anonymous sign-in with account upgrading, and multi-factor authentication (TOTP). It includes a dedicated \AuthRepository\ to separate auth logic from the UI, an end-to-end integration test suite covering these flows against a local Supabase stack, and configuration for local development using a mail server and test OTPs.

examples/authentication · high confidence

Added a new Flutter example application demonstrating how to perform Create, Read, Update, and Delete (CRUD) operations against a Supabase database using PostgREST. The example includes a task manager UI that showcases filtering, ordering, and joining data, along with an end-to-end integration test to verify the functionality.

_examples/database\crud · high confidence

A new command-line launcher has been added to the examples directory to simplify running Flutter examples with a local Supabase stack. The tool automatically detects and starts the local Supabase environment, presents an interactive menu for users to select which example to run, and forwards execution arguments to Flutter. It handles credential passing via dart-define and ensures the local Supabase instance is stopped when the launcher exits, providing a streamlined workflow for testing examples locally.

examples/launcher · high confidence

The \supabase\_flutter\_web\_auth\ package is now available as an opt-in solution to replace the default browser-based OAuth flow with a system web authentication session (ASWebAuthenticationSession on iOS/macOS, Custom Tabs on Android). This change means that when users configure the \FlutterWebAuth2OAuthLauncher\, the authentication window automatically closes upon redirect, preventing the blank-page issue of the previous default behavior, and shares cookies with the system browser on mobile platforms to allow seamless single sign-on. On Linux and Windows, the flow runs in an embedded webview. The package includes an example app demonstrating the setup and tests verifying the OAuth code exchange and ephemeral session options.

_packages/supabase\_flutter\_web\auth · high confidence

A new Flutter web example application has been added to the \examples/passkeys\ directory, demonstrating how to use the \supabase\_flutter\ package for passkey (WebAuthn) authentication. The app allows users to sign up with email and password, register a passkey, and subsequently sign in using that passkey without a password. It also includes functionality to list, rename, and delete registered passkeys. The example is configured to work with a shared local Supabase stack via the examples launcher and includes an end-to-end integration test to verify the sign-up and sign-in flows.

examples/passkeys · high confidence

Developers can now run all \supabase\_flutter\ examples against a single, shared local Supabase instance using the new launcher (\./run.sh\). This setup includes a pre-configured \config.toml\ that enables authentication (email, phone, OAuth, MFA, passkeys), Edge Functions, Storage with image transforms, and Realtime subscriptions, along with the necessary database migrations and seed data to demonstrate these features out of the box.

examples/supabase · high confidence

The \supabase\_typegen\ package is now available to generate typed Dart table definitions from your database schema, eliminating raw \Map\<String, dynamic\>\ data in query results. It introspects the database through the Supabase CLI (supporting local, linked, or direct connection modes) and emits Dart code including row extension types, \Insert\ and \Update\ value types, column tokens, and Postgres enum mappings. This tool serves as a bridge until native Dart support is added to the \supabase gen types\ CLI command.

_packages/supabase\typegen · high confidence

The \supabase\_flutter\ package now exposes a \testing.dart\ library containing \initializeTestSupabase\, a helper that configures Supabase for unit and widget tests by using in-memory session persistence, disabling token auto-refresh and deep-link detection, and defaulting to an unsigned test key. The main \supabase\_flutter.dart\ entry point has been restructured to explicitly export the new \FlutterAuthClientOptions\, \OAuthLauncher\, \SharedPreferencesAuthAsyncStorage\, \SupabaseAuth\, \SupabasePasskey\, and \SupabaseRestoreCredential\ components, ensuring these specific integration pieces are available to consumers.

_packages/supabase\flutter/lib · high confidence

The PostgREST client has been refactored to introduce a new typed query builder surface. The previous untyped \from()\ method remains for raw queries, but a new \table()\ method is now available to create typed builders that enforce compile-time checks on row, insert, and update types. This new surface uses \PostgrestColumn\ expressions for filters, ordering, and selections, preventing invalid column references at compile time. The change also includes a new \PostgrestFilter\ API for composing complex queries with \&\, \\|\, and \not\, and supports embedded relations for to-one and to-many joins. The client is now stateless, with configuration passed through immutable request configs, and includes support for aggregate functions, JSON paths, and casts within the typed expression system.

packages/postgrest/lib · high confidence

The \supabase\_auth\ package now includes an experimental MFA recovery codes API (\AuthClient.mfa.recoveryCodes\) allowing users to generate, verify, and manage single-use backup codes for authentication. Additionally, the Admin API (\AuthClient.admin\) has been expanded with dedicated namespaces for managing OAuth 2.1 clients (\oauth\) and custom OIDC/OAuth providers (\customProviders\), enabling server-side creation, listing, and deletion of these entities. The package also adds experimental support for passkey administration (\admin.passkey\) and user passkey management (\passkey\), alongside a new example demonstrating the \AuthClient\ usage with PKCE flow and persistent storage.

_packages/supabase\auth/lib · high confidence

This release updates the Supabase Dart client to version 3.0.0-dev.5, introducing several key capabilities. New-format API keys (prefixed with \sb\publishable\\ or \sb\secret\\) are now recognized and automatically excluded from the \Authorization: Bearer\ header to prevent authentication errors, while unrecognized \sb\_\ keys trigger a warning. The PostgREST client now supports typed table access via \SupabaseClient.table()\ and \SupabaseTypedQueryBuilder\, enabling type-safe realtime streams that convert rows into specific Dart classes. Additionally, the client supports opt-in W3C trace context propagation for distributed tracing, configurable realtime JSON encoding/decoding (e.g., for background isolates), and a new \disconnectOnEmptyChannelsAfter\ option to manage realtime socket lifecycle.

packages/supabase/lib/src · high confidence

The \supabase\_storage\ package has been updated to version 3.0.0-dev.4, introducing several new capabilities and behavioral changes. Users can now enable object versioning on buckets and configure lifecycle policies to automatically expire old versions. The client also adds an experimental Vectors API for managing vector buckets and indexes, and an Iceberg REST Catalog client for analytics buckets. Upload and download operations now support an \abortSignal\ parameter to cancel in-flight requests, and file paths are consistently normalized to prevent URL corruption. Additionally, the client supports resolving access tokens per request and offers an opt-in rewrite of legacy storage URLs to the dedicated storage host.

_packages/supabase\storage/lib · high confidence

The \lib/src\ directory has removed the legacy singleton \Supabase\ class, the \SupabaseAuthState\ mixin, and supporting files for deep linking and lifecycle management. This eliminates the previous implementation that relied on \SharedPreferences\ for session persistence and manual deep-link handling, signaling a shift away from these specific internal components.

lib/src · high confidence

The \supabase\_common\ package now provides a unified foundation for all Supabase Dart clients by centralizing shared logic. This includes a centralized retry mechanism with exponential backoff and jitter, an HTTP client wrapper that resolves access tokens per request, and standardized error handling via a new \SupabaseException\ hierarchy. The update also introduces shared utilities for PKCE flow handling, secure random generation, timestamp parsing, and credential redaction in logs, ensuring consistent behavior and security across the SDK.

_packages/supabase\common/lib/src · high confidence

A new supabase\_common package has been introduced to centralize shared internal utilities across the Supabase client ecosystem. This change extracts common code—such as HTTP handling, authentication callbacks, retry logic, and testing configurations—into a single location to prevent duplication and ensure consistency between different client packages. While this package is not intended for direct consumption by end-users, it underpins the behavior of the main Supabase clients by providing standardized implementations for core networking and utility functions.

_packages/supabase\common/lib · high confidence

The default HTTP transport used by the Supabase client now maintains idle connections for 60 seconds on \dart:io\ platforms (desktop and mobile) before closing them. This change reduces latency for subsequent requests by reusing existing TCP and TLS connections, aligning with the Supabase gateway's idle timeout behavior. On web platforms, the default browser-owned client remains unchanged.

_packages/supabase\common/lib/src/platform · high confidence

The \supabase\_flutter\ auth integration has been refactored to support pluggable OAuth launchers (defaulting to \UrlLauncherOAuthLauncher\ via \FlutterAuthClientOptions.oauthLauncher\) and improved deep-link handling. A new \clear\_auth\_url\_parameters\ module now strips authentication parameters from the browser URL after code exchange to prevent refresh errors, while \SupabaseAuth\ coordinates deep-link observation with session restoration. Session persistence now uses \SharedPreferencesAuthAsyncStorage\ with automatic migration from the legacy \SharedPreferences\ API, and web-specific hot-restart cleanup ensures WebSocket and BroadcastChannel resources are properly disposed.

_packages/supabase\flutter/lib/src · high confidence

The \supabase\_realtime\ package has been completely rewritten, replacing the previous callback-based API with Dart streams for all event listeners (e.g., \onPostgresChanges\, \onBroadcast\, \onPresence\). The library now defaults to the Realtime protocol version 2.0.0, which uses positional JSON arrays and supports binary WebSocket frames for lower latency and binary broadcast payloads, while still supporting the legacy v1.0.0 object-shaped frames. Internal implementation details have been restructured into a new file layout (e.g., \constants.dart\, \logger.dart\, \serializer.dart\), and logging is now centralized through the \package:logging\ hierarchy under the \supabase\ logger.

_packages/supabase\realtime/lib · high confidence

The main library entry point \lib/supabase\_flutter.dart\ has been removed, meaning users can no longer import the entire Supabase Flutter package via a single file. Previously, this file re-exported \src/supabase.dart\, \src/supabase\_auth\_state.dart\, \src/supabase\_deep\_linking\_mixin.dart\, and \src/supabase\_lifecycle\_state.dart\. Users must now import these specific modules individually or rely on other consolidated exports.

lib · high confidence

The Supabase client library has been restructured for version 3, consolidating related packages into a unified interface. The main entry point now exports renamed sub-packages (supabase\_auth, supabase\_storage, supabase\_realtime, supabase\_functions) alongside PostgREST. This update introduces typed table access via PostgrestTable and TableColumn, opt-in trace context propagation headers for observability, and stricter stream filtering rules. Deprecated APIs have been removed, and the library now uses a shared HttpMethod enum across packages.

packages/supabase/lib · high confidence

The Supabase local development environment is now configured with a dedicated set of non-ephemeral ports (14420–14429) to prevent binding conflicts with the host's default ephemeral range, and it uses a fixed RS256 signing key to ensure deterministic JWT generation across restarts. The setup includes seed data for users, channels, messages, and storage buckets to support integration testing, and enables vector storage buckets for local development.

supabase · high confidence

The Android example app's native configuration has been updated to align with modern Flutter standards. The Gradle wrapper has been upgraded to version 9.3.1, and the AndroidManifest.xml now explicitly declares the INTERNET permission for debug and profile builds to support hot reload and debugging. Additionally, the app now includes a \<queries\> block to handle text processing intents, and the Android embedding version is explicitly set to 2 in the manifest.

_packages/supabase\flutter/example/android · high confidence

The Supabase Flutter example application has been updated to reflect recent API changes. It now initializes the client using the new \publishableKey\ parameter instead of the previous \anonKey\, and includes a required \onError\ handler in the \onAuthStateChange\ stream listener to prevent unhandled exceptions during network failures.

_packages/supabase\flutter/example/lib · high confidence

The iOS example app for supabase\_flutter has been regenerated to align with current Flutter tooling standards. The minimum deployment target is now iOS 13.0, and the project includes updated Xcode workspace and scheme configurations, a standard Swift AppDelegate, and a basic test target to ensure the example builds and runs correctly out of the box.

_packages/supabase\flutter/example/ios · high confidence

The library has been refactored to route all JSON encoding and decoding through the new \AsyncJsonCodec\ interface, allowing users to supply custom implementations (e.g., for native parsers or instrumentation). On the IO platform, the implementation now uses an adaptive strategy: small payloads (under 64 KB) are processed inline to avoid isolate overhead, while large payloads are offloaded to short-lived isolates to prevent blocking the main event loop. The web platform variant continues to process all work inline, as isolates are not available. The public API remains compatible, but the internal architecture has shifted from a persistent isolate model to this on-demand, size-aware approach.

_packages/yet\_another\_json\isolate/lib · high confidence

Added browser tests for BroadcastChannel session synchronization; Added comprehensive test suite for Supabase Storage client; Added comprehensive test suite for yet\_another\_json\_isolate; Added integration and unit tests for the supabase\_auth package; Added local stack test configuration constants; Added test suite for Supabase client API key handling and configuration; Added tests for FunctionsClient error handling and custom HTTP client behavior; Added tests for Iceberg catalog REST API integration; Added tests for authentication type models and error handling; Added tests for the Supabase test harness capabilities; Added unit tests for supabase\_common utilities; Comprehensive test suite for supabase\_auth package; Expanded test coverage for Supabase Flutter initialization, authentication, and session management; Expanded test coverage for Supabase Realtime client; New database migration scripts for integration testing; Removed obsolete Supabase singleton initialization test.

The Supabase Dart and Flutter client packages have been upgraded to require Dart SDK 3.9.0 and Flutter 3.35.0, aligning with the latest platform capabilities. The repository structure has been reorganized into a Melos monorepo workspace, introducing new packages such as \supabase\_lints\ for shared linting, \supabase\_test\ for testing utilities, and \iceberg\ for storage analytics. This migration updates the dependency graph across all packages (e.g., \supabase\, \supabase\_flutter\, \postgrest\) to use version 3.0.0-dev.5 and integrates \supabase\_flutter\_web\_auth\ for improved OAuth flows.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 61.

• Code Health 94
• Architecture 99
• Maturity 62
• Readiness 49
• Security 63
• Domain Modelling 100

• 300 commits — 245 feature/other, 55 fixes

• .github/workflows — 36 commits
• packages/postgrest — 35 commits
• packages/gotrue — 34 commits
• (root) — 26 commits
• packages/supabase_auth — 22 commits
• packages/supabase_flutter — 21 commits
• packages/realtime_client — 20 commits
• packages/storage_client — 18 commits
• packages/supabase — 17 commits
• packages/supabase_realtime — 9 commits
• packages/supabase_storage — 9 commits
• packages/supabase_test — 9 commits
• packages/supabase_common — 8 commits
• packages/functions_client — 5 commits
• packages/supabase_typegen — 4 commits
• packages/yet_another_json_isolate — 4 commits
• examples/database_crud — 3 commits
• packages/supabase_functions — 3 commits
• .github/dependabot.yml — 2 commits
• examples/authentication — 2 commits

• fix: chore: enable strict-raw-types in supabase_lints and fix all violations (#1582)
• fix: chore: fix the analyzer issues from Flutter 3.47 (#1705)
• fix: ci(examples): fix the example integration test jobs (#1643)
• fix: fix!: make order() default to ascending (#1658)
• fix: fix!: release retained resources on dispose (#1668)
• fix: fix!: return unmodifiable header views with controlled replacement (#1764)
• fix: fix(auth)!: only open the broadcast channel when the session is persisted (#1804)
• fix: fix(auth)!: parse OAuth clients without a name (#1854)
• fix: fix(auth)!: return Uri from getSSOSignInUrl instead of String (#1722)
• fix: fix(auth): fail with an AuthException when a redirect response has no url (#1728)
• fix: fix(auth): guard startAutoRefresh against use after dispose (#1760)
• fix: fix(auth): parse OAuth authorization details for users without an email (#1844)
• fix: fix(auth): parse expires_in as num in Session.fromJson (#1716)
• fix: fix(functions): don't lose error status on a non-JSON body labeled JSON (#1507)
• fix: fix(functions): drain error responses with a streaming content type (#1480)
• fix: fix(functions): never send new-format API key as Bearer; warn on unrecognized sb_ key subtype (#1615)
• fix: fix(gotrue)!: assert asyncStorage is provided for PKCE flow in the constructor (#1489)
• fix: fix(gotrue)!: emit userUpdated instead of signedIn when an email change is confirmed (#1664)
• fix: fix(gotrue): OAuth server throws FormatException instead of ArgumentE… (#1535)
• fix: fix(gotrue): allow TOTP MFA enrollment without an issuer (#1501)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

supabase/supabase-flutter was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.