Refine integration

TaruviBase providers connect Refine 5 to app data, browser authentication, storage, users, and app-level services. Register the supported providers once, then select the right provider for each resource.

This guide uses the TaruviBase Refine provider with Refine 5 and the TaruviBase JavaScript SDK.

Install the packages

npm install \
  @refinedev/core \
  @taruvi/refine-providers \
  @taruvi/sdk

This installs the latest published release of each package. The providers support Refine 5. Check the provider release notes before upgrading either package on its own.

Configure the TaruviBase client

Use apiUrl for the site URL and construct one browser client for the application. This Vite example uses public build-time configuration; use the equivalent public configuration mechanism in another React setup.

import {Client} from '@taruvi/sdk';

export function createTaruviClient() {
  return new Client({
    apiUrl: import.meta.env.VITE_TARUVI_SITE_URL,
    appSlug: import.meta.env.VITE_TARUVI_APP_SLUG,
    apiKey: 'session-authenticated-client',
  });
}

The authentication provider starts TaruviBase's browser redirect when Refine invokes login. On the return page, the JavaScript SDK reads the session_token URL fragment, stores the browser session, and sends it as X-Session-Token. The browser runtime ignores the client's token option.

Register providers

Use the Database provider as Refine's default and name the providers used by other resource families:

import {Refine} from '@refinedev/core';
import type {ReactNode} from 'react';
import {useMemo} from 'react';
import {
  appDataProvider,
  authProvider,
  dataProvider,
  storageDataProvider,
  userDataProvider,
} from '@taruvi/refine-providers';
import {createTaruviClient} from './taruvi-client';

type TaruviProviderProps = {
  children: ReactNode;
};

export function TaruviProvider({children}: TaruviProviderProps) {
  const taruvi = useMemo(() => createTaruviClient(), []);
  const providers = useMemo(
    () => ({
      default: dataProvider(taruvi),
      storage: storageDataProvider(taruvi),
      app: appDataProvider(taruvi),
      user: userDataProvider(taruvi),
    }),
    [taruvi],
  );
  const authentication = useMemo(() => authProvider(taruvi), [taruvi]);

  return (
    <Refine
      dataProvider={providers}
      authProvider={authentication}
      resources={[
        {name: 'tasks'},
        {
          name: 'documents',
          meta: {dataProviderName: 'storage'},
        },
      ]}
    >
      {children}
    </Refine>
  );
}

Refine requires the default key when multiple data providers are registered. A resource selects another provider through meta.dataProviderName.

Access control

Don't register the accessControlProvider from @taruvi/refine-providers 1.3.6 yet: its permission checks don't reach the current API, so useCan and CanAccess can't return reliable answers.

TaruviBase enforces your access policies on the server for every request, whether or not the provider is registered. UI checks such as CanAccess and useCan only decide what to show; they never replace server-side enforcement. See Access policy SDK and provider support.

Read data with Refine 5

Refine 5 exposes list data through result and request state through query:

import {useList} from '@refinedev/core';

type Task = {
  id: string;
  title: string;
  done: boolean;
};

export function useTasks() {
  const {
    result: {data: tasks, total},
    query: {isLoading, error},
  } = useList<Task>({
    resource: 'tasks',
    pagination: {currentPage: 1, pageSize: 20},
    sorters: [
      {field: 'title', order: 'asc'},
      {field: 'id', order: 'asc'},
    ],
  });

  return {tasks, total, isLoading, error};
}

Each product guide shows the Refine provider calls it supports and the permissions they need.

Choose the right provider

Provider	Primary purpose
dataProvider	Database record reads, lists, filters, sorting, and query metadata
storageDataProvider	Storage objects and bucket workflows
appDataProvider	App settings, roles, secrets, functions, and analytics
userDataProvider	Users, roles, and app membership
authProvider	Browser login, logout, session checks, and identity
accessControlProvider	Not yet usable with 1.3.6 — see Access control

The standalone functions and analytics providers remain exported for compatibility. New applications should use appDataProvider with Refine's custom-query workflow.

Handle errors and permissions

TaruviBase SDK errors pass through the supported providers. Refine's authentication provider redirects on an expired session. Keep UI visibility decisions separate from the server-side authorization boundary described above.

Use the provider that matches the resource instead of routing arbitrary URLs through custom. Each product guide lists its supported operations and limits.

Deploy your app

Once you've built your Refine application, set up automated deployments to production:

Deploy with GitHub Actions →