Drop-in React bindings for tacobase — auth state, live data, and realtime updates with zero boilerplate.

npm install @tacobase/react

Table of Contents

• Wrap your app
• useAuth
• useCollection
• useRealtime
• useClient
• Full example
• Related packages

Wrap your app

Everything flows from TacoProvider. Put it at the root.

import { TacoProvider } from '@tacobase/react'

export default function App() {
  return (
    <TacoProvider
      url={process.env.NEXT_PUBLIC_TACOBASE_URL!}
      apiKey={process.env.NEXT_PUBLIC_TACOBASE_API_KEY!}
    >
      <YourApp />
    </TacoProvider>
  )
}

useAuth

Auth state, no assembly required.

import { useAuth } from '@tacobase/react'

function Header() {
  const { user, signIn, signOut, signUp, loading } = useAuth()

  if (loading) return <p>Wrapping up...</p>

  return user ? (
    <div>
      <span>Hey, {user.email} 👋</span>
      <button onClick={signOut}>Sign out</button>
    </div>
  ) : (
    <button onClick={() => signIn({ email: '[email protected]', password: '...' })}>
      Sign in
    </button>
  )
}

Full API

const {
  user,            // RecordModel | null — current user
  loading,         // boolean — true during initial auth check
  signUp,          // (credentials) => Promise<{ token, record }>
  signIn,          // (credentials) => Promise<{ token, record }>
  signInWithOAuth, // ({ provider }) => Promise<{ token, record }>
  signOut,         // () => void
} = useAuth()

useCollection

Live data, always fresh. Fetches, paginates, and re-fetches automatically. Realtime updates included.

import { useCollection } from '@tacobase/react'

function PostList() {
  const { data, loading, error, refresh } = useCollection('posts', {
    filter: 'published = true',
    sort: '-created',
    page: 1,
    perPage: 20,
  })

  if (loading) return <p>Loading the goods...</p>
  if (error) return <p>Something went wrong 🌶️</p>

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

Options

useCollection('posts', {
  filter: 'status = "active"',  // tacobase filter expression
  sort: '-created',              // prefix with - for descending
  expand: 'author,comments',    // expand relations
  page: 1,
  perPage: 20,
  realtime: true,                // auto-update on changes (default: true)
})

Return value

const {
  data,     // { items: T[], totalItems: number, totalPages: number } | null
  loading,  // boolean
  error,    // Error | null
  refresh,  // () => void — manually re-fetch
} = useCollection('posts')

useRealtime

Raw realtime subscriptions when you need them.

import { useRealtime } from '@tacobase/react'

function LiveFeed() {
  const [events, setEvents] = useState([])

  useRealtime('posts', (event) => {
    // event.action: 'create' | 'update' | 'delete'
    // event.record: the affected record
    setEvents((prev) => [event, ...prev])
  })

  return (
    <ul>
      {events.map((e, i) => (
        <li key={i}>{e.action}: {e.record.title}</li>
      ))}
    </ul>
  )
}

useClient

Need the full SDK? Grab it from context.

import { useClient } from '@tacobase/react'

function MyComponent() {
  const db = useClient()

  const handleUpload = async (file: File) => {
    const formData = new FormData()
    formData.append('image', file)
    await db.collection('uploads').create(formData)
  }
}

Full example

A live blog feed with auth, data, and realtime — under 40 lines.

import { TacoProvider, useAuth, useCollection } from '@tacobase/react'

function BlogFeed() {
  const { user, signOut } = useAuth()
  const { data, loading } = useCollection('posts', {
    filter: 'published = true',
    sort: '-created',
    realtime: true, // updates live as posts are published
  })

  return (
    <div>
      <header>
        {user && <button onClick={signOut}>Sign out</button>}
      </header>

      {loading ? (
        <p>Wrapping up...</p>
      ) : (
        <ul>
          {data?.items.map((post) => (
            <li key={post.id}>
              <h2>{post.title}</h2>
              <p>{post.content}</p>
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default function App() {
  return (
    <TacoProvider
      url={process.env.NEXT_PUBLIC_TACOBASE_URL!}
      apiKey={process.env.NEXT_PUBLIC_TACOBASE_API_KEY!}
    >
      <BlogFeed />
    </TacoProvider>
  )
}

Related packages

| Package | Description | |---|---| | @tacobase/client | Core SDK — CRUD, auth, realtime, storage | | @tacobase/cli | CLI — taco init, taco dev, taco typegen | | @tacobase/taco | Drop-in AI context — installs client + writes TACOBASE.md | | @tacobase/mcp-server | MCP server — let your AI manage schema via natural language |

tacobase.dev · docs · github

License

MIT