BasicProvider

To enable the features of the Basic SDK, you need to wrap your app in a <BasicProvider> component.

main.tsx

import { BasicProvider } from '@basictech/react'
import schema from './basic.config'

function App() {
  return (
    <BasicProvider schema={schema}>
      <YourApp />
    </BasicProvider>
  )
}

Props

schema

object

required

The Basic schema object containing your project configuration and table definitions. This should be imported from your basic.config.ts file.The project_id is extracted from schema.project_id.

project_id

string

The project ID of your Basic project.

Deprecated: Project ID is now extracted from schema.project_id. This prop is kept for backward compatibility but can be omitted if your schema includes the project_id.

debug

boolean

default:"false"

Enable debug mode for additional logging to the console. Useful during development.

<BasicProvider schema={schema} debug>
  <YourApp />
</BasicProvider>

dbMode

'sync' | 'remote'

default:"'sync'"

Determines which database implementation is used:

'sync' (default): Uses IndexedDB + WebSocket for local-first sync. Works offline, provides real-time updates, and useQuery auto-refreshes.
'remote': Uses REST API calls directly to the server. No local storage, requires authentication for all operations, but has no IndexedDB dependencies.

// Use remote mode for SSR-heavy apps or when you don't need offline support
<BasicProvider schema={schema} dbMode="remote">
  <YourApp />
</BasicProvider>

See Database Modes for detailed comparison.

storage

BasicStorage

Custom storage adapter for persisting auth tokens. By default, uses LocalStorageAdapter which stores data in localStorage.Implement the BasicStorage interface to use a custom storage solution (e.g., for React Native with AsyncStorage):

interface BasicStorage {
  get(key: string): Promise<string | null>
  set(key: string, value: string): Promise<void>
  remove(key: string): Promise<void>
}

import { BasicProvider, BasicStorage } from '@basictech/react'
import AsyncStorage from '@react-native-async-storage/async-storage'

const asyncStorageAdapter: BasicStorage = {
  get: (key) => AsyncStorage.getItem(key),
  set: (key, value) => AsyncStorage.setItem(key, value),
  remove: (key) => AsyncStorage.removeItem(key)
}

<BasicProvider schema={schema} storage={asyncStorageAdapter}>
  <YourApp />
</BasicProvider>

auth

AuthConfig

Custom authentication configuration. Most apps omit this and use defaults.

type AuthConfig = {
  scopes?: string | string[]   // default: 'profile,email,app:admin'
  pds_url?: string             // PDS / auth host (default: 'https://pds.basic.id')
  admin_url?: string          // Admin API for telemetry (default: 'https://api.basic.tech')
  ws_url?: string             // Sync WebSocket (default: 'wss://pds.basic.id/ws')
  /** @deprecated */ server_url?: string  // use pds_url instead
}

<BasicProvider 
  schema={schema} 
  auth={{ 
    scopes: ['profile', 'email'],
    pds_url: 'https://pds.basic.id'
  }}
>
  <YourApp />
</BasicProvider>

devToolbar

When true, shows the lazy-loaded Basic dev toolbar (schema status, useful shortcuts) in environments where it is allowed (for example localhost, NODE_ENV=development, or when debug is enabled on the provider). Export BasicDevToolbar from @basictech/react if you want to place it yourself.

Full Example

main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { BasicProvider } from '@basictech/react'
import { schema } from './basic.config'
import App from './App'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <BasicProvider schema={schema} debug>
      <App />
    </BasicProvider>
  </StrictMode>
)

React Guide

Guides

SDK Reference

Components (BasicProvider)

BasicProvider

Props

schema

project_id

debug

dbMode

storage

auth

devToolbar

Full Example

​BasicProvider

​Props

​schema

​project_id

​debug

​dbMode

​storage

​auth

​devToolbar

​Full Example

BasicProvider

Props

schema

project_id

debug

dbMode

storage

auth

devToolbar

Full Example