Skip to main content

​
useBasic

The useBasic hook is used to access authentication, database, and other Basic features. Any of these properties can be accessed by destructuring the useBasic hook.

​
Auth State

​
isReady

​
isReady
boolean
Boolean that indicates when auth state has been determined. Use this as a loading state for your app while auth is being verified.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { isReady, isSignedIn } = useBasic()

  if (!isReady) return <div>Loading...</div>

  return (
    <div>{isSignedIn ? "User is signed in" : "User is signed out"}</div>
  )
}
isAuthReady is a deprecated alias for isReady and will be removed in a future version.

​
isSignedIn

​
isSignedIn
boolean
Boolean that checks if a user is signed in. Only use after isReady is true.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { isReady, isSignedIn } = useBasic()

  return (
    <>
      {isReady ? 
        <div>{isSignedIn ? "User is signed in" : "User is signed out"}</div> :
        <div>Loading...</div>
      }
    </>
  )
}

​
user

​
user
User | null
The current user object containing the user’s ID, email, and name. Returns null when not signed in.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { user } = useBasic()

  console.log("Fetch user ID: ", user?.id)
  console.log("Fetch user email: ", user?.email)
  console.log("Fetch user name: ", user?.name)

  return (
    <>
      {/* render items */}
    </>
  )
}
User type (fields present depend on IdP / userinfo):
type User = {
  sub?: string
  name?: string
  email?: string
  picture?: string
}

​
did

​
did
string | null
The authenticated user’s Decentralized Identifier when available; null when not signed in or not provided by the identity layer.

​
scope

​
scope
string | null
Space-separated OAuth scopes granted on the current access token (for example profile plus datastore scopes). Use hasScope and missingScopes for fine-grained checks.

​
hasScope

​
hasScope
(scope: string) => boolean
Returns whether a given scope string is included on the current token.

​
missingScopes

​
missingScopes
() => string[]
Returns scopes your app requested (via provider configuration) that are not yet granted on the current token — useful for prompting re-consent.

​
Auth Methods

​
signIn

​
signIn
() => Promise<void>
Function to sign a user in via the Basic OAuth flow. It will redirect the user to the Basic login page, and then redirect them back to the page they were on.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { signIn } = useBasic()

  return (
    <>
      <button onClick={signIn}>Sign in</button>
    </>
  )
}
signin (lowercase) is a deprecated alias for signIn and will be removed in a future version.

​
signInWithHandle

​
signInWithHandle
(handle: string) => Promise<void>
Starts sign-in using a user handle (resolved to a DID server-side). Useful for handle-based login flows in addition to the default signIn() redirect.

​
signOut

​
signOut
() => Promise<void>
Function to sign a user out. User remains on your page after signing out, but isSignedIn will be set to false until they sign in again.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { signOut } = useBasic()

  return (
    <>
      <button onClick={signOut}>Sign out</button>
    </>
  )
}
signout (lowercase) is a deprecated alias for signOut and will be removed in a future version.

​
signInWithCode

​
signInWithCode
(code: string, state?: string) => Promise<AuthResult>
Function to complete authentication using an OAuth authorization code. Useful for custom OAuth flows or React Native apps where you handle the redirect manually.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { signInWithCode } = useBasic()

  const handleOAuthCallback = async (code: string, state: string) => {
    const result = await signInWithCode(code, state)
    if (result.success) {
      console.log('Signed in successfully!')
    } else {
      console.error('Sign in failed:', result.error)
    }
  }

  return <>{/* OAuth callback handling */}</>
}
AuthResult type:
type AuthResult = {
  success: boolean
  error?: string
  code?: string
}

​
getToken

​
getToken
(options?: { forceRefresh?: boolean }) => Promise<string>
Fetches the user’s JWT access token. The token is automatically refreshed when needed. Pass { forceRefresh: true } to obtain a new token from the server even if the current one is still valid. Use this for authenticated calls to your backend or the Basic APIs.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { getToken } = useBasic()

  const fetchFromMyAPI = async () => {
    const token = await getToken()
    const response = await fetch('/api/my-endpoint', {
      headers: { 'Authorization': `Bearer ${token}` }
    })
    return response.json()
  }

  return (
    <>
      <button onClick={async () => console.log(await getToken())}>Get token</button>
    </>
  )
}

​
getSignInUrl

​
getSignInUrl
(redirectUri?: string) => Promise<string>
Returns the OAuth sign-in URL without redirecting. Useful for custom sign-in flows, React Native apps, or opening in a popup/modal.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { getSignInUrl } = useBasic()

  const handleCustomSignIn = async () => {
    const url = await getSignInUrl()
    // Open in popup, new tab, or handle as needed
    window.open(url, '_blank')
  }

  return <button onClick={handleCustomSignIn}>Custom Sign In</button>
}
getSignInLink is a deprecated alias for getSignInUrl and will be removed in a future version.

​
Development & schema status

​
devInfo

​
devInfo
BasicSchemaDevInfo | null
Snapshot comparing your local basic.config schema to the project schema on the server (project id, version, validity, last check). Intended for debugging and the dev toolbar; null if no schema is configured on the provider.

​
refreshSchemaStatus

​
refreshSchemaStatus
() => Promise<void>
Re-runs the remote schema check and updates devInfo. Used by the dev toolbar and custom diagnostics UIs.

​
Database

​
db

​
db
BasicDB
The database object, which you can use to read, add, update, and delete items.

​
dbStatus

​
dbStatus
DBStatus
The current status of the database connection (string enum). Possible values include:
  • 'LOADING' — Initializing
  • 'CONNECTING' — Connecting to the sync server
  • 'ONLINE' — Connected and syncing
  • 'SYNCING' — Actively syncing
  • 'OFFLINE' — No network (local data may still be available in sync mode)
  • 'ERROR_WILL_RETRY' — Non-fatal error; will retry
  • 'ERROR_TOKEN_EXPIRED' — Auth token expired for sync; refresh or sign in again
  • 'ERROR' — Fatal error
    App.tsx
    import { useBasic } from '@basictech/react'

function App() {
  const { dbStatus } = useBasic()

  return (
    <div>
      Database status: {dbStatus}
      {dbStatus === 'OFFLINE' && <span> (Working offline)</span>}
    </div>
  )
}

​
dbMode

​
dbMode
'sync' | 'remote'
The current database mode. See Database Modes for details.
  • 'sync' - Local-first with IndexedDB + real-time WebSocket sync (default)
  • 'remote' - Direct REST API calls to server

​
useQuery

The useQuery hook is used to “subscribe” to data from the database, so that your component automatically re-renders when the data changes. It enables real-time sync between the local database, users’ devices, and all other users connected to the same database.
useQuery only works in sync mode. In remote mode, use regular async/await patterns instead.
We use it primarily to wrap our .get() and .getAll() functions, and it takes a function as an argument. 
import { useBasic, useQuery } from '@basictech/react'

function App() {
  const { db } = useBasic()

  // Example 1: Fetch a single item from the table
  const item = useQuery(() => db.collection('tablename').get('ID_OF_ITEM'))

  // Example 2: Fetch all items from the table
  const items = useQuery(() => db.collection('tablename').getAll())

  return (
    // render items
  )
}
The default value is an empty array [] while data is loading. This may change in a future version.