React SDK
Official React hooks for AltBase — data fetching with TanStack Query, realtime CDC subscriptions with automatic cache merging, auth state, and storage.
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 |
JavaScript / TypeScript SDK
Install and use the AltBase JS/TS SDK to query data, authenticate users, manage files, subscribe to realtime events, invoke functions, search, and more.
Python SDK
Install and use the AltBase Python SDK for async data queries, authentication, storage, vector search, realtime subscriptions, and more.