v1.3.0

React Native SDK

Use Koolbase in your React Native app — auth, database, storage, realtime, feature flags, functions, code push, analytics, and logic engine in one TypeScript package.

Installation

npm install koolbase-react-native

yarn add koolbase-react-native

Setup

Initialize the SDK once at app startup — before any screens render.

App.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

export default function App() {
  useEffect(() => {
    Koolbase.initialize({
      publicKey: 'pk_live_your_key_here',
      baseUrl: 'https://api.koolbase.com',
      codePushChannel: 'stable',
      analyticsEnabled: true,
      appVersion: '1.0.0',
    });
  }, []);

  return <Navigation />;
}

Get your public key

Authentication

screens/AuthScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

// Register
const user = await Koolbase.auth.register({
  email: 'user@example.com',
  password: 'securepassword',
});

// Login
const session = await Koolbase.auth.login({
  email: 'user@example.com',
  password: 'securepassword',
});

// Attach user to analytics after login
Koolbase.analytics.identify(session.user.id);

// Current user
const me = Koolbase.auth.currentUser;

// Logout
await Koolbase.auth.logout();
Koolbase.analytics.reset();

Database

screens/PostsScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

// Insert
await Koolbase.db.insert('posts', {
  title: 'Hello Koolbase',
  published: true,
});

// Query
const { records, total } = await Koolbase.db.query('posts', {
  filters: { published: true },
  limit: 10,
  orderBy: 'created_at',
  orderDesc: true,
});

// Populate related records
const { records } = await Koolbase.db.query('posts', {
  populate: ['author_id:users', 'category_id:categories'],
});

// Get single record
const post = await Koolbase.db.get('record-id');

// Update
await Koolbase.db.update('record-id', { title: 'Updated' });

// Delete
await Koolbase.db.delete('record-id');

Storage

screens/ProfileScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

// Upload
const { url } = await Koolbase.storage.upload({
  bucket: 'avatars',
  path: `user-${userId}.jpg`,
  file: {
    uri: imageResult.assets[0].uri,
    name: 'avatar.jpg',
    type: 'image/jpeg',
  },
});

// Get download URL
const downloadUrl = await Koolbase.storage.getDownloadUrl(
  'avatars',
  `user-${userId}.jpg`
);

// Delete
await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);

Realtime

screens/FeedScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

useEffect(() => {
  const unsubscribe = Koolbase.realtime.subscribe('messages', (event) => {
    if (event.type === 'created') {
      setMessages(prev => [event.record, ...prev]);
    }
    if (event.type === 'deleted') {
      setMessages(prev => prev.filter(m => m.id !== event.record.id));
    }
  });

  return () => unsubscribe();
}, []);

Feature flags & remote config

screens/HomeScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

// Feature flag
if (Koolbase.isEnabled('new_checkout')) {
  // show new checkout UI
}

// Remote config
const timeout = Koolbase.configNumber('timeout_seconds', 30);
const apiUrl = Koolbase.configString('api_url', 'https://api.myapp.com');
const darkMode = Koolbase.configBool('force_dark_mode', false);

// Version check
const result = Koolbase.checkVersion('1.2.3');
if (result.status === 'force_update') {
  // block the app and show update screen
}

Offline-first database

Queries return cached data instantly and refresh from the network in the background. Writes are saved locally first and synced automatically when online.

screens/PostsScreen.tsxTypeScript

const { records, isFromCache } = await Koolbase.db.query('posts', {
  filters: { published: true },
  limit: 20,
});

if (isFromCache) console.log('Served from local cache');

// Manual sync
await Koolbase.db.syncPendingWrites();

Functions

screens/CheckoutScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

const result = await Koolbase.functions.invoke('process-payment', {
  amount: 4999,
  currency: 'USD',
  userId: user.id,
});

if (result.success) console.log(result.data);

Code Push

Runtime bundles are deployed via the Koolbase dashboard or CLI and consumed automatically by the SDK on app launch. Bundle values transparently override Remote Config and Feature Flags.

App.tsxTypeScript

// Bundle values transparently override Remote Config + Feature Flags
const timeout = Koolbase.configNumber('api_timeout_ms', 3000);
const newCheckout = Koolbase.isEnabled('new_checkout_flow');

// Access code push client directly
if (Koolbase.codePush.hasActiveBundle) {
  const manifest = Koolbase.codePush.manifest;
  console.log('Bundle v' + manifest.version + ' active');
}

// Directive handlers
Koolbase.codePush.onDirective('force_logout_all', (value) => {
  if (value) Koolbase.auth.logout();
});
Koolbase.codePush.applyDirectives();

See the Code Push documentation for full details on bundle format, rollout, channels, and recall.

AnalyticsNew in v1.3.0

Track screen views, custom events, and user behaviour. Events are batched and flushed automatically — no manual setup required beyond enabling analytics in your config.

App.tsxTypeScript

await Koolbase.initialize({
  publicKey: 'pk_live_xxx',
  baseUrl: 'https://api.koolbase.com',
  analyticsEnabled: true, // default: true
  appVersion: '1.0.0',
});

screens/CheckoutScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

// Custom event
Koolbase.analytics.track('purchase', {
  value: 1200,
  currency: 'GHS',
  product_id: 'prod_123',
});

// Screen view
Koolbase.analytics.screenView('checkout');

// User identity — call after login
Koolbase.analytics.identify(user.id);
Koolbase.analytics.setUserProperty('plan', 'pro');
Koolbase.analytics.setUserProperties({
  plan: 'pro',
  country: 'GH',
});

// On logout
Koolbase.analytics.reset();

// Manual flush
await Koolbase.analytics.flush();

Auto events

On initialize, Koolbase automatically tracks app_open. Call screenView() on each navigation to track screen views. session_end fires when dispose() is called.

Batch flush triggers

Events are flushed automatically: every 30 seconds, when the app goes to background (via AppState), when the queue reaches 20 events, and when dispose() is called. Failed flushes are re-queued and retried.

Logic EngineNew in v1.3.0

Define conditional app behavior as data in your Runtime Bundle. Control navigation flows and feature gating from the server — without changing TypeScript code.

bundle/flows.jsonjson

{
  "on_checkout_tap": {
    "type": "if",
    "condition": {
      "op": "eq",
      "left": { "from": "context.plan" },
      "right": "free"
    },
    "then": { "type": "event", "name": "show_upgrade" },
    "else": { "type": "event", "name": "go_checkout" }
  }
}

screens/CheckoutScreen.tsxTypeScript

import { Koolbase } from 'koolbase-react-native';

// Execute a named flow from the active bundle
const result = Koolbase.executeFlow('on_checkout_tap', {
  plan: user.plan,
  cart_total: cart.total,
});

if (result.hasEvent) {
  switch (result.eventName) {
    case 'show_upgrade':
      navigation.navigate('Upgrade');
      break;
    case 'go_checkout':
      navigation.navigate('Checkout');
      break;
  }
}

Always safe

executeFlow() never throws. If the flow ID does not exist, the bundle is inactive, or evaluation fails — it returns a safe result with hasEvent: false. See the Logic Engine documentation for full node types and operators.

Source & contributing

The React Native SDK is open source at github.com/kennedyowusu/koolbase-react-native. Issues and PRs welcome.