Kitchen-sink Expo tutorial

Step-by-step build of a to-do list Expo app that exercises the whole Amba SDK surface — auth, collections, streaks, remote config, and push.

In this tutorial you'll build a real Expo to-do app that exercises every major Amba feature:

Email signup and login.
Todos stored as rows in an owner-scoped collection, private to each user (read and written from the app).
A daily "completed a todo" streak.
A remote-config feature flag (weekly_goal_count).
Push notifications on iOS and Android.

When you're done you'll have a TestFlight- and Play-Internal-ready app that uses every major Amba feature.

1. Prerequisites

Node.js 20 or later (node -v). Node 22 also works.
Expo CLI — invoked via npx, no global install needed.
iOS only: Xcode 15+ for local dev builds, or an Expo account for EAS Build.
Android only: Android Studio with an emulator, or a physical device with USB debugging.

You don't need an Apple Developer account to build and run the app, but you will need one ($99/yr) to test iOS push notifications and submit to TestFlight. Skip the iOS push section if you don't have one.

On iOS, push notifications require a development build — Expo Go can't deliver them. Plan to test push on the development build, not in Expo Go.

2. Install the SDK

Start from a fresh Expo project:

npx create-expo-app@latest my-app --template default
cd my-app
npx @layers/amba init

npx @layers/amba init walks you through:

Sign in — opens a browser for login (or reuses cached credentials).
Pick or create a project — choose an existing project or name a new one.
Mint a client key — generates a development client key (prefixed amba_ck_).
Write .env.local — your projectId, clientKey, and apiUrl land in the project root.
Drop agent context — writes AMBA.md and .cursor/rules/amba.mdc so Cursor / Claude Code know how to drive Amba in your project.

No Amba account yet? Run npx @layers/amba init; signup is open, so no invite code is needed. See Getting access.

Then install the Expo SDK and its peer dependencies:

npx expo install @layers/amba-expo \
  @react-native-async-storage/async-storage expo-secure-store \
  expo-notifications expo-device \
  expo-apple-authentication expo-auth-session \
  expo-crypto expo-linking

3. Environment variables

Expo only exposes env vars that start with EXPO_PUBLIC_ to client-side code. Rewrite .env.local so the Amba values use the Expo prefix:

# .env.local
 
# Client-side — embedded in the JS bundle, visible to end users.
EXPO_PUBLIC_AMBA_PROJECT_ID=proj_xxx
EXPO_PUBLIC_AMBA_CLIENT_KEY=amba_ck_xxx
EXPO_PUBLIC_AMBA_API_URL=https://api.amba.dev

There are no server-side env vars required for the mobile app itself. If you later add an edge function or a server that calls the Admin API, it will need un-prefixed developer credentials (AMBA_DEVELOPER_TOKEN=...) — never ship those to the client.

.gitignore in the Expo template already excludes .env*.local. Confirm before committing.

4. Configure the Expo plugin

The @layers/amba-expo config plugin auto-wires push entitlements, Apple Sign In capability, and URL schemes so you don't have to hand-edit Info.plist / AndroidManifest.xml / app.json. Register the plugin and pass any options you want:

// app.json
{
  "expo": {
    "name": "todo-kitchen-sink",
    "slug": "todo-kitchen-sink",
    "plugins": [
      "expo-router",
      [
        "@layers/amba-expo",
        {
          "projectId": "proj_...",
          "clientKey": "amba_ck_...",
          "scheme": "todokitchensink",
          "googleIosClientId": "<your-google-ios-client-id>.apps.googleusercontent.com"
        }
      ]
    ],
    "ios": {
      "bundleIdentifier": "com.example.todokitchensink",
      "supportsTablet": true
    },
    "android": {
      "package": "com.example.todokitchensink"
    }
  }
}

What the plugin adds for you:

iOS — aps-environment entitlement (default development, EAS flips to production at build time), applinks: associated domains, and CFBundleURLTypes for deep-link URL schemes. Apple Sign In capability is enabled via the peer expo-apple-authentication plugin.
Android — intent filters on .MainActivity for each scheme/host/pathPrefix you pass. autoVerify is added automatically when the scheme is https.

