Block controllers

Every block hook, such as useNotifications or useCommandSearch, is a thin wrapper over a controller: a plain TypeScript object that loads the block's data, follows its realtime topic and runs its actions. Controllers import no React, DOM or React Native code, so the same hook runs in React DOM and React Native, and a Vue, Svelte or Solid UI can use the controller directly.

The contractCopy Anchor Link

A controller has four members, the external-store contract that React's useSyncExternalStore and the other frameworks' stores expect:

import { createNotificationsController } from "better-supabase/blocks/notifications";
import { topicPort } from "better-supabase/realtime";

const unread = createNotificationsController({
  auth: bs.auth,
  ports: { topic: topicPort(bs.supabase) },
  topic: `notifications:${userId}`,
  load: () => listNotifications(),
});

const stop = unread.subscribe(() => {
  badge.textContent = String(unread.getSnapshot().count);
});

A Vue binding is a shallowRef that subscribe updates; a Svelte one is a readable store whose start function returns the unsubscribe.

Controllers by blockCopy Anchor Link

Each block exports its controllers from its main entry, better-supabase/blocks/<name>. The hooks in better-supabase/blocks/<name>/react build them from the provider's client.

Controllers with a moving input take it as an action instead of starting over: setRange on the calendar and bookings controllers and setSubjects on the reactions controller keep the shown data until the new data arrives.

PortsCopy Anchor Link

A controller reaches the platform only through ports, small interfaces the client carries in bs.ports. createClient from better-supabase/client fills the web ones; a React Native app passes nativePorts() from better-supabase/client/native to createNativeClient.

The topic port defaults to topicPort(bs.supabase) from better-supabase/realtime when bs.ports has none. A port the platform lacks stays unset, and the controller works without it: useCommandSearch on a phone has no Cmd+K.

import { createNativeClient, nativePorts } from "better-supabase/client/native";
import AsyncStorage from "@react-native-async-storage/async-storage";
import * as Linking from "expo-linking";
import * as Notifications from "expo-notifications";

export const bs = createNativeClient(betterSupabase, supabase, {
  ports: nativePorts({
    supabase,
    storage: AsyncStorage,
    linking: Linking,
    notifications: Notifications,
    projectId: process.env.EXPO_PUBLIC_EAS_PROJECT_ID,
  }),
});

On the web, createClient(betterSupabase, { env, ports }) merges your ports over the defaults, for example a push port with your VAPID key:

import { createClient, webPushToken } from "better-supabase/client";

export const bs = createClient(betterSupabase, {
  env,
  ports: { push: webPushToken({ vapidPublicKey: env.vapidPublicKey }) },
});

Testing a controllerCopy Anchor Link

Pass fakes for the client and the ports, subscribe once, and read the snapshot. No renderer is needed:

import { createNotificationsController } from "better-supabase/blocks/notifications";

const joined: string[] = [];
const controller = createNotificationsController({
  auth: { current: () => signedIn, subscribe: () => () => undefined },
  ports: {
    topic: (topic, watch) => {
      joined.push(topic);
      watch.onStatus("subscribed");
      return { leave: () => undefined, send: () => undefined };
    },
  },
  topic: "notifications:u1",
  load: async () => [{ id: "n1", readAt: null }],
});
const stop = controller.subscribe(() => undefined);
await Promise.resolve();
expect(controller.getSnapshot().count).toBe(1);
stop();

defineController and whileSignedIn from better-supabase/client build controllers of your own the same way.