The Expo React Native app | Expo Supabase SaaS Kit

The kit ships a second application alongside the Next.js one: an Expo (React Native) app in apps/native, building for iOS and Android from the same monorepo, against the same Supabase project as apps/web. This page explains what that app is, what it is not, and where the rest of this section takes you. Read it before you open the code — the app makes a few deliberate architectural choices that look surprising if you approach it as "the web app, in React Native".

What apps/native is

apps/native is an Expo app that covers a subset of the web kit: the surfaces a signed-in customer uses on a phone. Authentication, personal account settings, team accounts, members and invitations, and the app shell around them.

It is not a port of apps/web. Nothing in the kit tries to keep the two screen-for-screen identical, and several web surfaces are intentionally absent — see What is deliberately not there. Nor is it a WebView wrapper: every screen is a real React Native screen.

The two apps are siblings, not layers. apps/native does not import from apps/web, and apps/web does not import from apps/native. What they share is the database, a set of @kit/* packages, and an HTTP contract.

How it relates to apps/web

Why the database goes through /api/v1

Supabase's client SDK can query the database from React Native perfectly well. The kit deliberately does not do that.

A mobile binary is distributed through the app stores and updated on the user's schedule — you cannot assume every installed copy is running this week's code. If business rules lived in the app (which roles may be assigned, when a seat count changes, whether team creation is allowed), an old binary would keep enforcing an old version of them, and every rule would exist twice. Routing data through apps/web/app/api/v1/* keeps one implementation of each rule on a server you can redeploy, and gives the mobile client a versioned contract: fields get added within v1, and removals or renames go to a new version.

The wrapper that native calls those endpoints with is api() in apps/native/features/core/api-client.ts. It attaches the current Supabase JWT, prefixes /api/v1, applies a timeout, and normalizes failures into a typed ApiError carrying the handler's status and machine-readable code:

import type { UserWorkspaceShape } from '@kit/accounts/shared';
import { api } from '~/features/core/api-client';
const workspace = await api<UserWorkspaceShape>('/me/workspace');

On the server side, enhanceRouteHandler from @kit/next/routes detects the Authorization: Bearer <jwt> header and builds an RLS-bound client for that user, so a handler is written once and serves both the cookie-bearing browser and the token-bearing app. The endpoint list and the shape of each response are documented in apps/web/app/api/v1/AGENTS.md; adding an endpoint and the React Query hook that consumes it is covered in docs/native/data-fetching.mdoc.

Supabase's JS SDK is still used directly, but only for the three things an HTTP wrapper would make worse: auth (the session must live in the client to be refreshed), MFA (challenge and enrollment are GoTrue APIs), and storage (uploading an image through a JSON endpoint would mean base64 in a request body).

Tech stack

Versions come from pnpm-workspace.yaml — every native dependency is pinned there under the expo named catalog rather than in apps/native/package.json, so an SDK bump is one file.

The React Compiler is enabled through babel-preset-expo in apps/native/babel.config.js.

The @kit/* packages apps/native depends on:

Only the /shared subpaths are imported. Those entrypoints are free of React DOM and Next.js imports, which is what makes them safe to pull into a Metro bundle.

What ships in the app today

At a high level: password sign-in and sign-up, password reset, MFA challenge and TOTP enrollment, Google (and other) OAuth, personal account settings including avatar and account deletion, team creation and settings, the full members/invitations/roles surface, a workspace switcher across personal and team accounts, theming, and a device-info diagnostics screen.

Every email flow uses a typed 6-digit code rather than a link, because the browser your mail client opens shares no cookie jar with the app — so sign-up confirmation, password reset and invitation acceptance need no deep-link infrastructure at all. docs/native/authentication.mdoc covers the flows.

What is deliberately not there

"Not there" is not the same as "unreachable": some settings rows render as a disabled row with a "manage on web" notice rather than disappearing, so the app never silently loses a capability. Which ones, and the Planned features that are simply not built yet, are in docs/native/covered-features.mdoc.

Where to go next

If you already have this repository checked out, start at docs/native/running-locally.mdoc — the app reads its Supabase URL, API base URL and feature flags from apps/native/.env.development, and seeing it run against your local stack makes the rest of this section concrete. If you are adding the Expo app to a Makerkit project you already have, start at docs/native/installation.mdoc instead.