You never need to hand-edit Info.plist or AndroidManifest.xml for basic push + deep-link wiring. Rebuild native after changing app.json:

npx expo prebuild           # writes ios/ + android/ with the plugin output
# or let `expo run:ios` / `eas build` do it implicitly

Pick your own bundleIdentifier / package — you'll need them later for APNs / FCM.

5. Initialize the SDK

Edit (or create) app/_layout.tsx:

import { useEffect, useState } from 'react';
import { Stack } from 'expo-router';
import { View, ActivityIndicator } from 'react-native';
import { Amba } from '@layers/amba-expo';
 
export default function RootLayout() {
  const [ready, setReady] = useState(false);
 
  useEffect(() => {
    Amba.configure({
      projectId: process.env.EXPO_PUBLIC_AMBA_PROJECT_ID!,
      clientKey: process.env.EXPO_PUBLIC_AMBA_CLIENT_KEY!,
      apiUrl: process.env.EXPO_PUBLIC_AMBA_API_URL,
    })
      .catch((err) => {
        // Don't swallow silently in dev — network outages and misconfigured
        // env vars both show up here.
        console.warn('Amba.configure failed', err);
      })
      .finally(() => setReady(true));
  }, []);
 
  if (!ready) {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <ActivityIndicator />
      </View>
    );
  }
 
  return <Stack />;
}

If you're starting from the create-expo-app --template default template, keep the existing ThemeProvider + <Stack> wrapper around this — merge the ready-check into the template's root layout rather than replacing it wholesale.

Amba.configure() does three things for you:

Initializes the on-device SDK singleton with your project + client key.
Restores any persisted session and anonymous id from device storage.
Boots the in-memory caches (events queue, config, flags).

On iOS and Android builds, the session and refresh tokens are stored in SecureStore (Keychain on iOS, EncryptedSharedPreferences on Android) when expo-secure-store and AsyncStorage are both installed and SecureStore is available on the device. Otherwise the SDK logs a warning and keeps the tokens in memory, so users sign in again after each launch (tokenStorage: "asyncStorage" in Amba.configure() opts into plain AsyncStorage instead). Keep expo-secure-store in the install command above for any app that signs users in.

Push registration is opt-in — call Amba.registerPushToken() explicitly when you're ready to ask for the permission prompt (see step 7).

Create app/(auth)/signin.tsx:

import { useState } from 'react';
import { View, TextInput, Button, Text, StyleSheet, Alert } from 'react-native';
import { useRouter } from 'expo-router';
import { Amba, AmbaApiError } from '@layers/amba-expo';
 
export default function SignInScreen() {
  const router = useRouter();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [mode, setMode] = useState<'signin' | 'signup'>('signup');
  const [busy, setBusy] = useState(false);
 
  const submit = async () => {
    if (busy) return;
    setBusy(true);
    try {
      if (mode === 'signup') {
        await Amba.auth.signUpWithEmail(email, password);
      } else {
        await Amba.auth.signInWithEmail(email, password);
      }
      router.replace('/');
    } catch (err) {
      if (err instanceof AmbaApiError) {
        // Common codes: INVALID_CREDENTIALS, USER_EXISTS, INVALID_EMAIL,
        // WEAK_PASSWORD, RATE_LIMITED. See AmbaApiError.code.
        Alert.alert('Auth error', err.message);
      } else {
        Alert.alert('Error', String(err));
      }
    } finally {
      setBusy(false);
    }
  };
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>{mode === 'signup' ? 'Create account' : 'Sign in'}</Text>
      <TextInput
        style={styles.input}
        placeholder="Email"
        autoCapitalize="none"
        keyboardType="email-address"
        value={email}
        onChangeText={setEmail}
      />
      <TextInput
        style={styles.input}
        placeholder="Password"
        secureTextEntry
        value={password}
        onChangeText={setPassword}
      />
      <Button title={mode === 'signup' ? 'Sign up' : 'Sign in'} onPress={submit} disabled={busy} />
      <Button
        title={mode === 'signup' ? 'I have an account' : 'Create account instead'}
        onPress={() => setMode(mode === 'signup' ? 'signin' : 'signup')}
      />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', padding: 24, gap: 12 },
  title: { fontSize: 28, fontWeight: '600', marginBottom: 12 },
  input: { borderWidth: 1, borderColor: '#ccc', padding: 12, borderRadius: 8 },
});

