Client

ffdb-client is the main SDK for connecting your app to FFDB. It gives you typed database queries, authentication helpers, request utilities, and optional offline sync in one client instance.

This page focuses on day-to-day usage. For setup flow, start with Quickstart, then return here for the full client surface.

Install

npm install ffdb-client

Initialize the client

import { createClient } from 'ffdb-client'
import type { Database } from './ffdb.types'

const client = await createClient<Database>({
  config: {
    apiUrl: import.meta.env.VITE_FFDB_API_URL,
  },
})

const { db, sql, auth, request, sync, getAccess, destroy } = client

What the client gives you

Name
db
Description
Type-safe query builder for reads and writes against your generated Database schema.
Name
sql
Description
Raw SQL helper for query patterns that are easier to express as SQL strings.
Name
auth
Description
Built-in auth client for sign-in, sign-out, session reads, and auth state flows.
Name
request
Description
Low-level request utility when you need a direct SDK-managed HTTP call.
Name
sync
Description
Offline sync handle when offline mode is enabled; otherwise this is null.
Name
getAccess
Description
Resolves the current user access scope that your app can use for role-aware UI behavior.
Name
destroy
Description
Cleans up timers, subscriptions, and in-memory resources when your app shuts down.

Typical usage pattern

await auth.signIn.email({
  email: '[email protected]',
  password: 'password',
})

const users = await db
  .selectFrom('user')
  .select(['id', 'email'])
  .execute()

console.log(users)

Keep admin credentials in trusted environments only. Frontend code should use user auth flows and app-level configuration values.

React usage

For React apps, use the React entrypoint and provider:

import { FFDBProvider, useFFDB, useQuery } from 'ffdb-client/react'
import type { Database } from './ffdb.types'

function Root() {
  return (
    <FFDBProvider<Database>
      options={{
        config: {
          apiUrl: import.meta.env.VITE_FFDB_API_URL,
        },
      }}
    >
      <Users />
    </FFDBProvider>
  )
}

function Users() {
  const { isLoading, error } = useFFDB<Database>()
  const { data } = useQuery((db) => db.selectFrom('user').selectAll().execute())

  if (isLoading) return <p>Connecting...</p>
  if (error) return <p>Connection failed: {error.message}</p>
  return <pre>{JSON.stringify(data, null, 2)}</pre>
}

Node.js usage

Use the Node entrypoint when running in server processes:

import { createClient, createNodeLifecycle } from 'ffdb-client/node'
import type { Database } from './ffdb.types'

const { db, destroy } = await createClient<Database>({
  config: {
    apiUrl: process.env.API_URL,
    origin: process.env.ORIGIN,
  },
  lifecycle: createNodeLifecycle(),
})

// ... use db

await destroy()