Make great apps with a great backend!

Supabase is an open source Firebase alternative. It has support for auth, database and storage updates. The goal of this package is to make things easier when using supabase.

Get started

Add the dependencies to your pubspec.yaml file:

  supabase: <latest-version>
  supabase_addons: <latest-version>

Import both supabase and supabase_addons:

import 'package:supabase/supabase.dart';
import 'package:supabase_addons/supabase_addons.dart';

First of all, we need to init the addons:

await SupabaseAddons.initialize(
  client: SupabaseClient(SUPABASE_URL, SUPABASE_SECRET),

After eveything is used, you have to dispose the addons. Failure to do so can result in performance issues:


Auth Addons

The auth addon is able to persist the user session into the device storage. It is backed by hive, a lightweight and blazing fast key-value database written in pure Dart

How it works?

The user session is persisted on the device everytime the user signs in or is updated. When the user signs out, the session is removed from the device.

This behavior is enabled by default when SupabaseAddons.initialize is called. To disable it, call SupabaseAuthAddons.dispose(). Once disabled, it can't be turned on anymore

Change the storage path

When initializing the addons, you can change the storagePath to the location you'd like:

  authPersistencePath: './auth'

If you're in a Flutter environment, you can use the package path_provider to get the application documents path:

import 'package:path_provider/path_provider.dart';

final dir = await getApplicationDocumentsDirectory()

  authPersistencePath: '${dir.path}/auth'


Analytics is a database-addon.

Analytics provides insight on app usage and user engagement. Its reports help you understand clearly how your users behave, which enables you to make informed decisions regarding app marketing and performance optimizations.

Get started with Analytics

Create a table called analytics on the database:

create table (
  name text not null,
  params json,
  user_id text,
  timestamp text

Initialize the analytics addon:


Log an event

After initialized, you can log the events using SupabaseAnalyticsAddons.logEvent.

You can pass three arguments:

  • required name, the event name. It can't have any spaces. If any, they are replaced by _.
  • params, the event info. It's not required to have params, but it's good to have when rendering the graphics. The more info, the better
  • userId, the user id on the event. If not provided, the current session is used
SupabaseAnalyticsAddons.logEvent('goal_completion', params: {
  'name': 'lever_puzzle',

Auth events

When the user is signed in or signed up, the user_session event is triggered automatically.

You can disable the automatic logging when initializing by passing logUserSignIn: false.

The user_session has some useful information on the params field:

  • country_code, the user country.
  • os, the user operating system. This is a String representing the operating system or platform. This is powered by (Platform.operatingSystem)

Built-in events

This addon provides a lot of built-in events that can be analized in the analizer:

purchaseaffiliation, coupon, currency, items, shipping, tax, transactionId, valuelogPurchase()An AssertionError is thrown if the currency couldn't be fetched
refundaffiliation, coupon, currency, items, shipping, tax, transactionId, valuelogRefund()An AssertionError is thrown if the currency couldn't be fetched
ad_impressionformat, providerlogAdImpression()
screen_viewscreenClass, screenNamelogScreenViewThis should be handled automatically if supabase_addons_flutter is used
searchterm (required), paramslogSearch()
select_itemitem (required)logSelectItem()


Crashlytics is a crash reporter that helps you track, prioritize, and fix stability issues that erode your app quality.

Get started with Crashlytics

Create a table called crashlytics on the database:

create table public.crashlytics (
  id uuid DEFAULT gen_random_uuid() primary key not null,
  exception text not null,
  stackTraceElements json,
  timestamp text not null,
  info json

Initialize the crashlytics addon:


Toggle Collection

import 'package:flutter/foundation.dart' show kDebugMode;

if (kDebugMode) {
  // Force disable collection while doing every day development.
  // Temporarily toggle this to true if you want to test crash reporting in your app.
  SupabaseCrashlyticsAddons.collectionEnabled = false;
} else {
  // Handle Crashlytics enabled status when not in Debug,
  // e.g. allow your users to opt-in to crash reporting.

Recording an error

To record an error with custom information, you can wrap the code in a try/catch block:

import 'package:flutter/foundation.dart' show kDebugMode;

try {
  // code that may throw an exception
} catch (error, stacktrace) {
    reason: 'The user is very dumb', // the reason goes here
    fatal: false, // whether the error is fatal, such as an app crash
    printDetails: kDebugMode, // whether the error should be printed to the console. Usually only on debug mode

Handling uncaught errors

If you're using Flutter, you can catch and report all the errors from the framework by redefining FlutterError.onError with the following function:

FlutterError.onError = (details) {
  FlutterError.dumpErrorToConsole(details, forceReport: true);

    reason: details.context,
    printDetails: false,

To catch any other exception that may happen in your program, wrap the dart program in a runZonedGuarded:

void main() async {
  runZonedGuarded<Future<void>>(() async {
    // the rest of your code goes here
  }, (error, stacktrace) {
    SupabaseCrashlyticsAddons.recordError(error, stacktrace);

Features and bugs

Please file feature requests and bugs at the issue tracker.


Support for doing something awesome.