Now gate the home tab on having a session. With the default template, (tabs)/index.tsx is the home route; drop the auth gate in there (don't create a new app/index.tsx, or it will race with (tabs)/index.tsx):

// app/(tabs)/index.tsx
import { useEffect, useState } from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import { useRouter } from 'expo-router';
import { Amba } from '@layers/amba-expo';
import type { Session } from '@layers/amba-expo';
 
export default function HomeScreen() {
  const router = useRouter();
  const [session, setSession] = useState<Session | null>(null);
 
  useEffect(() => {
    (async () => {
      const s = await Amba.auth.getSession();
      if (!s) {
        router.replace('/(auth)/signin');
      } else {
        setSession(s);
      }
    })();
 
    const unsub = Amba.auth.onAuthStateChange((s) => {
      setSession(s);
      if (!s) router.replace('/(auth)/signin');
    });
    return unsub;
  }, []);
 
  if (!session) return null;
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Hi {session.user.email ?? session.user.anonymous_id}</Text>
      <Button title="Sign out" onPress={() => Amba.auth.signOut()} />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, alignItems: 'center', justifyContent: 'center', gap: 12 },
  title: { fontSize: 20, fontWeight: '600' },
});

Amba.auth.signOut() fires onAuthStateChange(null), so the subscription redirects the user back to the sign-in screen automatically.

Full auth surface (every method available on Amba.auth):

Amba.auth.signInAnonymously(): Promise<AuthResult>
Amba.auth.signInWithEmail(email, password): Promise<AuthResult>
Amba.auth.signUpWithEmail(email, password): Promise<AuthResult>
Amba.auth.signInWithApple(identityToken: string): Promise<AuthResult>
Amba.auth.signInWithGoogle(idToken: string): Promise<AuthResult>
Amba.auth.linkAccount(provider: 'apple' | 'google', idToken: string): Promise<AuthResult>
Amba.auth.getSession(): Promise<Session | null>
Amba.auth.refresh(): Promise<Session>
Amba.auth.me(): Promise<AppUser>
Amba.auth.signOut(rotateAnonymousId?: boolean): Promise<void>
Amba.auth.onAuthStateChange(cb): Unsubscribe

For the Expo one-liner social flows use Amba.signInWithApple() and Amba.signInWithGoogle() — they wrap the native prompt and then call Amba.auth.signInWithApple(identityToken) / Amba.auth.signInWithGoogle(idToken) for you. See Authentication for details.

Run npx expo start and verify you can sign up, sign in, and sign out.

7. Todos: store them in an owner-scoped collection

Store personal todos in an owner-scoped collection. The app creates each todo through the authenticated client Collections API, so the server assigns the row's owner from the signed-in session. A collection uses the owner policy by default: each user reads only the rows they own (plus unowned rows, which only a shared collection can hold), and only the owner can update or delete a row. The app calls these APIs directly, with no server of your own in front.

Content libraries hold shared content that every user of the project can read, so they must not hold private todos.

Create the collection (admin-side, one time)

The collection's schema is admin-scoped: you define it once, and every user's todos land in it as separate rows. With the CLI:

amba collections create todos --field title:text --field completed:boolean

Or with an MCP-enabled agent like Cursor or Claude Code with the Amba MCP server configured (see MCP):

Agent: Create a collection named "todos" where each user sees only their own rows.

amba_collections_create({
  project_id: "proj_xxx",
  name: "todos",
  columns: [
    { name: "title", type: "text" },
    { name: "completed", type: "boolean" }
  ],
  read_policy: "owner",
  write_policy: "owner"
})

Or via the Admin API directly:

