React SDK

Installation

npm install @altbase/react @altbasedb/sdk @tanstack/react-query

The React SDK provides hooks that build on the core JS/TS SDK and TanStack Query for caching and state management.

Peer Dependency	Minimum Version
react	18+
@tanstack/react-query	5+
@altbasedb/sdk	0.1.0+

Provider Setup

Wrap your app with AltBaseProvider to make the client and query cache available to all hooks:

import { AltBaseProvider } from '@altbase/react'
import { createClient } from '@altbasedb/sdk'

const altbase = createClient('http://localhost:4000', 'your-anon-key')

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <AltBaseProvider client={altbase}>
      {children}
    </AltBaseProvider>
  )
}

AltBaseProvider internally creates a QueryClient and wraps children with both QueryClientProvider and an AltBase context. If you already have a QueryClient, you can pass it as a prop.

Hooks

useClient

Access the AltBase client instance from any component:

import { useClient } from '@altbase/react'

function MyComponent() {
  const altbase = useClient()
  // altbase.from('posts').select(...)
}

useQuery

Fetch data from any table with automatic caching via TanStack Query:

import { useQuery } from '@altbase/react'

function PostList() {
  const { data, isLoading, error } = useQuery('posts', {
    select: 'id, title, created_at',
    order: { column: 'created_at', ascending: false },
    limit: 20,
  })

  if (isLoading) return <p>Loading...</p>
  if (error) return <p>Error: {error.message}</p>

  return (
    <ul>
      {data?.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

useRealtime

Subscribe to CDC events and automatically merge changes into the TanStack Query cache:

import { useQuery, useRealtime } from '@altbase/react'

function LivePosts() {
  const { data } = useQuery('posts', { select: '*' })

  // Automatically merges INSERT, UPDATE, DELETE into the cached query
  useRealtime('posts', {
    event: '*',
    schema: 'public',
    table: 'posts',
  })

  return (
    <ul>
      {data?.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

When a CDC event arrives, useRealtime calls mergeIntoCache to update the relevant query data without a refetch. This means your UI updates in real time with no additional state management.

useAuth

Manage authentication state and actions:

import { useAuth } from '@altbase/react'

function AuthStatus() {
  const { user, session, signIn, signOut, isLoading } = useAuth()

  if (isLoading) return <p>Loading...</p>

  if (!user) {
    return (
      <button onClick={() => signIn({ email: 'user@example.com', password: 'secret' })}>
        Sign In
      </button>
    )
  }

  return (
    <div>
      <p>Signed in as {user.email}</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  )
}

useStorage

Upload and download files:

import { useStorage } from '@altbase/react'

function FileUploader() {
  const { upload, isUploading, progress } = useStorage('avatars')

  return (
    <input
      type="file"
      onChange={(e) => {
        const file = e.target.files?.[0]
        if (file) upload('profile.png', file)
      }}
    />
  )
}

Cache Merging

The mergeIntoCache utility is available for manual cache updates when you need more control:

import { mergeIntoCache } from '@altbase/react'

// Manually merge a CDC event into a specific query cache
mergeIntoCache(queryClient, 'posts', cdcEvent)

Exports

Export	Description
AltBaseProvider	Context provider wrapping QueryClient and AltBase client
useClient	Access the AltBase client instance
useQuery	Data fetching with TanStack Query integration
useRealtime	CDC subscriptions with automatic cache merging
useAuth	Auth state and actions
useStorage	File upload and download
mergeIntoCache	Manual CDC-to-cache merge utility