GuiBibeau/use-supabase

React Hooks library for Supabase

Summary

use-supabase is a small, zero-dependency TypeScript library that exposes a Supabase client and a few data hooks to React applications. It wraps createClient from @supabase/supabase-js in a context provider and ships hooks that fetch table data with a stale-while-revalidate (SWR) strategy. The package is intended as a thin convenience layer for consumer apps built on Supabase.

What it is useful for

The library targets React developers who want to call Supabase from components without writing a custom fetching wrapper. The three main hooks cover the common cases:

• useSupabase() returns the configured client from context, so any from, auth, or storage call is reachable from a hook.
• useTable('site', '*') runs an SWR-style fetch against an entire table or a specific column.
• useQuery(query) accepts a query builder constructed with useSupabase().from(...).select(...) and applies the same SWR caching and revalidation to it.

This is most useful in single-page apps (the README shows a Create-React-App example) and in Next.js apps via a custom _app.tsx. Limitations called out in the README: the useUser hook is marked deprecated, and the author points Next.js or Remix users to the separate supabase-auth-helpers project for authentication, so this library is not the right choice if server-side session handling is a priority. The README does not document mutation helpers, realtime subscriptions, or generated TypeScript types, so anything beyond read-with-revalidation is done through the raw client.

How engineers can use it

1. Install the package alongside @supabase/supabase-js. The README does not list the exact install command, so check the npm page for the current version.
2. Create a client with createClient('supabase-url', 'supabase-anon-key') as usual.
3. Wrap the root of the app in <SupabaseContextProvider client={supabase}> — the README shows this for both Create-React-App (ReactDOM.render) and Next.js (a custom _app.tsx).
4. In any component under that provider, call useSupabase(), useTable('users', '*'), or useQuery(useSupabase().from('users').select('*').eq(...)) to read data with automatic revalidation.
5. Use the returned client directly for any other Supabase operation (auth, storage, RPC) that the hooks do not cover.

The package is published under the Apache-2.0 license.