POST /v1/admin/projects/:projectId/collections
Authorization: Bearer <developer token>
 
{
  "name": "todos",
  "columns": [
    { "name": "title", "type": "text" },
    { "name": "completed", "type": "boolean" }
  ],
  "read_policy": "owner",
  "write_policy": "owner"
}

owner is the default for both policies; the examples spell it out so the privacy rule is visible. The server adds id, user_id, created_at, updated_at, and deleted_at to every row. Leave shared off: a shared collection accepts rows without an owner, and every user can read those rows.

Read, write, update, and delete todos in the app

The client SDK's collections module exposes:

Amba.collections.find<T>(name: string, options?: FindOptions): Promise<{ data: T[]; next_cursor?: string | null; has_more: boolean }>
Amba.collections.insert<T>(name: string, row: Record<string, unknown>): Promise<T>
Amba.collections.update<T>(name: string, id: string, set: Record<string, unknown>): Promise<T>
Amba.collections.delete(name: string, id: string): Promise<{ data: { deleted: boolean } }>

Every call needs a signed-in session, which the auth gate from step 6 provides. On insert the server sets user_id from the session and ignores any user_id in the payload. update and delete match only rows the signed-in user owns, and return 404 for a row that belongs to someone else. delete is a soft delete: the row stops appearing in reads.

Create app/todos.tsx (or add it as a new tab in (tabs)/ if you want it inside the tab bar — with the default template it's easier to add to the existing tabs group):

import { useEffect, useState, useCallback } from 'react';
import { View, Text, TextInput, FlatList, Button, StyleSheet, Pressable } from 'react-native';
import { Amba } from '@layers/amba-expo';
 
const COLLECTION = 'todos';
 
type Todo = {
  id: string;
  title: string;
  completed: boolean;
  created_at: string;
};
 
export default function TodosScreen() {
  const [todos, setTodos] = useState<Todo[]>([]);
  const [draft, setDraft] = useState('');
 
  const load = useCallback(async () => {
    // The owner read policy scopes this to the signed-in user's rows.
    const { data } = await Amba.collections.find<Todo>(COLLECTION, {
      order: [{ column: 'created_at', direction: 'desc' }],
      limit: 100,
    });
    setTodos(data);
  }, []);
 
  useEffect(() => {
    load().catch((err) => console.warn('Loading todos failed', err));
  }, [load]);
 
  const add = async () => {
    const title = draft.trim();
    if (!title) return;
    // The server stamps the owner (user_id) from the session.
    await Amba.collections.insert(COLLECTION, { title, completed: false });
    setDraft('');
    await load();
  };
 
  const toggle = async (todo: Todo) => {
    await Amba.collections.update(COLLECTION, todo.id, { completed: !todo.completed });
    if (!todo.completed) {
      // Fire the qualifying event — server-side, any streak definition
      // with `qualifying_event: "todo_completed"` will qualify.
      await Amba.events.track('todo_completed', { todo_id: todo.id });
    }
    await load();
  };
 
  const remove = async (todo: Todo) => {
    // Soft delete: the row drops out of find() results.
    await Amba.collections.delete(COLLECTION, todo.id);
    await load();
  };
 
  return (
    <View style={styles.container}>
      <View style={styles.inputRow}>
        <TextInput
          style={styles.input}
          placeholder="Add a todo…"
          value={draft}
          onChangeText={setDraft}
          onSubmitEditing={add}
        />
        <Button title="Add" onPress={add} />
      </View>
      <FlatList
        data={todos}
        keyExtractor={(t) => t.id}
        renderItem={({ item }) => (
          <Pressable
            style={styles.row}
            onPress={() => toggle(item)}
            onLongPress={() => remove(item)}
          >
            <Text style={[styles.title, item.completed && styles.completed]}>{item.title}</Text>
            <Text style={styles.hint}>tap to toggle · long-press to delete</Text>
          </Pressable>
        )}
        ListEmptyComponent={<Text style={{ padding: 16 }}>No todos yet — add one above.</Text>}
      />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1 },
  inputRow: { flexDirection: 'row', padding: 12, gap: 8, alignItems: 'center' },
  input: { flex: 1, borderWidth: 1, borderColor: '#ccc', padding: 8, borderRadius: 6 },
  row: { padding: 16, borderBottomWidth: 1, borderColor: '#eee' },
  title: { fontSize: 16, fontWeight: '600' },
  completed: { textDecorationLine: 'line-through', color: '#888' },
  hint: { color: '#999', marginTop: 4, fontSize: 12 },
});

