Getting Started

Installation

Inside your React project directory, run the following:

pnpm add @supabase-cache-helpers/postgrest-swr

If your package manager does not install peer dependencies automatically, you will need to install them, too.

pnpm add swr react @supabase/postgrest-js

pnpm add @tanstack/react-query react @supabase/postgrest-js

Quick Start

Import useQuery and define a simple query. The cache key is automatically created from the query. You can pass the SWR- and React Query-native options as a second argument. For pagination and infinite scroll queries, use useInfiniteOffsetPaginationQuery, useOffsetInfiniteScrollQuery and useCursorInfiniteScrollQuery.

import { useQuery } from "@supabase-cache-helpers/postgrest-swr";
 
const client = createClient<Database>(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);
 
function Page() {
  // Define the query, and its automatically parsed into an unique cache key.
  // `count` queries are supported, too
  const { data, count } = useQuery(
    client
      .from("contact")
      .select("id,username,ticket_number", { count: "exact" })
      .eq("username", "psteinroe"),
    {
      revalidateOnFocus: false,
      revalidateOnReconnect: false,
    }
  );
  return <div>...</div>;
}

Somewhere in your app, import useInsertMutation and define a mutation. For the automatic cache population to work, you need to pass the primary key(s) of the relation as a second argument. To return data from the mutation, pass a .select('...') string as the third argument. Pass null to skip. The fourth argument is the SWR- and React Query-native options object. The mutation will automatically update the query cache of the contact query defined above. Other operations are supported with useUpsertMutation, useUpdateMutation and useDeleteMutation.

import { useInsertMutation } from "@supabase-cache-helpers/postgrest-swr";
 
const client = createClient<Database>(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);
 
function Page() {
  const { trigger: insert } = useInsertMutation(
    client.from('contact'),
    ['id'],
    'ticket_number',
    {
      onSuccess: () => console.log('Success!'),
    }
  );
  return <div>...</div>;
}

To subscribe to changes, import useSubscription and define a subscription. Use any channel name, and define the subscription as you know it from the Supabase client. For the automatic cache population to work, you need to pass the primary key(s) of the relation. You can pass the SWR and React Query-native mutation options.

The query cache will automatically be updated when new data comes in. If you use computed / virtual columns or relations, you can use useSubscriptionQuery to fetch the entity from PostgREST before populating the cache with it.

import { useSubscription } from "@supabase-cache-helpers/postgrest-swr";
 
const client = createClient<Database>(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);
 
function Page() {
  const { status } = useSubscription(
    client,
    `insert-channel-name`,
    {
      event: "*",
      table: "contact",
      schema: "public",
    },
    ["id"],
    { callback: (payload) => console.log(payload) }
  );
  return <div>...</div>;
}

Configuration Queries