Skip to main content

SDK

The Tarobase JavaScript SDK allows you to interact with the Tarobase platform from your JavaScript or TypeScript applications. It provides a simple interface for authentication, data management, and real-time updates.

Installation​

Install the SDK via npm:

npm install @tarobase/js-sdk

Or with Yarn:

yarn add @tarobase/js-sdk

Getting Started​

Initialization​

Initialize the SDK with your Application ID from the Tarobase Console:

import { init } from '@tarobase/js-sdk';

init({ appId: 'YOUR_APP_ID' });

Authentication​

Connect a wallet and authenticate:

import { login } from '@tarobase/js-sdk';

// Prompts wallet connection
await login();

Listen for authentication state changes:

import { onAuthStateChanged } from '@tarobase/js-sdk';

onAuthStateChanged((user) => {
  if (user) {
    console.log('Connected wallet:', user.address);
  } else {
    console.log('No wallet connected');
  }
});

React Integration​

For React applications, Tarobase provides a useAuth hook that makes it easy to handle authentication state:

import { useAuth } from '@tarobase/js-sdk';

const MyReactComponent = () => {
  const { loading, user, login } = useAuth();

  if (loading) { return <div> Loading... </div> }
  return user ?
    <div> Logged in as {user.address} </div>
    :
    <div> Not logged in. <a onClick={login}> Log in. </a></div>
}

Core Functions​

Reading Data​

import { get } from '@tarobase/js-sdk';

// Get data at a specific path
const data = await get('users/123/profile');

Writing Data​

Use set for setting data on a specific document within a collection.

import { set } from '@tarobase/js-sdk';

// Set data at a specific path
await set('users/123', {
  name: 'Alice',
  bio: 'Blockchain developer'
});

Use setMany for setting data on multiple documents in multiple collections in one atomic call.

import { setMany } from '@tarobase/js-sdk';
await setMany([
  { path: "users/1", document: { name: "Alice" }},
  { path: "names/alice", document: { taken: true }}
])

Using setMany combined with policies that make use of getAfter rules to enforce multiple path changes in a single atomic call is a common pattern to safely create relationships between multiple collections.

Real-time Updates​

import { subscribe } from '@tarobase/js-sdk';

// Subscribe to data changes
subscribe('users/123/profile', {
  onData: (data) => {
    console.log('Profile updated:', data);
  },
  onError: (error) => {
    console.error("Received error", error.message)
  },
  prompt: "Only profiles that have names starting with letter s"
);

On-Chain vs Off-Chain Data​

The SDK automatically handles data storage location based on your application's policies:

  • On-Chain Data: For paths configured as on-chain in your policy, data is stored on the blockchain
  • Off-Chain Data: For paths configured as off-chain, data is stored in Tarobase's secure database

The storage location is transparent to your application code - the same set, get, and subscribe functions work for both.

For more details on configuring storage policies, see the Policies documentation.

Support​

Need help? Join our Discord community or open an issue on GitHub.