To make the screen reachable from the tab bar, add a Link to (tabs)/index.tsx or create a new tab file in app/(tabs)/ that re-exports this screen.

8. Streaks: track "completed a todo today"

Define the streak (admin-side)

Via MCP:

amba_streaks_create({
  project_id: "proj_xxx",
  name: "Daily todo",
  key: "daily-todo",
  qualifying_event: "todo_completed",
  period: "daily",
  grace_period_hours: 6
})

Capture the streak_definition_id — you'll only need it if you plan to call qualify() manually. If you're letting track('todo_completed') drive qualification (as the todo screen above does), no client-side id is required.

Fire the event when a todo is completed

The track() call in Step 7's toggle handler is all you need — the server matches the event name against every streak definition and qualifies whichever ones match:

await Amba.events.track('todo_completed', { todo_id: todo.id });

You can also force-qualify without firing an event:

await Amba.streaks.qualify(STREAK_DEFINITION_ID);

Read the current streak

// components/streak-badge.tsx
import { useEffect, useState } from 'react';
import { View, Text } from 'react-native';
import { Amba } from '@layers/amba-expo';
import type { UserStreak } from '@layers/amba-shared';
 
export function StreakBadge() {
  const [streaks, setStreaks] = useState<UserStreak[]>([]);
 
  useEffect(() => {
    Amba.streaks
      .getAll()
      .then(setStreaks)
      .catch(() => setStreaks([]));
  }, []);
 
  const daily = streaks[0];
  if (!daily) return null;
 
  return (
    <View style={{ padding: 12 }}>
      <Text>Current streak: {daily.current_count}</Text>
      <Text>Longest streak: {daily.longest_count}</Text>
    </View>
  );
}

Import it into (tabs)/index.tsx (or todos.tsx) wherever you want it rendered.

9. Remote config: `weekly_goal_count`

Set the flag via the CLI:

amba config set weekly_goal_count 5

Or via MCP:

amba_remote_configs_create({
  project_id: "proj_xxx",
  key: "weekly_goal_count",
  value: 5,
  value_type: "number",
  description: "How many todos the user should complete per week"
})

Read it in the app. The Expo wrapper exposes the config module as Amba.config:

// components/weekly-goal.tsx
import { useEffect, useState } from 'react';
import { Text } from 'react-native';
import { Amba } from '@layers/amba-expo';
 
export function WeeklyGoal() {
  const [goal, setGoal] = useState<number | null>(null);
 
  useEffect(() => {
    (async () => {
      const bundle = await Amba.config.fetch();
      const value = bundle.values['weekly_goal_count'];
      setGoal(typeof value === 'number' ? value : 5); // sensible default
    })();
  }, []);
 
  return <Text>Weekly goal: {goal ?? '...'}</Text>;
}

config.fetch() returns the full ConfigBundle ({ version, values }); read individual keys off values.

Per-segment override

Set the value to 10 for users in a power_users segment:

amba_remote_configs_create({
  project_id: "proj_xxx",
  key: "weekly_goal_count",
  value: 5,
  value_type: "number",
  conditions: [{ segment_id: "seg_power_users", value: 10 }]
})

10. Push notifications

Expo plugin handles the native wiring

You already registered @layers/amba-expo as an Expo config plugin in Step 4. That means aps-environment, Apple Sign In capability, URL schemes, and Android intent filters are all added automatically when you prebuild or run expo run:ios / eas build.

You do not need to hand-edit:

