> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basic.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Components (BasicProvider)

# BasicProvider

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

```tsx main.tsx theme={null}
import { BasicProvider } from '@basictech/react'
import schema from './basic.config'

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

## Props

### schema

<ParamField query="schema" type="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`.
</ParamField>

### project\_id

<ParamField query="project_id" type="string">
  The project ID of your Basic project.

  <Warning>**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.</Warning>
</ParamField>

### debug

<ParamField query="debug" type="boolean" default="false">
  Enable debug mode for additional logging to the console. Useful during development.

  ```tsx theme={null}
  <BasicProvider schema={schema} debug>
    <YourApp />
  </BasicProvider>
  ```
</ParamField>

### dbMode

<ParamField query="dbMode" type="'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.

  ```tsx theme={null}
  // 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](/basic-nextjs/nextjs-modes) for detailed comparison.
</ParamField>

### storage

<ParamField query="storage" type="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):

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

  ```tsx theme={null}
  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>
  ```
</ParamField>

### auth

<ParamField query="auth" type="AuthConfig">
  Custom authentication configuration. Most apps omit this and use defaults.

  ```typescript theme={null}
  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
  }
  ```

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

### devToolbar

<ParamField query="devToolbar" type="boolean" default="false">
  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.
</ParamField>

***

## Full Example

```tsx main.tsx theme={null}
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>
)
```