ios/*.entitlements
ios/Info.plist (deep-link schemes)
android/app/src/main/AndroidManifest.xml (intent filters)

Push on iOS still requires a development build — Expo Go cannot add custom entitlements. npx expo run:ios or eas build --profile development both produce a dev build.

Configure APNs (iOS)

Via MCP:

amba_integrations_configure({
  project_id: "proj_xxx",
  provider: "apns",
  config: {
    key_id: "ABC123DEFG",
    team_id: "TEAM123456",
    bundle_id: "com.example.todokitchensink",
    apns_key_p8: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    environment: "sandbox"
  }
})

If you don't have an Apple Developer account, skip this and rely on Android for push testing.

Configure FCM (Android)

amba_integrations_configure({
  project_id: "proj_xxx",
  provider: "fcm",
  config: {
    service_account_json: "{ ...the full Firebase service-account JSON... }"
  }
})

Verify the app registered its token

After a successful sign-in on a real device (push requires a physical device — simulators don't get tokens), confirm via MCP or the Admin API — the user listing includes a push_token_count per user:

amba_users_list({ project_id: "proj_xxx", search: "<email or external_id>" })
// → check push_token_count >= 1 on the returned user

If you want a custom permission flow (e.g. show your own soft-ask screen first, then prompt the OS), call Amba.registerPushToken() yourself at the moment you want the OS dialog to fire. The call requests permission, fetches the native device token, and forwards to Amba.push.register in one shot:

import { Amba, AmbaApiError } from '@layers/amba-expo';
 
async function onUserOptedIn() {
  try {
    await Amba.registerPushToken();
  } catch (err) {
    if (err instanceof AmbaApiError && err.code === 'PUSH_PERMISSION_DENIED') {
      // User rejected the OS prompt. Surface a "you can change this in Settings" affordance.
    }
  }
}

Send a test push

Via MCP:

amba_push_send_test({
  project_id: "proj_xxx",
  title: "Hello from the kitchen sink",
  body: "If you see this, push works!",
  device_token: "<the token from push_tokens>"
})

Or the CLI:

amba push test --user <app_user_id>

amba push test sends one notification to that user's newest active push token.

Send a scheduled campaign

amba_push_campaigns_create({
  project_id: "proj_xxx",
  title: "Time to check off a todo",
  body: "Keep your streak alive!",
  scheduled_at: "2026-04-20T09:00:00Z"
})

The API rejects scheduled_at values in the past — use a future timestamp.

11. Test on iOS and Android

Expo Go

Works for: auth, collections, streaks, remote config.
Does not support iOS push (custom entitlements unavailable).
Supports Android push only with the Expo push service — for Amba-owned FCM delivery you need a development build.

Development build

# iOS (requires Xcode, Apple Developer account)
npx expo run:ios
 
# Android (requires Android Studio + emulator or USB device)
npx expo run:android

A development build lets you test push on both platforms and matches your production native config.

Export without running

If you just want to confirm the app bundles, run:

npx expo export --platform ios
npx expo export --platform android

Both should produce a clean bundle with no Metro errors.

12. Deploy to TestFlight / Play internal

Use EAS Build (the standard Expo CI):

npm install -g eas-cli
eas login
eas build:configure
 
# iOS internal (TestFlight)
eas build -p ios --profile preview
 
# Android internal (Play Internal Testing track)
eas build -p android --profile preview

Then submit:

eas submit -p ios --latest
eas submit -p android --latest

Full EAS docs at https://docs.expo.dev/build/setup/.

What you just built

Expo app with file-based routing.
@layers/amba-expo initialized in the root layout — session, anonymous id, and remote config restored on launch.
Email signup + login backed by bcrypt on your project's dedicated database.
Todos stored in an owner-scoped collection: each user creates, reads, updates, and deletes only their own rows.
Daily streak driven by Amba.events.track('todo_completed', ...).
Remote-config flag (weekly_goal_count) read in the UI.
Device push tokens registered automatically on both platforms.
Test push + scheduled campaign delivered via Amba.

Every module you just used is covered in depth in the dedicated docs:

Kitchen-sink Expo tutorial

On this page