# ReadyNative

> Pick-your-stack Expo SDK 57 starter: run setup once, keep only the modules you chose, ship. A one-time-payment Expo (React Native) boilerplate for iOS and Android: one `setup` command assembles only the modules you pick (auth, payments, push, analytics, crash reporting, data, forms, i18n and more), with EAS store builds and a `doctor` check wired in.

## Product

- [Home](https://readynative.app/): what ReadyNative is and what the setup command does.
- [Pricing](https://readynative.app/#pricing): Free, Starter and Pro tiers - one payment, lifetime updates.
- [Stacks](https://readynative.app/stack/): every module you can pick, one page each.
- [Comparisons](https://readynative.app/vs/): ReadyNative next to other Expo and React Native boilerplates.
- [Best Expo boilerplates](https://readynative.app/best-expo-boilerplates/): a sourced roundup of the options.
- [Free tier on GitHub](https://github.com/ReadyNative/ready-native-free): the public repository.

# Add a paywall (/docs/add-a-paywall)



<Badge>
  Pro
</Badge>

Hey - by the end of this page you'll open a paywall from your own screen, buy a subscription
with a test account, watch a locked feature unlock, and restore the purchase.

The `/paywall` route ships as a modal with your feature bullets, the live prices, Buy, Restore
and the Terms / Privacy links from `urls` in `readynative.config.ts`. You add the products
behind it and the button that opens it.

## Before you start [#before-you-start]

* **Tier:** Pro. The payments modules aren't in Free or Starter.
* **Time:** about 2 hours of your own work. <If cat="payments" is="stripe">Stripe test mode is
  live as soon as you sign up.</If><Else cat="payments" is="stripe">Apple can take up to a day to
  activate a new Paid Apps Agreement, so start step 2 first.</Else>
* **Runs in:** <If cat="payments" is="stripe">Expo Go - Checkout is a web page, with no native
  SDK.</If><Else cat="payments" is="stripe">a dev build on a **real device**. StoreKit and Play
  Billing are native, so Expo Go can't run them and simulators can't buy. See
  [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build).</Else>
* **Accounts:** <If cat="payments" is="stripe">[Stripe](https://stripe.com), and an auth module
  (Supabase, Clerk or Better Auth) - Checkout charges the signed-in user.</If><If cat="payments" is="adapty">[Adapty](https://app.adapty.io), the Apple Developer Program and a Google Play
  developer account.</If><If cat="payments" is="revenuecat|none">[RevenueCat](https://app.revenuecat.com), the Apple Developer Program and a Google Play developer
  account.</If>
* **Previous tutorial:** [Add sign-in](https://readynative.app/docs/add-sign-in).

**Picked a payments option at setup?** Skip step 1. Step 1 needs `modules/`, so it works only
in a tree set up with `--keep-modules`; a finalized tree without payments starts from a fresh
clone - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## 1. Add the module [#1-add-the-module]

<If cat="payments" is="adapty">
  <Cmd>
    bun run setup --payments adapty --yes --keep-modules
  </Cmd>
</If>

<If cat="payments" is="stripe">
  <Cmd>
    bun run setup --payments stripe --backend api-routes --yes --keep-modules
  </Cmd>

  Checkout runs through your API routes, so Stripe requires `backend=api-routes` (setup refuses
  it with any other backend). It also needs to know who's paying: if you have no auth module yet,
  add `--auth supabase` (or `clerk`, `better-auth`) to the same command.

  This page sells through Stripe alone. To offer in-app purchase and Stripe Checkout side by side,
  see [Add web checkout next to the App Store](https://readynative.app/docs/add-web-checkout).
</If>

<If cat="payments" is="revenuecat|none">
  <Cmd>
    bun run setup --payments revenuecat --yes --keep-modules
  </Cmd>

  <If cat="payments" is="none">
    Your stack toggle says `payments=none`, where `presentPaywall` doesn't exist and nothing is ever
    unlocked. The steps below follow RevenueCat, the default; pick Adapty or Stripe in the toggle
    above to switch them.
  </If>
</If>

**You should see:** `src/lib/payments.ts`, `src/app/paywall/` and
`src/screens/paywall/paywall-screen.tsx` in your tree.

## 2. Get paid-ready [#2-get-paid-ready]

<If cat="payments" is="stripe">
  Stay in **test mode** for this whole page: test keys, test prices, test cards. Activating your
  Stripe account (business details, bank account) matters only when you switch to live mode.
</If>

<Else cat="payments" is="stripe">
  <Callout type="warn" title="No agreement, no prices">
    Until the Paid Apps Agreement is active in App Store Connect, StoreKit returns no products and
    your paywall shows no prices - with no error that says why. Sign it before anything else.
  </Callout>

  1. **App Store Connect → Business**: accept the **Paid Apps Agreement**, then add a bank account
     and fill in the tax forms. The agreement shows "Active" once Apple has checked them.
  2. **App Store Connect → Apps → +**: create the app record with the production bundle id from
     `readynative.config.ts` (the one without `.dev`), if you haven't yet.
  3. **Play Console → Settings → Payments profile**: create or link a payments profile. Play lets
     you create subscriptions only once a build with billing has been uploaded, so do the Play side
     after [Ship to Google Play](https://readynative.app/docs/ship-to-google-play) - iOS is enough for this page.
</Else>

**You should see:** <If cat="payments" is="stripe">the **Test mode** toggle on in the Stripe
dashboard.</If><Else cat="payments" is="stripe">the Paid Apps Agreement marked **Active** under
App Store Connect → Business.</Else>

## 3. Create the product [#3-create-the-product]

<If cat="payments" is="stripe">
  In Stripe, open **Product catalog → Add product**, give it a name, and add a **recurring**
  price (for example monthly). Copy the price id (`price_…`).
</If>

<Else cat="payments" is="stripe">
  In **App Store Connect → your app → Subscriptions**, create a subscription group, then a
  subscription in it: a product id such as `trailmix_pro_monthly`, a duration, a price and one
  localization. It stays "Ready to Submit" until your first app version goes to review - that's
  fine for sandbox testing.
</Else>

**You should see:** the product listed with its price.

## 4. Connect the dashboard and keys [#4-connect-the-dashboard-and-keys]

Copy `.env.example` to `.env` if you haven't yet (`cp .env.example .env`).

<If cat="payments" is="adapty">
  1. Create an app at [app.adapty.io](https://app.adapty.io) and add your iOS bundle id and
     Android package under **App settings**. Add the `.dev` bundle id too - your dev build uses it.
  2. **App settings → General**: copy the Public SDK key into `.env`.
  3. **Products**: add the App Store product from step 3.
  4. **Access levels**: use `premium` (Adapty's built-in default) and attach your product.
  5. **Paywalls**: build one with the Paywall Builder, then attach it to a **Placement** -
     `default`, unless you set `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID`.

  ```bash title=".env"
  EXPO_PUBLIC_ADAPTY_PUBLIC_KEY=public_live_...
  ```

  Every step in full is on the [Adapty page](https://readynative.app/docs/features/payments/adapty#setup).
</If>

<If cat="payments" is="stripe">
  1. **Developers → API keys** (test mode): the secret key goes into `STRIPE_SECRET_KEY` - never
     with an `EXPO_PUBLIC_` prefix, which would ship it to every device - and the publishable key
     into `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY`.
  2. The price id from step 3 goes into `STRIPE_PRICE_ID`.
  3. Webhooks: install the [Stripe CLI](https://docs.stripe.com/stripe-cli) and forward events to
     your dev server. It prints a signing secret (`whsec_…`) for `STRIPE_WEBHOOK_SECRET`.
  4. `EXPO_PUBLIC_API_URL` is your dev server on the LAN (a phone can't reach `localhost`).
  5. With Clerk, also set `CLERK_SECRET_KEY` so the routes can verify the session token.

  ```bash
  stripe listen --forward-to localhost:8081/api/stripe/webhook
  ```

  ```bash title=".env"
  EXPO_PUBLIC_API_URL=http://192.168.1.20:8081
  EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
  STRIPE_SECRET_KEY=sk_test_...
  STRIPE_PRICE_ID=price_...
  STRIPE_WEBHOOK_SECRET=whsec_...
  ```

  Leave `stripe listen` running while you test. Every step in full is on the
  [Stripe page](https://readynative.app/docs/features/payments/stripe#setup).
</If>

<If cat="payments" is="revenuecat|none">
  1. Create a project at [app.revenuecat.com](https://app.revenuecat.com) and add an App Store
     app under **Project settings → Apps** with your bundle id. Add the `.dev` bundle id as well -
     your dev build uses it. (Add the Play Store app when you do the Play side.)
  2. **Project settings → API keys**: copy the App Store key (`appl_…`) into `.env`.
  3. **Products**: add the App Store product from step 3.
  4. **Entitlements**: create one with the identifier `pro` (`PRO_ENTITLEMENT` in
     `src/lib/payments.ts`) and attach the product.
  5. **Offerings**: create an offering with a monthly package holding that product, and mark it
     **current**. The bundled paywall lists its packages.
  6. Optional: design a paywall under **Paywalls** and attach it to the current offering.
     `payments.presentPaywall()` shows it natively when it exists and falls back to the bundled
     `/paywall` otherwise. Replace RevenueCat's sample copy before you ship.

  ```bash title=".env"
  EXPO_PUBLIC_REVENUECAT_IOS_KEY=appl_...
  EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=goog_...
  ```

  Leave the Android key empty until the Play side exists - `bun run doctor` keeps that one row
  red until then. Want to try the flow before App Store Connect is ready? A RevenueCat **Test
  Store** key (`test_…`) in the iOS slot shows RevenueCat's own purchase dialog instead of
  Apple's - never ship it. Every step in full is on the
  [RevenueCat page](https://readynative.app/docs/features/payments/revenuecat#setup).
</If>

<Cmd>
  bun run doctor
</Cmd>

**You should see:** the payments rows green (apart from any key you're deliberately leaving
for later).

## 5. Run it on a device [#5-run-it-on-a-device]

<If cat="payments" is="stripe">
  <Cmd>
    bun run start
  </Cmd>

  Open the app in Expo Go and sign in - the paywall charges the signed-in user.
</If>

<Else cat="payments" is="stripe">
  Add a sandbox tester in **App Store Connect → Users and Access → Sandbox → Testers** (a fresh
  email, not your Apple ID). Then build the dev build onto your iPhone - `bun run ios` compiles it
  locally, and `--device` picks the plugged-in phone:

  <Cmd>
    bunx expo run:ios --device
  </Cmd>

  No Mac or Xcode? Build it on EAS with `bunx eas-cli build --profile development --platform ios`
  after registering your phone - [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build) walks
  through it. Then start the dev server:

  <Cmd>
    bun run start:dev
  </Cmd>
</Else>

**You should see:** your app running on the phone, signed in.

## 6. Gate a feature [#6-gate-a-feature]

`@/lib/payments` has the same API for every option: `useEntitlements()` returns
`{ active, loading }`, and `presentPaywall()` opens the paywall<If cat="payments" is="revenuecat|none"> (RevenueCat's native one when you designed it, else the bundled `/paywall`)</If><If cat="payments" is="adapty"> (the Paywall Builder one for your placement, else the bundled `/paywall`)</If><If cat="payments" is="stripe"> (the bundled `/paywall`, which hands off to Checkout)</If>. This
component shows its children to paying users and an unlock card to everyone else:

```tsx title="src/components/pro-gate.tsx"
import type { ReactNode } from "react";

import { Box, Button, Card, Loading, Text, toast } from "@/components/ui";
import { payments } from "@/lib/payments";

/** The entitlement id from your payments dashboard. */
const ENTITLEMENT = "pro";

export function ProGate({ children }: { children: ReactNode }) {
  const { active, loading } = payments.useEntitlements();

  if (loading) return <Loading />;
  if (active.includes(ENTITLEMENT)) return <>{children}</>;

  const openPaywall = () => {
    payments.presentPaywall?.().catch(() => {
      toast.show({ title: "Couldn't open the paywall", kind: "error" });
    });
  };

  return (
    <Box p={4}>
      <Card>
        <Box gap={3}>
          <Text variant="heading">This is a Pro feature</Text>
          <Text variant="caption">Subscribe to unlock it.</Text>
          <Button onPress={openPaywall}>Unlock Pro</Button>
        </Box>
      </Card>
    </Box>
  );
}
```

<If cat="payments" is="adapty">
  On Adapty the id is the access level, so set `const ENTITLEMENT = "premium";`.
</If>

Now wrap something with it. With the Notes tab from [Add your first feature](https://readynative.app/docs/first-feature),
make writing notes a Pro feature - in `src/screens/notes/notes-screen.tsx`, import `ProGate` and
change the `header` prop of the `List`:

```tsx title="src/screens/notes/notes-screen.tsx"
import { ProGate } from "@/components/pro-gate";

// ...in the <List> props:
        header={
          <ProGate>
            <NoteForm onSave={add} />
          </ProGate>
        }
```

**You should see:** the "This is a Pro feature" card instead of the form. Tap **Unlock Pro** and
the paywall opens with your product's price.

## 7. Buy it [#7-buy-it]

<If cat="payments" is="stripe">
  On the paywall, tap **Subscribe**. Checkout opens in the browser: pay with the test card
  `4242 4242 4242 4242`, any future expiry, any CVC. The browser returns to the app, the webhook
  lands (watch the `stripe listen` output), and the entitlement refreshes.
</If>

<Else cat="payments" is="stripe">
  On the paywall, tap **Buy**. Apple's sheet asks you to sign in: use the sandbox tester from
  step 5. Sandbox subscriptions renew every few minutes, so you can watch renewals happen.
</Else>

**You should see:** the paywall close and the note form appear where the unlock card was.

## 8. Restore it [#8-restore-it]

Both stores require a Restore button - the bundled paywall has one, and it's one call anywhere
else:

```ts
import { payments } from "@/lib/payments";

await payments.restorePurchases();
```

<If cat="payments" is="stripe">
  On Stripe, restore re-fetches the entitlements from your server, which also makes it the
  "refresh after a purchase" call.
</If>

**You should see:** after deleting and reinstalling the app, **Restore** on the paywall brings
the form back without paying again.

## Check it [#check-it]

<Cmd>
  bun run doctor
</Cmd>

<Cmd>
  bun run typecheck
</Cmd>

Every payments row should be green, and typecheck should pass.

## If it doesn't work [#if-it-doesnt-work]

<If cat="payments" is="stripe">
  * **The paywall says "Configure Stripe"** - `EXPO_PUBLIC_API_URL` is empty or unreachable. Set
    it to your LAN IP and restart with `bun run start -- -c`.
  * **"Sign in to subscribe"** - Checkout charges the signed-in user; sign in first, or add an auth
    module.
  * **Paid, but still locked** - the webhook didn't arrive. Check `stripe listen` is running and
    `STRIPE_WEBHOOK_SECRET` is the secret it printed, then tap **Restore**.
  * **401 or 500 from `/api/stripe/*` with Clerk** - `CLERK_SECRET_KEY` is missing.
  * **iOS refuses the request** - plain `http://` works only on a LAN IP; a tunnel or deployed URL
    must be https.
</If>

<Else cat="payments" is="stripe">
  * **The paywall has no prices or no packages** - the Paid Apps Agreement isn't active, the
    product isn't attached, or the offering isn't **current**. See
    [RevenueCat shows no offerings or no prices](https://readynative.app/docs/troubleshooting#revenuecat-shows-no-offerings-or-no-prices).
  * **The paywall says "Configure …"** - the key for this platform isn't in `.env`, or Metro still
    has the old env. Restart with `bun run start -- -c`.
  * **"Native module not found" or a red screen on launch** - you opened the app in Expo Go. Use
    the dev build and `bun run start:dev`.
  * **The buy sheet never appears in the simulator** - buy on a real device with a sandbox tester.
  * **Purchases work for you but not for a tester** - they're signed into the App Store with a
    real Apple ID; sandbox needs the sandbox account (Settings → App Store → Sandbox Account).
</Else>

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

You're selling: a paywall with live prices, a feature behind an entitlement, and restore -
which is what App Review checks first. To take the module out again, see <If cat="payments" is="adapty">[Adapty → Remove it](https://readynative.app/docs/features/payments/adapty#remove-it)</If><If cat="payments" is="stripe">[Stripe → Remove it](https://readynative.app/docs/features/payments/stripe#remove-it)</If><If cat="payments" is="revenuecat|none">[RevenueCat → Remove it](https://readynative.app/docs/features/payments/revenuecat#remove-it)</If>.

Next, reach users when the app is closed: [Add push notifications](https://readynative.app/docs/add-push).


# Add analytics and crash reporting (/docs/add-analytics-and-crash)



<Badge>
  Pro
</Badge>

Hey - by the end of this page your events show up in your analytics dashboard, a test error
shows up in Sentry with a readable stack trace, and you've watched both stay silent until the
user says yes.

That last part is the consent module's job. `setup` adds it whenever you pick an analytics or
crash option: PostHog, Amplitude and Sentry create their clients only once the matching category
is consented to, so nothing - no event, no flags request, no crash report - leaves the device
before that.

## Before you start [#before-you-start]

* **Tier:** Pro. Analytics and crash modules aren't in Free or Starter.
* **Time:** about 30 minutes, plus a build if you want native crashes and source maps checked.
* **Runs in:** Expo Go for events and JS errors. Native crashes<If cat="analytics" is="amplitude"> and Amplitude's full device context</If> need a
  dev build - see [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build).
* **Accounts:** <If cat="analytics" is="amplitude">[Amplitude](https://app.amplitude.com)</If><If cat="analytics" is="posthog|none">[PostHog](https://app.posthog.com)</If> and [Sentry](https://sentry.io) - both have free tiers.
* **Previous tutorial:** [Add push notifications](https://readynative.app/docs/add-push).

**Picked these at setup?** Skip step 1. Step 1 needs `modules/`, so it works only in a tree set
up with `--keep-modules`; a finalized tree without them starts from a fresh clone - see
[Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## 1. Add the modules [#1-add-the-modules]

<If cat="analytics" is="amplitude">
  <Cmd>
    bun run setup --analytics amplitude --crash sentry --yes --keep-modules
  </Cmd>
</If>

<Else cat="analytics" is="amplitude">
  <Cmd>
    bun run setup --analytics posthog --crash sentry --yes --keep-modules
  </Cmd>
</Else>

Drop either flag if you want only one of them. `consent` comes along on its own. If you install
with bun on a tree that already existed, run `bun pm trust @sentry/cli` once so its source-map
uploader can download.

**You should see:** `src/lib/analytics.ts`, `src/lib/crash.ts`, `src/lib/consent.ts` and
`src/components/consent-sheet.tsx` in your tree, and a **Privacy** card in Settings with
**Analytics** and **Crash reports** switches.

## 2. Paste the keys [#2-paste-the-keys]

Copy `.env.example` to `.env` if you haven't yet (`cp .env.example .env`).

<If cat="analytics" is="amplitude">
  In Amplitude, open **Settings → Projects → your project** and copy the API key. For EU data
  residency, add `serverZone: "EU"` to the `init` options in `src/lib/analytics.ts`.

  ```bash title=".env"
  EXPO_PUBLIC_AMPLITUDE_KEY=your-amplitude-api-key
  ```
</If>

<Else cat="analytics" is="amplitude">
  In PostHog, open **Settings → Project** and copy the Project API key (`phc_…`). EU project? Set
  the host too; it defaults to the US one.

  ```bash title=".env"
  EXPO_PUBLIC_POSTHOG_KEY=phc_...
  EXPO_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
  ```
</Else>

In Sentry, create a project (platform: React Native), open &#x2A;*Settings → Projects → your project →
Client Keys (DSN)**, and copy the DSN:

```bash title=".env"
EXPO_PUBLIC_SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
```

All of these are public by design and safe in the client. Restart with a clean cache so Metro
picks them up:

<Cmd>
  bun run start -- -c
</Cmd>

**You should see:** `bun run doctor` green for the analytics and crash rows.

## 3. Decide who gets asked [#3-decide-who-gets-asked]

The consent sheet asks users where the law requires opt-in and stays out of the way
elsewhere:

| Device                                                                                        | Before an answer | Sheet                                      |
| --------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------ |
| Region in the EU/EEA, UK, Switzerland, Canada or Brazil, a `Europe/*` time zone, or no region | off              | shown once, after onboarding               |
| Anywhere else                                                                                 | on               | never; Settings → Privacy has the switches |
| `privacy.askEverywhere: true`                                                                 | off              | shown to everyone                          |

The region comes from the device's locale settings and time zone - no network lookup. To ask
every user, whatever the region, flip one setting in `readynative.config.ts`:

```ts title="readynative.config.ts"
  privacy: { askEverywhere: true },
```

Turn it on now even if you'll turn it off later - otherwise a simulator set to the US never
shows you the sheet.

**You should see:** on a fresh install (delete the dev build, or Expo Go's data, and open the app
again), the **Your privacy** sheet after onboarding, with **Accept all**, **Save choices** and
**Only necessary**.

## 4. Add a test card [#4-add-a-test-card]

A temporary card with two buttons lets you trigger both SDKs by hand. Both calls work whatever
options you picked:

```tsx title="src/components/telemetry-test.tsx"
import { Box, Button, Card, Text } from "@/components/ui";
import { analytics } from "@/lib/analytics";
import { crash } from "@/lib/crash";

export function TelemetryTest() {
  return (
    <Card>
      <Box gap={3}>
        <Text variant="heading">Telemetry test</Text>
        <Button onPress={() => analytics.track("telemetry_test", { source: "home" })}>
          Send test event
        </Button>
        <Button
          variant="outline"
          onPress={() => crash.capture(new Error("Telemetry test error"), { source: "home" })}
        >
          Send test error
        </Button>
      </Box>
    </Card>
  );
}
```

Render `<TelemetryTest />` inside the `<Box>` of `src/screens/home/home-screen.tsx` for now.

**You should see:** the card on Home.

## 5. Prove nothing is sent before consent [#5-prove-nothing-is-sent-before-consent]

Open your live views side by side: <If cat="analytics" is="amplitude">Amplitude's
**Analytics → User Look-Up**</If><If cat="analytics" is="posthog|none">PostHog's **Activity → Live
events**</If>, and Sentry's **Issues**.

1. On the sheet, tap **Only necessary** (or, if you already answered, turn off **Analytics** and
   **Crash reports** in **Settings → Privacy**).
2. Tap **Send test event** and **Send test error** a few times.
3. Wait a minute.

**You should see:** nothing in either dashboard - no event, no app-open, no issue. The SDKs aren't
running.

Now turn both switches on in **Settings → Privacy** (the change takes effect immediately) and tap
the two buttons again.

**You should see:** `telemetry_test` in the live view within seconds, and
`Error: Telemetry test error` in Sentry within about a minute, tagged with the `dev` environment.
Turn a switch off again and the matching SDK stops.

Before release, set `askEverywhere` back to what you want and delete the test card.

## 6. Track what matters [#6-track-what-matters]

Screen views are already tracked: the root layout calls `analytics.screen(pathname)` on every
route change. Add your own events where something meaningful happens - for example, in the
Notes screen from [Add your first feature](https://readynative.app/docs/first-feature). In
`src/screens/notes/notes-screen.tsx`, wrap the store's `add` and pass the wrapper to the
form:

```tsx title="src/screens/notes/notes-screen.tsx"
import { analytics } from "@/lib/analytics";

// ...inside NotesScreen(), after `const { drafts, add } = useDrafts();`:
  const save = (title: string, body: string) => {
    add(title, body);
    analytics.track("note_saved", { length: body.length });
  };

// ...and in the <List> props:
        header={<NoteForm onSave={save} />}
```

Keep properties free of personal data - counts, ids and choices, not emails or note text.

Then tie events and errors to the signed-in user, so both dashboards can count affected people
and account deletion can erase the right person on your server:

<If cat="crash" is="sentry">
  ```ts title="src/hooks/use-identify.ts"
  import * as Sentry from "@sentry/react-native";
  import { useEffect } from "react";

  import { analytics } from "@/lib/analytics";
  import { auth } from "@/lib/auth";

  /** Tags analytics and crash reports with the signed-in user's id (never the email). */
  export function useIdentify(): void {
    const session = auth.useSession();
    const userId = session.status === "authenticated" ? session.user.id : null;

    useEffect(() => {
      if (!userId) return;
      analytics.identify(userId);
      Sentry.setUser({ id: userId });
    }, [userId]);
  }
  ```
</If>

<Else cat="crash" is="sentry">
  ```ts title="src/hooks/use-identify.ts"
  import { useEffect } from "react";

  import { analytics } from "@/lib/analytics";
  import { auth } from "@/lib/auth";

  /** Tags analytics with the signed-in user's id (never the email). */
  export function useIdentify(): void {
    const session = auth.useSession();
    const userId = session.status === "authenticated" ? session.user.id : null;

    useEffect(() => {
      if (userId) analytics.identify(userId);
    }, [userId]);
  }
  ```
</Else>

Call it once, in `RootStack` in `src/app/_layout.tsx`, next to the redirect hooks:

```tsx title="src/app/_layout.tsx"
import { useIdentify } from "@/hooks/use-identify";

// ...inside RootStack(), after useSignOutCleanup():
useIdentify();
```

Signing out already resets the identity (`wipeLocalData()` calls `analytics.reset()`).

**You should see:** after signing in, your next events carry your user id in the dashboard.

## 7. Get readable stack traces [#7-get-readable-stack-traces]

Sentry needs the source maps of each build and each update, or stack traces stay minified. This
step uses EAS builds and `eas update`; if you haven't made either yet, come back to it after
[Ship to TestFlight](https://readynative.app/docs/ship-to-testflight) and [Your first update](https://readynative.app/docs/your-first-update).

Three build-time keys make the upload work - never with an `EXPO_PUBLIC_` prefix:

* `SENTRY_ORG` and `SENTRY_PROJECT`: the slugs from your Sentry project URL.
* `SENTRY_AUTH_TOKEN`: **Settings → Auth Tokens**, with the scopes `project:releases` and
  `org:read`.

Put them in every EAS environment you build from, as `sensitive`:

```bash
bunx eas-cli env:set --name SENTRY_ORG --value your-org --environment production --visibility sensitive
bunx eas-cli env:set --name SENTRY_PROJECT --value your-project --environment production --visibility sensitive
bunx eas-cli env:set --name SENTRY_AUTH_TOKEN --value sntrys_... --environment production --visibility sensitive
```

**EAS builds** then upload their source maps on their own, through the Sentry config plugin.
**EAS updates** don't - after each `eas update`, upload the bundle it exported to `dist/`, with
the same three keys set in your shell:

```bash
bunx eas-cli update --channel production --environment production --message "Fix totals"
bunx sentry-expo-upload-sourcemaps dist
```

**You should see:** in Sentry, an error from a release build or an update pointing at your
TypeScript file and line, not at `index.bundle`.

## Check it [#check-it]

<Cmd>
  bun run doctor
</Cmd>

<Cmd>
  bun run typecheck
</Cmd>

Every analytics, crash and consent row should be green, and typecheck should pass.

## If it doesn't work [#if-it-doesnt-work]

* **Nothing arrives even after consent** - the key isn't set, or Metro still has the old env.
  Check `.env` and restart with `bun run start -- -c`.
* **The sheet never shows** - the device's region isn't in the ask group and `askEverywhere` is
  off, or you already answered on this install. Set `askEverywhere: true` and reinstall.
* **The first screen view of each launch is missing** - with `storage=async-storage` the consent
  record loads asynchronously, and events fired before it loads are dropped rather than sent
  without a known answer. `kv-store` and MMKV load it synchronously.
* **Stack traces are minified** - the three `SENTRY_*` keys are missing from the EAS environment,
  or you didn't run `sentry-expo-upload-sourcemaps` after the update.
* **Works locally, silent in a build** - the `EXPO_PUBLIC_*` keys aren't on EAS. See
  [A key works locally but not in an EAS build](https://readynative.app/docs/troubleshooting#a-key-works-locally-but-not-in-an-eas-build).

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

You can see how people use the app and where it breaks - with their consent, tied to their
account, and with stack traces you can read. To take a module out again, see <If cat="analytics" is="amplitude">[Amplitude → Remove it](https://readynative.app/docs/features/analytics/amplitude#remove-it)</If><If cat="analytics" is="posthog|none">[PostHog → Remove it](https://readynative.app/docs/features/analytics/posthog#remove-it)</If> and [Sentry → Remove it](https://readynative.app/docs/features/crash/sentry#remove-it).

Next, give the app its own backend in the cloud:
[Deploy your API routes](https://readynative.app/docs/deploy-api-routes).


# Add push notifications (/docs/add-push)



<Badge>
  Pro
</Badge>

Hey - by the end of this page your phone shows a push notification you sent from your terminal,
and tapping it opens the screen you chose - from the background and from a cold start.

The module does the plumbing: `@/lib/push` asks for permission and fetches the Expo push token,
`PushProvider` shows notifications while the app is open, creates the Android `default` channel
and deep-links to `data.url` on tap, and `bun run push:test` sends one message through Expo's
push service. You add the Apple and Google credentials and a place in your UI to ask for
permission.

## Before you start [#before-you-start]

* **Tier:** Pro. The push module isn't in Free or Starter.
* **Time:** about 45 minutes, plus a dev build.
* **Runs in:** a dev build on a **physical** phone. Expo Go can't receive remote push since SDK
  53, and simulators never can - see
  [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build).
* **Accounts:** the Apple Developer Program (iOS), a
  [Firebase](https://console.firebase.google.com) project (Android), and a free
  [Expo account](https://expo.dev/signup) - step 2 links the EAS project.
* **Previous tutorial:** [Add a paywall](https://readynative.app/docs/add-a-paywall).

**Picked `push=expo-notifications` at setup?** Skip step 1. Step 1 needs `modules/`, so it works
only in a tree set up with `--keep-modules`; a finalized tree without push starts from a fresh
clone - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## 1. Add the module [#1-add-the-module]

<Cmd>
  bun run setup --push expo-notifications --yes --keep-modules
</Cmd>

Push needs a dev build, so `setup` also switches `bun run start` to `expo start --dev-client`.

**You should see:** `src/lib/push.ts`, `src/hooks/use-push-token.ts` and `scripts/push-test.ts`
in your tree, and a `push:test` script in `package.json`.

## 2. Link the EAS project [#2-link-the-eas-project]

The token request needs your EAS project id. If `app.easProjectId` in `readynative.config.ts`
is still empty:

```bash
bunx eas-cli login
bunx eas-cli init
```

`eas init` only prints the id - paste it into `app.easProjectId`. With an empty id, the push
hook reports `unsupported` and warns in the console. If the project belongs to an organisation,
also set `app.owner` to its slug.

<Cmd>
  bun run doctor
</Cmd>

**You should see:** "EAS project linked" green.

## 3. Add the iOS credentials [#3-add-the-ios-credentials]

Apple delivers push through APNs, which needs a key from your developer account. EAS stores
the key per bundle id:

```bash
bunx eas-cli credentials --platform ios
```

Pick a build profile, then **Push Notifications**, and set up a key: sign in with your Apple
account and let EAS create one, or upload a `.p8` you made in the Apple Developer portal →
**Certificates, Identifiers & Profiles → Keys** with &#x2A;*Apple Push Notifications service (APNs)**
ticked. Your dev build uses the `.dev` bundle id, so run the command for the `development`
profile as well as `production`.

**You should see:** the push key listed for your bundle id when you run the command again.

## 4. Add the Android credentials [#4-add-the-android-credentials]

Android delivers push through Firebase Cloud Messaging (FCM v1).

1. In the [Firebase console](https://console.firebase.google.com), create a project and add an
   Android app for each package that will receive push - your production package from
   `readynative.config.ts`, and the same with `.dev` for your dev build.

2. Download `google-services.json` (it covers every Android app in the project) and put it at
   the repo root. It's configuration, not a secret, and EAS needs it in git to see it.

3. Tell the build about it - in `app.config.ts`, add one line to the `android` block:

   ```ts title="app.config.ts"
     android: {
       googleServicesFile: "./google-services.json",
       // ...the existing adaptiveIcon, package and other keys stay as they are
     },
   ```

4. In Firebase, open **Project settings → Service accounts → Generate new private key**. That JSON
   is what lets Expo's servers send through FCM - keep it out of git.

5. Upload it to EAS:

   ```bash
   bunx eas-cli credentials --platform android
   ```

   Pick a profile, then **Google Service Account → Manage your Google Service Account Key for
   Push Notifications (FCM V1) → Set up → Upload a new service account key**.

**You should see:** the FCM V1 key listed under your Android app's credentials on expo.dev.

## 5. Show the token in your app [#5-show-the-token-in-your-app]

`push.usePushToken()` returns `{ token, status }` (`status` is `"loading"`, `"unsupported"`,
`"denied"` or `"granted"`), and `push.requestPermission()` shows the OS prompt. Ask when it makes
sense in your flow, not on first launch. Here's a card to drop into Settings or any screen while
you test:

```tsx title="src/components/push-card.tsx"
import * as Clipboard from "expo-clipboard";

import { Box, Button, Card, Text, toast } from "@/components/ui";
import { push } from "@/lib/push";

export function PushCard() {
  const { token, status } = push.usePushToken();

  const allow = () => {
    push
      .requestPermission()
      .then((granted) => {
        if (!granted) toast.show({ title: "Notifications are off", kind: "error" });
      })
      .catch(() => toast.show({ title: "Couldn't ask for permission", kind: "error" }));
  };

  const copy = (value: string) => {
    Clipboard.setStringAsync(value)
      .then(() => toast.show({ title: "Token copied", kind: "success" }))
      .catch(() => toast.show({ title: "Couldn't copy", kind: "error" }));
  };

  return (
    <Card>
      <Box gap={3}>
        <Text variant="heading">Push notifications</Text>
        <Text variant="caption">Status: {status}</Text>
        {token ? <Text variant="code">{token}</Text> : null}
        {status !== "granted" ? <Button onPress={allow}>Allow notifications</Button> : null}
        {token ? (
          <Button variant="outline" onPress={() => copy(token)}>
            Copy token
          </Button>
        ) : null}
      </Box>
    </Card>
  );
}
```

For example, render `<PushCard />` inside the `<Box>` of `src/screens/home/home-screen.tsx`.
`expo-clipboard` came with the module.

**You should see:** `bun run typecheck` passing. The card shows up on the dev build in the next
step.

## 6. Build and install on your phone [#6-build-and-install-on-your-phone]

Credentials and `google-services.json` are native, so build now. On EAS:

```bash
bunx eas-cli build --profile development --platform ios
bunx eas-cli build --profile development --platform android
```

(iOS installs only on registered devices - `bunx eas-cli device:create` first.) Or locally with
a phone plugged in:

<Cmd>
  bunx expo run:ios --device
</Cmd>

Then start the dev server for it:

<Cmd>
  bun run start:dev
</Cmd>

**You should see:** the push card with status `denied` (iOS reports "not asked yet" as `denied`
too). Tap **Allow notifications**, accept the OS dialog, and an `ExponentPushToken[…]` appears.
Tap **Copy token**.

## 7. Send yourself a push [#7-send-yourself-a-push]

Background the app (or lock the phone), then from the repo root:

<Cmd>
  bun run push:test "ExponentPushToken[paste-yours]" "Hello" "It works" --url /settings
</Cmd>

The arguments are the token, an optional title and body, and `--url`, the route the app opens on
tap. Without `--url` it opens `/examples/push`, which exists only with `--with-examples`. It
prints `Sent. Ticket …`.

**You should see:** the notification within a few seconds. Tap it and the app opens on Settings.
Kill the app, send again and tap: the same screen, from a cold start. With the app open, the
banner still shows - that's the foreground handler.

The ticket only means Expo accepted the message. Delivery errors such as `DeviceNotRegistered`
or bad credentials show up in the push receipt, which you fetch with the ticket id - the link the
script prints explains how. Or paste the token into
[expo.dev/notifications](https://expo.dev/notifications) to send and inspect from the browser.

## Check it [#check-it]

<Cmd>
  bun run doctor
</Cmd>

<Cmd>
  bun run typecheck
</Cmd>

Every push row should be green, and typecheck should pass.

## If it doesn't work [#if-it-doesnt-work]

* **Status stays `unsupported`** - you're in Expo Go or a simulator, or `app.easProjectId` is
  empty. See [The push token is null](https://readynative.app/docs/troubleshooting#the-push-token-is-null).
* **No token on Android** - `google-services.json` is missing, not referenced from
  `app.config.ts`, or has no app for the package you're running (dev builds use `.dev`). Fix it
  and rebuild.
* **`Sent`, but nothing arrives** - check the push receipt for the ticket. `InvalidCredentials`
  means the APNs key or FCM V1 key isn't on EAS for this app; `DeviceNotRegistered` means the
  token is stale - reopen the app for a fresh one.
* **Arrives, but the tap opens Home** - `--url` must be a route that exists, starting with `/`.
* **Nothing on Android while the app is open for a long time** - check the app's notification
  settings on the phone: the `default` channel may be muted.

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

You sent a push from your terminal to your phone and landed on a screen from the tap. In
production, store each user's token on your server and send with `data: { url }` from there. To
take the module out again, see
[Expo Notifications → Remove it](https://readynative.app/docs/features/push/expo-notifications#remove-it).

Next, see how people use the app and where it breaks:
[Add analytics and crash reporting](https://readynative.app/docs/add-analytics-and-crash).


# Add sign-in (/docs/add-sign-in)



<Badge>
  Pro
</Badge>

Hey - by the end of this page you'll sign up and sign in on the simulator, see your email in
Settings, reset a forgotten password, and have signed-out users sent to the sign-in screen
automatically.

The screens are already written: `src/app/(auth)/sign-in`, `sign-up` and `reset` with
`src/screens/auth/*` (Supabase adds `new-password`, where the reset link lands), plus
`src/hooks/use-auth-redirect.ts`, which sends signed-out users to `/(auth)/sign-in` and
signed-in users out of `(auth)` - onboarding still comes first. You add the keys and the
dashboard settings.

## Before you start [#before-you-start]

* **Tier:** Pro. The auth modules aren't in Free or Starter.
* **Time:** about 45 minutes, most of it in the provider's dashboard.
* **Runs in:** Expo Go, all three options. Sign in with Apple runs natively on iOS, and Google
  opens the system browser.
* **Accounts:** <If cat="auth" is="clerk">a [Clerk](https://clerk.com) account.</If><If cat="auth" is="better-auth">none - Better Auth runs on your own API routes (a Postgres database before you ship).</If><If cat="auth" is="supabase|none">a [Supabase](https://supabase.com) account.</If> An Apple Developer account only for Sign in with Apple, and a Google Cloud project only for Google sign-in.
* **Previous tutorial:** [Add your first feature](https://readynative.app/docs/first-feature).

**Picked an auth option at setup?** Skip step 1. Step 1 needs `modules/`, so it works only in a
tree set up with `--keep-modules`; a finalized tree without auth starts from a fresh clone - see
[Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## 1. Add the module [#1-add-the-module]

<If cat="auth" is="clerk">
  <Cmd>
    bun run setup --auth clerk --yes --keep-modules
  </Cmd>
</If>

<If cat="auth" is="better-auth">
  <Cmd>
    bun run setup --auth better-auth --backend api-routes --yes --keep-modules
  </Cmd>

  Better Auth runs on your own server, so it requires `backend=api-routes`; setup refuses it with
  any other backend.
</If>

<If cat="auth" is="supabase|none">
  <Cmd>
    bun run setup --auth supabase --yes --keep-modules
  </Cmd>

  <If cat="auth" is="none">
    Your stack toggle says `auth=none`, where `auth.useSession()` always reports signed-out. The
    steps below follow Supabase, the default; pick Clerk or Better Auth in the toggle above to switch
    them.
  </If>
</If>

Drop `--keep-modules` to let setup finalize the tree afterwards.

**You should see:** setup finish with the auth module in its summary, and `src/lib/auth.ts` plus
`src/app/(auth)/` in your tree.

## 2. Paste the keys [#2-paste-the-keys]

Copy `.env.example` to `.env` if you haven't yet - `setup` lists every key your stack needs in
it:

```bash
cp .env.example .env
```

<If cat="auth" is="clerk">
  Create an application at [clerk.com](https://clerk.com), open **API keys**, and copy the
  publishable key:

  ```bash title=".env"
  EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
  ```

  Without it, `ClerkProvider` never mounts: `useSession()` stays `unauthenticated`, there's no
  redirect, and the sign-in screen shows "Configure Clerk".
</If>

<If cat="auth" is="better-auth">
  Better Auth needs the origin of your API routes, a server secret and its base URL. The two
  server keys have no `EXPO_PUBLIC_` prefix, which would ship them to every device.

  ```bash title=".env"
  EXPO_PUBLIC_API_URL=http://192.168.1.20:8081
  BETTER_AUTH_SECRET=paste-the-output-of-openssl-here
  BETTER_AUTH_URL=http://192.168.1.20:8081
  ```

  Use your computer's LAN IP (a phone can't reach `localhost`), and generate the secret with:

  ```bash
  openssl rand -base64 32
  ```

  Without `EXPO_PUBLIC_API_URL`, the module is disabled and sign-in shows "Configure
  EXPO\_PUBLIC\_API\_URL".
</If>

<If cat="auth" is="supabase|none">
  Create a project at [supabase.com](https://supabase.com), open **Project Settings → API** and
  copy two values:

  ```bash title=".env"
  EXPO_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
  EXPO_PUBLIC_SUPABASE_ANON_KEY=eyJ...
  ```

  Until both are set, auth is disabled: no redirect, `useSession()` stays `unauthenticated`, and
  the sign-in screen shows "Configure Supabase". Both keys are public - row-level security is what
  protects your data.
</If>

Restart with a clean cache so Expo inlines the new keys:

<Cmd>
  bun run start -- -c
</Cmd>

**You should see:** after onboarding, the app lands on the sign-in screen instead of Home.

## 3. Set up the dashboard [#3-set-up-the-dashboard]

<If cat="auth" is="clerk">
  In the Clerk dashboard:

  1. **User & Authentication → Email, phone, username**: enable **Email address** and
     **Password**, with verification set to **Email verification code**. The shipped sign-up and
     reset screens expect the code step.
  2. **SSO connections → Apple**: enable it and add your iOS bundle id under "Apple → Native".
     Then turn on the Sign in with Apple capability for that bundle id in the Apple Developer
     portal → **Certificates, Identifiers & Profiles → Identifiers**.
  3. **SSO connections → Google**: enable it. Development instances use Clerk's shared
     credentials, so there's nothing to paste yet.
  4. **Native applications**: add the iOS bundle id and the Android package from
     `readynative.config.ts`, so Clerk accepts native requests from your app.

  Every screen in order is on the [Clerk page](https://readynative.app/docs/features/auth/clerk#setup).
</If>

<If cat="auth" is="better-auth">
  Better Auth has no dashboard - it's `src/server/auth.ts`. For this tutorial the shipped
  in-memory database is fine (every user is gone when the dev server restarts). Before you ship,
  swap it for Postgres and plug an email provider into `src/server/email.ts`; Apple and Google
  need their own client ids. The [Better Auth page](https://readynative.app/docs/features/auth/better-auth#setup) covers
  all of it.

  Check the server is up:

  ```bash
  curl -s http://localhost:8081/api/health
  ```
</If>

<If cat="auth" is="supabase|none">
  In the Supabase dashboard:

  1. **Authentication → URL Configuration → Redirect URLs**: add `trailmix://` and
     `trailmix://new-password`, using the `scheme` from your `readynative.config.ts`. In Expo Go
     the links start with `exp://<lan-ip>:8081/--/` instead, so also add `exp://**` - on your
     development project only. Without these, the Google and password-reset round trips never
     come back to the app.
  2. **Authentication → Providers → Email**: leave "Confirm email" on. Sign-up then asks the user
     to confirm by email before the first sign-in.
  3. **Authentication → Providers → Apple** (optional): enable it and set Client IDs to your iOS
     bundle id. The native flow uses `signInWithIdToken`, so no Services ID is needed. Turn on the
     Sign in with Apple capability for that bundle id in the Apple Developer portal →
     **Certificates, Identifiers & Profiles → Identifiers**.
  4. **Authentication → Providers → Google** (optional): enable it with a **Web** OAuth client from
     Google Cloud Console → **APIs & Services → Credentials**, and paste Supabase's callback URL
     into that client's authorized redirect URIs. The app never needs a Google client id.
</If>

<Cmd>
  bun run doctor
</Cmd>

**You should see:** every auth row green.

## 4. Sign up and sign in [#4-sign-up-and-sign-in]

Open the app, tap **Sign up**, and create an account with an email you can read.

<If cat="auth" is="clerk">
  Clerk emails a 6-digit code; enter it on the next screen and you're signed in.
</If>

<If cat="auth" is="better-auth">
  Better Auth signs you in straight away - the shipped setup sends no confirmation email.
</If>

<If cat="auth" is="supabase|none">
  A toast says "Check your email". Open the email, confirm, then sign in with the same email and
  password.
</If>

**You should see:** Home, and in **Settings** an **Account** card with your email (or your name
with the email under it, when the provider has one), plus **Sign out** and **Delete account**.
Kill the app and reopen it: you're still signed in.

## 5. Reset a password [#5-reset-a-password]

On the sign-in screen, tap &#x2A;*Forgot password?** and enter your email.

<If cat="auth" is="clerk">
  Clerk emails a code. Enter it, then choose the new password on the next screen.
</If>

<If cat="auth" is="better-auth">
  Reset emails go through `src/server/email.ts`, which logs a notice in dev until you plug in a
  provider (Resend, Postmark or your own) - see
  [Better Auth → Sending email](https://readynative.app/docs/features/auth/better-auth#sending-email). Come back to this
  step once it sends.
</If>

<If cat="auth" is="supabase|none">
  The email's link opens the app on the **new password** screen (`/(auth)/new-password`). Enter
  the new password twice.
</If>

**You should see:** "Password updated", and the new password works on the next sign-in.

<If cat="auth" is="supabase|none">
  Open the same link again and it says "This link is invalid or has expired" - each link works
  once.
</If>

## 6. Use the session in your code [#6-use-the-session-in-your-code]

`@/lib/auth` is the same API whichever option you picked, so this code survives a switch.
Here's a small component that shows who's signed in - drop it into any screen, for example above
the form in the Notes screen from [Add your first feature](https://readynative.app/docs/first-feature):

```tsx title="src/components/signed-in-as.tsx"
import { Text } from "@/components/ui";
import { auth } from "@/lib/auth";

export function SignedInAs() {
  const session = auth.useSession();
  if (session.status !== "authenticated") return null;
  return <Text variant="caption">Signed in as {session.user.email ?? session.user.id}</Text>;
}
```

`session.status` is `"loading"`, `"unauthenticated"` or `"authenticated"`, and only the last one
has a `user` (`id`, and `email` / `name` when the provider has them).

With `backend=api-routes`, call your own API as that user by attaching the credentials the
server checks:

```ts title="src/lib/api/me.ts"
import { auth } from "@/lib/auth";
import { env } from "@/lib/env";

export async function fetchMe(): Promise<{ id: string }> {
  const res = await fetch(`${env.API_URL}/api/me`, { headers: await auth.getAuthHeaders() });
  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
  return (await res.json()) as { id: string };
}
```

`/api/me` is yours to write: resolve the caller with `serverAuth.getRequestUser(request)` from
`src/server/session.ts`, and never trust a user id sent by the app.<If cat="auth" is="clerk"> With Clerk, that needs `CLERK_SECRET_KEY` (server, no
`EXPO_PUBLIC_` prefix) in `.env`.</If> [Deploy your API routes](https://readynative.app/docs/deploy-api-routes) covers
the hosting side.

**You should see:** "Signed in as [you@example.com](mailto:you@example.com)" where you placed `<SignedInAs />`.

## 7. Delete the account [#7-delete-the-account]

The App Store and Google Play both require in-app account deletion, and Settings ships it.

<If cat="auth" is="supabase|none">
  The anon key can't delete users, so the module ships two SQL migrations in
  `supabase/migrations/`: `delete_user()`, and the storage clean-up that runs before it. Apply
  them once per Supabase project. The quickest way is the dashboard: open **SQL Editor**, paste
  the contents of each file in order, and **Run**. Or use the Supabase CLI:

  ```bash
  bunx supabase login
  bunx supabase link --project-ref your-project-ref
  bunx supabase db push
  ```

  The project ref is the `xxxx` in your `EXPO_PUBLIC_SUPABASE_URL`.
</If>

<If cat="auth" is="clerk">
  Clerk deletes the user through `user.delete()`, so there's nothing to apply. With API routes, a
  `user.deleted` webhook can erase the user's analytics and purchase data too - see the
  [Clerk page](https://readynative.app/docs/features/auth/clerk).
</If>

<If cat="auth" is="better-auth">
  The shipped server enables `deleteUser`. Deleting needs a fresh session (signed in within the
  last day, set in `src/lib/auth-policy.ts`), otherwise the app asks for the password first.
</If>

Now open **Settings → Delete account** and confirm.

**You should see:** a success toast and the sign-in screen. Signing in with the old
credentials now fails.

## Check it [#check-it]

<Cmd>
  bun run doctor
</Cmd>

<Cmd>
  bun run typecheck
</Cmd>

Every auth row should be green, and typecheck should pass.

## If it doesn't work [#if-it-doesnt-work]

* **The sign-in screen says "Configure …"** - a key is missing or Metro still has the old env.
  Check `.env`, then restart with `bun run start -- -c`.
* **Google sign-in or the reset link never comes back to the app in Expo Go** - add `exp://**`
  to the Supabase redirect URLs; see
  [Supabase sign-in never comes back in Expo Go](https://readynative.app/docs/troubleshooting#supabase-sign-in-never-comes-back-in-expo-go).
* **Delete account fails and names a migration file** - that migration isn't applied to this
  Supabase project yet. Run it (step 7) and try again; nothing was deleted.
* **Sign in with Apple errors out** - the Sign in with Apple capability isn't on for the bundle
  id you're running. Dev builds use `<your id>.dev`, so register that one too.
* **Works locally, signed out in a build** - `.env` isn't uploaded to EAS; set the keys there.
  See [A key works locally but not in an EAS build](https://readynative.app/docs/troubleshooting#a-key-works-locally-but-not-in-an-eas-build).

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

Your app has accounts: sign-up, sign-in, password reset and account deletion, with the session
persisted through your storage adapter and the redirect hook guarding the app. To take the
module out again, see <If cat="auth" is="clerk">[Clerk → Remove it](https://readynative.app/docs/features/auth/clerk#remove-it)</If><If cat="auth" is="better-auth">[Better Auth → Remove it](https://readynative.app/docs/features/auth/better-auth#remove-it)</If><If cat="auth" is="supabase|none">[Supabase → Remove it](https://readynative.app/docs/features/auth/supabase#remove-it)</If>.

Next, charge for it: [Add a paywall](https://readynative.app/docs/add-a-paywall).


# Add web checkout next to the App Store (/docs/add-web-checkout)



<Badge>
  Pro
</Badge>

Setup picks **one** payments option. This page is for when you want two: in-app purchase
through RevenueCat (StoreKit / Play Billing, Apple's sheet, Face ID) **and** Stripe Checkout on
the web (cards, Apple Pay and Google Pay on Stripe's page) - both unlocking the same `pro`.

The finished version lives in `examples/snap-recipe`. Copy from there; this page explains the
pieces and the rules. It assumes a tree set up with `payments=revenuecat`, `backend=api-routes`
and an auth option, with RevenueCat working as in [Add a paywall](https://readynative.app/docs/add-a-paywall).

The example was set up the other way round - `payments=stripe`, with RevenueCat added by hand as
`examples/snap-recipe/src/lib/store-purchases.ts` - so its files split what your tree has in one place. In a
RevenueCat tree, your `src/lib/payments.ts` is the RevenueCat rail: move it aside and take the
example's `payments.ts` and `store-purchases.ts` together. Picked `payments=stripe`? You already
have the Stripe rail; add `store-purchases.ts`, `react-native-purchases` and
`react-native-purchases-ui`, and the example's paywall. Picked `payments=adapty`? The example
has no Adapty rail: keep the Stripe files from the table, and write your own
`store-purchases.ts` with the same exports on top of the Adapty calls in your current
`src/lib/payments.ts` (Adapty's access levels play the part of RevenueCat's entitlements).

| File in `examples/snap-recipe`                    | What it does                                                                                   |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `examples/snap-recipe/src/lib/store-purchases.ts` | The RevenueCat rail: lazy configure, `logIn` as the signed-in user, native paywall, storefront |
| `src/lib/payments.ts`                             | The Stripe rail + the payments contract: entitlements are the union of both rails              |
| `src/screens/paywall/paywall-screen.tsx`          | App Store plans first, "Or pay by card through Stripe" below - only where allowed              |
| `src/app/api/stripe/*`, `src/server/stripe.ts`    | Checkout session, entitlements lookup, webhook                                                 |

## 1. Start from RevenueCat, add the Stripe server [#1-start-from-revenuecat-add-the-stripe-server]

Pick RevenueCat, API routes and an [auth](https://readynative.app/docs/add-sign-in) option when you run setup - Stripe
needs a signed-in user:

<Cmd>
  bun run setup --payments revenuecat --backend api-routes --auth supabase
</Cmd>

Then bring the server half of Stripe over by hand. `modules/` is gone after setup, but
`examples/snap-recipe` carries the same files: copy `src/server/stripe.ts` and
`src/app/api/stripe/` into your tree (they read the signed-in user through the
`src/server/session.ts` your auth option wrote), add the package with
`bunx expo install stripe`, and set `STRIPE_SECRET_KEY`, `STRIPE_PRICE_ID` and
`STRIPE_WEBHOOK_SECRET` as on the [Stripe page](https://readynative.app/docs/features/payments/stripe#setup).

## 2. One user id on both rails [#2-one-user-id-on-both-rails]

Both dashboards must know the buyer by the same id, or a Stripe subscription and an App Store
subscription belong to two strangers:

* **Stripe**: the checkout route stores `metadata.app_user_id = user.id` on the subscription and
  the entitlements route searches by it.
* **RevenueCat**: call `Purchases.logIn(user.id)` when the session user changes and
  `Purchases.logOut()` on sign-out (`syncStoreUser()` in the example). A purchase made while
  signed out moves to the account on the next `logIn`.

## 3. Merge the entitlements [#3-merge-the-entitlements]

`payments.useEntitlements()` returns the union, so every existing `active.includes("pro")`
check keeps working:

```ts
const store = useStoreEntitlements();
const active = useMemo(
  () => [...new Set([...stripeActive, ...store.active])].sort(),
  [stripeActive, store.active]
);
```

If your RevenueCat entitlement isn't literally `pro`, map it once
(`REVENUECAT_PRO_ENTITLEMENT` in the example) instead of teaching every screen a second name.
Make `restorePurchases()` do both: `Purchases.restorePurchases()` and a fresh Stripe lookup.

## 4. Only show Stripe where App Review allows it [#4-only-show-stripe-where-app-review-allows-it]

Under App Review guideline 3.1.1, digital subscriptions sold inside an iOS app go through
in-app purchase. A link-out to web checkout is allowed on the **US** storefront; elsewhere it can
get the build rejected. Ask StoreKit which storefront the user is on:

```ts
export function canOfferExternalPayments(): Promise<boolean> {
  if (Platform.OS !== "ios" || !configureStore()) return Promise.resolve(true);
  return Purchases.getStorefront()
    .then((s) => ["US", "USA"].includes(s?.countryCode.toUpperCase() ?? ""))
    .catch(() => false);
}
```

The paywall hides the Stripe card when this is `false`. Android and web always show it (check
Google Play's payments policy for your markets).

## 5. Test both [#5-test-both]

* **Store rail**: a RevenueCat Test Store key (`test_…`) shows RevenueCat's simulated purchase
  dialog; the `appl_…` key shows Apple's sheet for a sandbox Apple ID on a device.
* **Stripe rail**: in test mode, the hosted page shows Apple Pay once you enable it under
  Stripe → Settings → Payment methods. The Apple Pay sheet itself needs a Wallet card, so use a
  real iPhone.

## Things to know [#things-to-know]

* **Two subscriptions for one person.** Nothing stops someone who pays on the web from also
  buying in the store on another device. The paywall hides both once `pro` is active on the
  current one; if that isn't enough, check server-side before creating a checkout session.
* **Refunds and cancellations** arrive through RevenueCat's customer-info listener and the
  Stripe webhook - both rails drop the entitlement on their own.
* **Fees differ.** Apple and Google keep 15-30% of store sales; Stripe takes its card fee.
  Price the store product accordingly.
* **The store sheet is not Apple Pay.** It charges the Apple ID's payment method (which may be
  an Apple Pay card). A native Apple Pay button is allowed only for physical goods and
  services, never for unlocking app features.


# Get access (/docs/after-you-buy)



Hey - here's what happens between paying and having the code. By the end you'll have your
private repo cloned and know exactly what your tier gives you. On the Free tier there's nothing
to buy: clone [`ready-native-free`](https://github.com/ReadyNative/ready-native-free) and go to
[Quickstart](https://readynative.app/docs/ship-in-5-minutes).

## 1. Check out on Polar [#1-check-out-on-polar]

[Polar](https://polar.sh) is the merchant of record: it takes the payment, charges the VAT or
sales tax your country needs, and emails the receipt and invoice. Buying for a company? Add the
company name and VAT number at checkout.

## 2. Connect GitHub in the Polar portal [#2-connect-github-in-the-polar-portal]

Repository access is a GitHub benefit on your Polar order. Right after checkout, the thanks page
has a **Connect GitHub to get the repo** button that opens Polar's customer portal for your
order. Missed it? The receipt email from Polar links to the same portal.

In the portal, connect the GitHub account that should get the repo. Each license gives one
GitHub account access; on Pro, you share the code with the developers your license covers.

## 3. Accept the invite [#3-accept-the-invite]

GitHub emails an invitation to the address on that GitHub account, and it also waits at
[github.com/notifications](https://github.com/notifications). Accept it and you're a read-only
collaborator on your tier's private repo.

The invitation expires after 7 days. If it lapses, or you connected the wrong GitHub account,
pick "Paid, no repo access" on [the support form](https://readynative.app/support/?topic=access)
and leave the email you paid with - I'll sort it out.

## 4. Clone it [#4-clone-it]

The repo is private, so git needs your GitHub credentials. Swap `pro` for `starter` if that's
what you bought:

```bash
git clone https://github.com/ReadyNative/ready-native-pro.git my-app
cd my-app
```

`gh repo clone ReadyNative/ready-native-pro my-app` does the same through the GitHub CLI. The clone is
yours to push anywhere: add your own remote and keep going.

## What's in each tier [#whats-in-each-tier]

Here's how the three tiers compare. In a Starter or Pro tree, `.readynative-tier.json` at the
root records the tier and the version you got.

| Tier    | Repo                                        | Who may use it                                               | What you get                                                                                                                                                                                                                                                                        |
| ------- | ------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Free    | `ReadyNative/ready-native-free` (public)    | Anyone (MIT)                                                 | The finished app with one stack already chosen: NativeWind 4, TanStack Query and Zustand, with tabs, settings and dark mode. No `setup`, `doctor` or `gen:*` scripts, no EAS or CI config, no agent files. Runs in Expo Go                                                          |
| Starter | `ReadyNative/ready-native-starter` (invite) | One named individual                                         | The picker: `bun run setup` chooses between every UI, data, state, storage, forms, i18n, onboarding, consent and testing option, with the `minimal` and `default` presets. Plus `doctor`, the `gen:*` generators, `eas.json`, Maestro flows and the agent files. No service modules |
| Pro     | `ReadyNative/ready-native-pro` (invite)     | Up to 5 developers (employees or contractors) in one company | Everything in Starter, plus every service module (auth, payments, analytics, crash reporting, push, backend), the `saas` preset, the two [example apps](https://readynative.app/docs/examples) in `examples/`, the store-review agent skill and `bun run doctor --store`                                   |

Every paid license is perpetual with lifetime updates, and there are no refunds once you have
access, except where the law requires otherwise. The terms are in [License](https://readynative.app/docs/license).

## Next [#next]

Install, pick your stack and run the app: [Quickstart](https://readynative.app/docs/ship-in-5-minutes).


# Do I need a backend? (/docs/backend)



Hey - this is the page I'd read before picking anything in the `backend` category. By the
end you'll know whether your app needs a server at all, how to point ReadyNative at one you
already run, and which one to start with if you have none.

A "backend" is everything that must not live on the phone. Secrets (a Stripe key, an API
token) are readable by anyone who unzips your app, so they need a server. Data that two users
share - a feed, a leaderboard, a team - needs a place both phones can reach. Payments have to
be verified somewhere the buyer can't tamper with, and push notifications are *sent* by a
server, not by the app. If your app is a calculator, a timer or a notes app that syncs
nowhere, you don't need one and `bun run setup --backend none` is the right answer.

The decision is short. **If you already have a backend, use it**: set `EXPO_PUBLIC_API_URL`
and call it through `src/lib/api/client.ts` - the calls are in the
[API routes usage](https://readynative.app/docs/features/backend/api-routes#usage) section. **If you don't, start
with the built-in one**: Expo API routes in the same tree, deployed to EAS Hosting.

## You already have a backend [#you-already-have-a-backend]

Then ReadyNative is a client, and all it needs is the origin. Put it in `.env`:

```bash title=".env"
EXPO_PUBLIC_API_URL=https://api.example.com
```

`setup` lists this key in `.env.example` whenever a data, auth or backend module wants it,
and `src/lib/env.ts` exposes it as `env.API_URL` after zod validation. Relative paths passed
to `fetchJson` resolve against it; absolute URLs pass through:

```ts
import { fetchJson } from "@/lib/api/client";

const me = await fetchJson<{ id: string; email: string }>("/v1/me");
```

Non-2xx responses reject with an `ApiError` carrying `status` and the parsed body, and every
call times out after 15 seconds unless you pass `timeoutMs`. To authenticate, add the header
yourself. `auth.useSession()` from `@/lib/auth` tells you *whether* you're signed in under
every auth option; the token itself comes from the vendor client, because each vendor issues a
different kind. With Supabase:

```ts
import { supabase } from "@/lib/auth";
import { fetchJson } from "@/lib/api/client";

const { data } = await supabase!.auth.getSession();
const token = data.session?.access_token;
await fetchJson("/v1/me", { headers: token ? { authorization: `Bearer ${token}` } : {} });
```

Clerk gives you a JWT through `useAuth().getToken()`, and Better Auth sends a cookie, so its
routes have to live on the same origin as `EXPO_PUBLIC_API_URL`. Each option's page under
[Auth](https://readynative.app/docs/features/auth) shows the call.

Two more things. Native apps don't send an `Origin` header, so CORS never blocks them - but
the web build does, so if you ship to the web, allow your app's web origin (and
`http://localhost:8081` in dev) on the server. And never put a secret behind an `EXPO_PUBLIC_`
prefix: those keys are inlined into the JavaScript bundle and anyone can read them. Your
backend holds the secrets; the app holds only the URL.

## You don't have one yet [#you-dont-have-one-yet]

Here's the ladder I'd climb. Each rung is a complete answer; most apps never leave the first
one.

### Expo API routes on EAS Hosting [#expo-api-routes-on-eas-hosting]

<Badge>
  Pro
</Badge>

This is the `backend/api-routes` module, the default backend in the Pro `saas` preset; it and
the `src/server/*` helpers below only exist in a Pro tree set up with `backend=api-routes`. A
file named `+api.ts` under
`src/app/api/` exports `GET`, `POST` and friends, runs on the dev server while `expo start`
is up, and runs on EAS Hosting (Cloudflare Workers under the hood) once deployed. Both
`auth/better-auth` and `payments/stripe` require it.

* **Good for**: a handful of endpoints, webhooks, hiding a third-party key, the first
  version of almost anything.
* **What you write**: `+api.ts` handlers with the shipped `src/server/json.ts` helpers
  (`handle`, `json`, `readJson` with zod) and `serverEnv()` for secrets.
* **Where it runs**: your dev machine in development, EAS Hosting in production, same repo.
* **Free tier / cost shape**: the free Expo plan includes 100,000 requests a month and 1 GB
  of storage; custom domains need a paid plan.
* **When you outgrow it**: you need a database (pair it with Supabase or a hosted Postgres),
  long-running jobs, websockets, or a Node module the Workers runtime can't load.

First deploy: pick it at setup (`bun run setup --backend api-routes`), then follow
[Deploy your API routes](https://readynative.app/docs/deploy-api-routes) - the local health check, server keys on EAS,
`eas deploy`, and pointing your builds at the hosted URL through an EAS environment.

### Supabase [#supabase]

<Badge>
  Pro
</Badge>

Postgres with a REST API, auth, file storage, realtime and edge functions, all behind one
dashboard. It pairs with `auth/supabase`, so if you picked that auth option you already have
a backend.

* **Good for**: shared data with row-level security, user accounts and files without
  writing a server.
* **What you write**: SQL (tables and policies) and `supabase.from("…")` calls from the
  app; Deno edge functions when you need server code.
* **Where it runs**: Supabase's cloud, in the region you pick.
* **Free tier / cost shape**: two active projects, a 500 MB database, 50,000 monthly
  active users, 1 GB of file storage and 500,000 edge function invocations; free projects
  pause after a week of inactivity.
* **When you outgrow it**: you want business logic in TypeScript rather than SQL policies,
  or a runtime other than Deno for server code.

First deploy:

1. Pick it at setup: <Cmd>bun run setup --auth supabase</Cmd> Already finalized without it?
   Re-clone and re-run setup ([FAQ](https://readynative.app/docs/faq#can-i-change-a-module-after-setup)).
2. Create a project at supabase.com and paste the Project URL and anon key into `.env` as
   `EXPO_PUBLIC_SUPABASE_URL` and `EXPO_PUBLIC_SUPABASE_ANON_KEY`.
3. Create your first table in the SQL editor and turn on row-level security.
4. Query it with the `supabase` client exported from `@/lib/auth` - there's nothing to deploy.

### Convex [#convex]

A reactive database and serverless functions in one, TypeScript end to end: queries you
subscribe to re-run in the app whenever the data changes.

* **Good for**: collaborative and live-updating apps, or when you'd rather never think about
  caching and invalidation.
* **What you write**: `query`, `mutation` and `action` functions in a `convex/` folder,
  called through `useQuery` and `useMutation` in components.
* **Where it runs**: Convex's cloud; `npx convex dev` syncs your functions as you save.
* **Free tier / cost shape**: 1 million function calls, 0.5 GB of database storage and 1 GB
  of file storage included, then pay-as-you-go.
* **When you outgrow it**: you need raw SQL, a specific database engine, or to run on your
  own infrastructure.

First deploy:

1. <Cmd>
     bunx expo install convex
   </Cmd>
2. <Cmd>bunx convex dev</Cmd> creates the `convex/` folder and writes `EXPO_PUBLIC_CONVEX_URL` to
   `.env.local`.
3. Wrap the app in `ConvexProvider` in `src/providers.tsx` with `new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!)`.
4. Add a `query` in `convex/tasks.ts` and read it with `useQuery(api.tasks.get)`.
5. <Cmd>bunx convex deploy</Cmd> pushes to production when you're ready.

### A small server you own [#a-small-server-you-own]

Hono or Express on Railway, Fly.io, Cloudflare Workers or Vercel Functions. Pick this when
the API is the product - many endpoints, background jobs, websockets, a queue, a database you
administer - or when your team already runs one of these hosts.

* **Good for**: anything the rungs above can't run, and teams that want full control.
* **What you write**: a normal HTTP server, plus a `Dockerfile` or a host config file.
* **Where it runs**: Railway and Fly.io run containers (long-lived processes, websockets,
  cron); Cloudflare Workers and Vercel Functions run request handlers that scale to zero.
* **Free tier / cost shape**: Cloudflare Workers gives 100,000 requests a day free and
  $5/month after; Vercel's Hobby plan includes 1 million invocations a month for
  non-commercial use; Railway offers a $5 one-time trial credit and a $5/month Hobby plan;
  Fly.io's trial is 2 machine-hours or 7 days, then usage billing.
* **When you outgrow it**: you don't - this is the top of the ladder. What changes is how
  much of it you operate yourself.

First deploy (Hono on Cloudflare Workers, the cheapest of the four to keep running):

1. <Cmd>bun create hono\@latest my-api</Cmd> and pick the `cloudflare-workers` template.
2. Add a route: `app.get("/health", (c) => c.json({ ok: true }))`.
3. <Cmd>bunx wrangler dev</Cmd> serves it at `http://localhost:8787`.
4. <Cmd>bunx wrangler deploy</Cmd> gives you `https://<worker>.<subdomain>.workers.dev`.
5. Set `EXPO_PUBLIC_API_URL` to that origin and store secrets with `wrangler secret put <NAME>`.

Side by side, the four rungs compare like this:

| Option          | You write            | Runs on                          | Database included?   | Auth included?           | Free tier             |
| --------------- | -------------------- | -------------------------------- | -------------------- | ------------------------ | --------------------- |
| Expo API routes | `+api.ts` handlers   | EAS Hosting                      | no                   | with `auth/better-auth`  | 100k requests/month   |
| Supabase        | SQL + client calls   | Supabase cloud                   | Postgres             | yes (`auth/supabase`)    | 2 projects, 500 MB DB |
| Convex          | TypeScript functions | Convex cloud                     | reactive document DB | via Convex Auth or Clerk | 1M calls/month        |
| Your own server | Hono / Express app   | Railway, Fly.io, Workers, Vercel | bring your own       | bring your own           | varies by host        |

## Things every backend needs [#things-every-backend-needs]

Whichever rung you're on, the same short list keeps you out of trouble:

* **Secrets live on the server.** Locally they go in `.env` under the
  `# server (never EXPO_PUBLIC)` heading; in production they go in the host's secret store
  (`eas env:set --visibility sensitive` for EAS Hosting, `wrangler secret put`, the Railway or Vercel
  dashboard). Read them through `serverEnv()` so a missing key fails at startup, not in a
  request.
* **A `/health` route.** The module ships `GET /api/health`; keep one on any server so you,
  `curl` and your uptime monitor can tell "deployed" from "working".
* **CORS for the web build.** Native ignores it; the browser doesn't. Allow your web origin
  and `http://localhost:8081` explicitly rather than `*` once auth cookies are involved.
* **A version in the path.** `/v1/…` costs nothing today and lets old app builds keep
  working when you change a response shape - phones don't update the day you deploy.
* **Logging you can read.** If you picked `crash/sentry`, add the Sentry server SDK to the
  same project so a failed request and the crash it caused show up together. See
  [Crash reporting](https://readynative.app/docs/features/crash).
* **Rate limiting.** Any route a signed-out user can hit (sign-in, password reset, a webhook)
  needs a per-IP limit - EAS Hosting, Workers and Vercel all have one you can turn on.

<Callout type="info" title="What to deploy first">
  A `/health` route, one real endpoint, and the secret it needs - then point a dev build at the
  hosted URL and tap through the flow on a phone before you write the second endpoint.
</Callout>

## Where the keys go [#where-the-keys-go]

Every option reduces to a few lines in `.env`. `bun run doctor` checks the ones a module marks
as required and prints the dashboard and guide links for each missing one - the rows are
explained in [Doctor](https://readynative.app/docs/doctor).

| Option          | Client keys (`EXPO_PUBLIC_`)                                | Server keys                                                     | `doctor` checks       |
| --------------- | ----------------------------------------------------------- | --------------------------------------------------------------- | --------------------- |
| Expo API routes | `EXPO_PUBLIC_API_URL`                                       | `WEBHOOK_SECRET`                                                | `EXPO_PUBLIC_API_URL` |
| + Better Auth   | `EXPO_PUBLIC_API_URL`                                       | `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `DATABASE_URL`         | the first three       |
| + Stripe        | `EXPO_PUBLIC_API_URL`, `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY` | `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID` | all five              |
| Supabase        | `EXPO_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_ANON_KEY` | none in the app                                                 | both                  |
| Convex          | `EXPO_PUBLIC_CONVEX_URL`                                    | set in the Convex dashboard                                     | not a module; nothing |
| Your own server | `EXPO_PUBLIC_API_URL`                                       | whatever the server reads                                       | nothing               |

The anon key and the publishable key are safe in the client by design; a secret key,
a webhook signing secret or a database URL never is.

## Next [#next]

* [API routes](https://readynative.app/docs/features/backend/api-routes) - the module in detail, with the helpers and the example route.
* [Deploy your API routes](https://readynative.app/docs/deploy-api-routes) - the tutorial that puts them on EAS Hosting.
* [Auth](https://readynative.app/docs/features/auth) - Supabase, Clerk or Better Auth on top of whichever backend you chose.

{/* Research notes (2026-09-15): docs.expo.dev api-routes, eas/hosting/introduction and get-started, expo.dev/pricing, supabase.com pricing, convex.dev pricing and RN quickstart, hono.dev, Cloudflare Workers guide and pricing, vercel.com/docs/functions and plans/hobby, railway.com pricing and quick-start, fly.io free-trial all fetched OK. docs.railway.com/quick-start and fly.io/docs/getting-started carried no pricing, so those numbers come from the pricing pages. EAS Hosting rate limiting is stated generically; the docs pages fetched don't describe a specific feature. */}


# Changelog (/docs/changelog)



{/* Generated by apps/docs/scripts/gen-modules.ts from CHANGELOG.md - do not edit. */}

All notable changes to this project are documented here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions are tagged
`v<version>-sdk<expo major>`, the Expo SDK the release targets.

## \[1.3.0-sdk57] - 2026-09-28 [#130-sdk57---2026-09-28]

### Added [#added]

* A weather demo is the app you see on first run (`bun install && bun ios`): the forecast where you are, an hourly strip, a 10-day list, detail tiles, city search and saved cities, °C / °F, pull to refresh, share and "notify me", a Pro gate on the 10-day forecast. It runs on every module choice and keylessly on [Open-Meteo](https://open-meteo.com); `setup` removes it unless you pass `--with-examples`.
* Native navigation throughout: the tab bar is `NativeTabs` (Liquid Glass on iOS 26, Material 3 on Android), and the demo's Cities tab uses a large-title native stack, `Stack.SearchBar` and `Link.Menu` context menus. `bun run gen screen --tab` writes a `<NativeTabs.Trigger>`.
* `location` category: `expo-location` (foreground position and reverse geocoding behind `@/lib/location`, resolving `null` instead of throwing) or `none`. In the `default` and `saas` presets.
* `widgets` category: `expo-widgets` (an iOS home-screen widget in `@expo/ui` SwiftUI views, fed by `widgets.update()`) or `none`. In the `saas` preset; needs a dev build.
* Six languages in both i18n modules - English, Spanish, Russian, Chinese (Simplified), Portuguese and Arabic - with right-to-left layout: picking Arabic mirrors the app and restarts it. Settings lists languages as rows.
* `@/lib/cache`: an offline cache on the storage adapter; the last good response paints on the first frame and without a connection.
* Native feel in every UI stack: `toast.show()` is a native iOS toast (Burnt) in dev and store builds, with the themed card as the Expo Go / Android / web fallback; `Pressable` runs on Pressto (UI-thread press animation on a gesture-handler button); `<Screen scroll>` is keyboard-controller's `KeyboardAwareScrollView`. The root layout mounts `GestureHandlerRootView` and `KeyboardProvider`.
* `Sheet` primitive in the UI contract: `@expo/ui`'s native bottom sheet (SwiftUI on iOS, Material 3 on Android, a drawer on web), with detents. Works in Expo Go.
* Live Activities: `widgets.activity.start / update / end` with a Lock Screen + Dynamic Island layout in `src/widgets/app-activity.tsx` (widgets/expo-widgets).
* Docs: [No ios/ or android/ folders](https://readynative.app/docs/native-without-native-folders) - how Continuous Native Generation and over-the-air updates fit together.

### Changed [#changed]

* The Explore tab is gone; the weather demo's Cities tab replaces it.
* The onboarding Maestro flow ends on the tab bar instead of the Home title.

## \[1.2.1-sdk57] - 2026-09-27 [#121-sdk57---2026-09-27]

### Removed [#removed]

* The GitHub Actions workflows (`.github/workflows/ci.yml`, `eas-preview.yml`): the repo no longer runs CI or EAS builds on GitHub. Build and submit with `eas build` / `eas submit`; add your own CI if you want one ([Expo's guide](https://docs.expo.dev/eas-update/github-actions/)). `setup` still re-renders a `ci.yml` you kept from 1.2.0 for your package manager.

### Fixed [#fixed]

* `bun run typecheck` on a fresh clone: Expo's global types are now referenced from the committed `expo-types.d.ts` (the generated `expo-env.d.ts` is gitignored and only appears after `expo start`).
* `bun run test` before setup: the UI stack's jest mocks (the `@/global.css` stub) load without `.readynative.json`.
* `docs/graph.json` / `docs/ARCHITECTURE.md` now match the tree you receive, so `bun run gen:graph --check` passes out of the box.
* README links point to the docs at [https://readynative.app/docs/](https://readynative.app/docs/).

## \[1.2.0-sdk57] - 2026-09-25 [#120-sdk57---2026-09-25]

First public release, on Expo SDK 57 (Expo 57.0.24, React Native 0.86, Expo Router 57, React 19.2).

### Added [#added-1]

* Module system: every optional feature lives in `modules/<category>/<option>/`; `bun run setup` applies a preset (`minimal`, `default`, `saas`) or a per-category selection, generates `src/providers.tsx`, `src/lib/env.ts`, `.env.example` and `.readynative.json`, and stays idempotent. Setup then finalizes the tree into a plain Expo Router app (`modules/` and the setup tooling removed, `src/ui` → `src/components/ui`); `--keep-modules` keeps the module system.
* Five UI stacks behind one component contract: NativeWind 4 (the default: stable `4.2.7` on Tailwind 3, in every preset), NativeWind 5 (RC · Tailwind 4, `5.0.0-rc.0`, one `--ui nativewind5` away), Tamagui, Unistyles and plain StyleSheet, with `bun run gen:theme` deriving each stack's theme from `src/theme/tokens.ts` and the brand in `readynative.config.ts`.
* App-layer modules: data (TanStack Query, Apollo, SWR), state (Zustand, Jotai), storage (expo-sqlite/kv-store, MMKV, AsyncStorage), forms (react-hook-form), i18n (i18next, Lingui; English and Spanish, with a language picker in Settings), onboarding flow.
* Service modules (Pro), each with a no-op shim for its `none` option: auth (Supabase, Clerk, Better Auth), payments (RevenueCat, Stripe, Adapty), analytics (PostHog, Amplitude), crash (Sentry), push (expo-notifications), backend (API routes).
* Account deletion on every auth module (Supabase via a shipped `delete_user()` migration, Clerk `user.delete()`, Better Auth `deleteUser`) and a confirm-guarded "Delete account" row in Settings.
* Payments: `presentPaywall()` shows RevenueCat's native paywall only to users without the entitlement and falls back to `/paywall` (auto-renewal disclosure, "Compare all plans", "Manage subscription"); RevenueCat follows the signed-in user. A guide covers web checkout next to the App Store: RevenueCat and Stripe Checkout with one `pro` entitlement across both rails (`examples/snap-recipe` is the reference).
* Feature flags on the analytics contract: `analytics.isFeatureEnabled(key)`, `analytics.getFeatureFlag(key)` and `useFeatureFlag(key)` (PostHog; Amplitude and `none` read `undefined`).
* App Tracking Transparency with the analytics modules: `expo-tracking-transparency`, `src/lib/tracking.ts`, and a one-time prompt when `features.tracking` is on in `readynative.config.ts`.
* Privacy and consent: a `consent` category whose default asks once (EU/EEA, UK, Switzerland, Canada, Brazil, or no device region) with Analytics / Crash reports toggles. PostHog, Amplitude and Sentry follow the choice, and Sentry events are scrubbed of IP, email, username, headers and cookies. Settings → Privacy adds "Do not sell or share my personal information" and "Export my data"; sign-out and account deletion wipe local data.
* Store paperwork from the modules: every module declares its privacy data. Setup composes the Apple privacy manifest (`ios.privacyManifests`) and the Play Data safety rows, and `bun run gen:privacy` writes a privacy-policy draft to `docs/privacy-policy.md`.
* `bun run doctor`: env keys (with a dashboard link and a docs guide for each missing one), native toolchains and runtime versions in one checklist; store identity (placeholder ids, urls, store ids, EAS link and login, the placeholder app icon) is listed under "Before you ship" as warnings, so a fresh setup exits 0. `bun run doctor --store` (Pro) checks the app against the App Store Review Guidelines and Google Play policies, with a guideline id and a fix per finding.
* Package manager of your choice: setup detects bun / pnpm / yarn / npm (or `--pm`), installs with it, drops the other lockfiles and renders CI for it. `scripts/*.ts` run under plain Node 22.18+ (`setup` and `doctor` check it first); bun is the recommended default.
* First run in Expo Go: `start` is `expo start --go` when every selected module runs there and `expo start --dev-client` otherwise; `start:dev` always targets the dev build. Module tools such as `push:test` survive setup and run under any package manager.
* `bun run gen:graph` writes `docs/graph.json` + `docs/ARCHITECTURE.md`, the app as one graph (modules, providers, routes, screens, libs, env keys); CI checks it stays current.
* Agent skills in `.agents/skills/` (`readynative`, `expo-router`, `expo-native-ui`, `expo-data-fetching`; Pro adds `store-review`).
* `examples/` (Pro): Field Notes and Snap Recipe, standalone apps that boot with no `.env` (`cd examples/notes && bun install && bun ios`).
* Always-on extras: icon / splash / favicon from `assets/brand/icon.png` (`bun run gen:assets`), universal and app links (`bun run gen:links`), updates banner, store review prompt, clipboard / share / browser helpers, root error boundary, and the iOS 27 UIScene life cycle (`plugins/with-scene-lifecycle.js`).
* CI and EAS workflows: typecheck, lint, test and the architecture graph on every push; EAS preview builds on pull requests and production build + submit on your own `v*` tags.
* Every preset and every module option is set up, typechecked, linted, bundled and tested in CI before a release ships.
* Free tier: `readynative-free`, a public MIT repo with one fixed stack (Expo Router, NativeWind 4, TanStack Query, Zustand, `expo-sqlite/kv-store`), already set up: no `modules/`, no setup, no EAS / CI / scripts.
* Licensing: Starter and Pro ship under the ReadyNative Commercial License, the Free tier under MIT; third-party notices (the Expo template's MIT text) are in `LICENSES/`.


# Stack comparison (/docs/choose-your-stack)



{/* Generated by apps/docs/scripts/gen-modules.ts from every modules/<category>/<option>/module.json - do not edit. */}

Every option of every category side by side. `bun run setup` asks one question per category; every answer is a module under `modules/<category>/<option>/`. Non-interactive: `bun run setup --preset default --ui tamagui --auth supabase --yes`. This page is generated from the same `module.json` files `setup` reads, so it can't drift from what ships. For how to choose, read [Pick your stack](https://readynative.app/docs/pick-your-stack) first.

## Presets [#presets]

| Category     | `minimal`     | `default`         | `saas`               |
| ------------ | ------------- | ----------------- | -------------------- |
| `ui`         | `nativewind4` | `nativewind4`     | `nativewind4`        |
| `data`       | `none`        | `react-query`     | `react-query`        |
| `state`      | `none`        | `zustand`         | `zustand`            |
| `storage`    | `kv-store`    | `kv-store`        | `kv-store`           |
| `forms`      | `none`        | `react-hook-form` | `react-hook-form`    |
| `i18n`       | `none`        | `i18next`         | `i18next`            |
| `auth`       | `none`        | `none`            | `supabase`           |
| `payments`   | `none`        | `none`            | `revenuecat`         |
| `analytics`  | `none`        | `none`            | `posthog`            |
| `crash`      | `none`        | `none`            | `sentry`             |
| `push`       | `none`        | `none`            | `expo-notifications` |
| `backend`    | `none`        | `none`            | `api-routes`         |
| `onboarding` | `off`         | `on`              | `on`                 |
| `location`   | `none`        | `expo-location`   | `expo-location`      |
| `widgets`    | `none`        | `none`            | `expo-widgets`       |
| `consent`    | `none`        | `none`            | `consent`            |
| `testing`    | `none`        | `jest`            | `jest`               |

The committed tree equals `setup --preset default`; `saas` is `default` plus every service category turned on.

## UI (`ui`) [#ui-ui]

| Option                                         | Label                  | Expo Go                 | Hint                                                                                 |
| ---------------------------------------------- | ---------------------- | ----------------------- | ------------------------------------------------------------------------------------ |
| [`nativewind4`](https://readynative.app/docs/features/ui/nativewind4) | NativeWind 4 (default) | yes                     | Stable · Tailwind 3 classes + RNR components behind @/ui · Expo Go OK                |
| [`nativewind5`](https://readynative.app/docs/features/ui/nativewind5) | NativeWind 5           | yes                     | RC · Tailwind 4 classes behind @/ui · Expo Go OK                                     |
| [`tamagui`](https://readynative.app/docs/features/ui/tamagui)         | Tamagui                | yes                     | Tamagui 2 (v5 config, optimising compiler) behind @/ui · Expo Go OK                  |
| [`unistyles`](https://readynative.app/docs/features/ui/unistyles)     | Unistyles 3            | no - dev build required | C++ StyleSheet with themes/breakpoints behind @/ui · dev build required (no Expo Go) |
| [`stylesheet`](https://readynative.app/docs/features/ui/stylesheet)   | StyleSheet (plain RN)  | yes                     | no style engine, tokens + StyleSheet.create · Expo Go OK                             |

## Data (`data`) [#data-data]

| Option                                           | Label                                            | Expo Go | Hint                                             |
| ------------------------------------------------ | ------------------------------------------------ | ------- | ------------------------------------------------ |
| [`react-query`](https://readynative.app/docs/features/data/react-query) | TanStack Query (default) (most people pick this) | yes     | server state + cache · Expo Go OK                |
| [`apollo`](https://readynative.app/docs/features/data/apollo)           | Apollo Client                                    | yes     | GraphQL client + normalized cache · Expo Go OK   |
| [`swr`](https://readynative.app/docs/features/data/swr)                 | SWR                                              | yes     | stale-while-revalidate hooks · Expo Go OK        |
| [`none`](https://readynative.app/docs/features/data/none)               | No data layer                                    | yes     | plain fetch; add TanStack Query/Apollo/SWR later |

## State (`state`) [#state-state]

| Option                                    | Label                                     | Expo Go | Hint                                                        |
| ----------------------------------------- | ----------------------------------------- | ------- | ----------------------------------------------------------- |
| [`zustand`](https://readynative.app/docs/features/state/zustand) | Zustand (default) (most people pick this) | yes     | tiny stores, persisted on the storage adapter · Expo Go OK  |
| [`jotai`](https://readynative.app/docs/features/state/jotai)     | Jotai                                     | yes     | atomic state, persisted on the storage adapter · Expo Go OK |
| [`none`](https://readynative.app/docs/features/state/none)       | No state library                          | yes     | built-in useSyncExternalStore stores only                   |

* [`zustand`](https://readynative.app/docs/features/state/zustand): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`
* [`jotai`](https://readynative.app/docs/features/state/jotai): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`

## Storage (`storage`) [#storage-storage]

| Option                                                  | Label                                                  | Expo Go                 | Hint                                                             |
| ------------------------------------------------------- | ------------------------------------------------------ | ----------------------- | ---------------------------------------------------------------- |
| [`kv-store`](https://readynative.app/docs/features/storage/kv-store)           | expo-sqlite/kv-store (default) (most people pick this) | yes                     | sync + async key/value on SQLite · Expo Go OK                    |
| [`mmkv`](https://readynative.app/docs/features/storage/mmkv)                   | MMKV                                                   | no - dev build required | fastest sync key/value (Nitro) · dev build required (no Expo Go) |
| [`async-storage`](https://readynative.app/docs/features/storage/async-storage) | AsyncStorage                                           | yes                     | async-only key/value, the community standard · Expo Go OK        |

## Forms (`forms`) [#forms-forms]

| Option                                                    | Label                                             | Expo Go | Hint                                                  |
| --------------------------------------------------------- | ------------------------------------------------- | ------- | ----------------------------------------------------- |
| [`react-hook-form`](https://readynative.app/docs/features/forms/react-hook-form) | React Hook Form (default) (most people pick this) | yes     | Form + Field on @/ui Input, zod resolver · Expo Go OK |
| [`none`](https://readynative.app/docs/features/forms/none)                       | No forms library                                  | yes     | controlled @/ui Inputs with useState                  |

## i18n (`i18n`) [#i18n-i18n]

| Option                                   | Label                                     | Expo Go | Hint                                                                                          |
| ---------------------------------------- | ----------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| [`i18next`](https://readynative.app/docs/features/i18n/i18next) | i18next (default) (most people pick this) | yes     | react-i18next + expo-localization, 6 languages bundled incl. Arabic (RTL) · Expo Go OK        |
| [`lingui`](https://readynative.app/docs/features/i18n/lingui)   | Lingui                                    | yes     | @lingui/core + @lingui/react runtime API, 6 languages bundled incl. Arabic (RTL) · Expo Go OK |
| [`none`](https://readynative.app/docs/features/i18n/none)       | No i18n                                   | yes     | i18n.t/useT return the English key                                                            |

* [`i18next`](https://readynative.app/docs/features/i18n/i18next): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`
* [`lingui`](https://readynative.app/docs/features/i18n/lingui): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`

## Auth (`auth`) [#auth-auth]

| Option                                           | Label                                           | Expo Go | Hint                                                                                          |
| ------------------------------------------------ | ----------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| [`supabase`](https://readynative.app/docs/features/auth/supabase)       | Supabase Auth (default) (most people pick this) | yes     | email+password, Apple (native), Google (OAuth) · session on the storage adapter · Expo Go OK  |
| [`clerk`](https://readynative.app/docs/features/auth/clerk)             | Clerk                                           | yes     | email+code verification, Apple (native), Google (SSO) · @clerk/expo · Expo Go OK for JS flows |
| [`better-auth`](https://readynative.app/docs/features/auth/better-auth) | Better Auth                                     | yes     | self-hosted on the API routes · email/password + Apple/Google · Expo Go OK                    |
| [`none`](https://readynative.app/docs/features/auth/none)               | No auth                                         | yes     | auth.useSession() shim returns signed-out, signOut resolves                                   |

* [`supabase`](https://readynative.app/docs/features/auth/supabase): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`; needs `EXPO_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_ANON_KEY`
* [`clerk`](https://readynative.app/docs/features/auth/clerk): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`; needs `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`
* [`better-auth`](https://readynative.app/docs/features/auth/better-auth): requires `backend` ∈ `api-routes`; needs `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`

## Payments (`payments`) [#payments-payments]

| Option                                             | Label                                        | Expo Go                 | Hint                                                                     |
| -------------------------------------------------- | -------------------------------------------- | ----------------------- | ------------------------------------------------------------------------ |
| [`revenuecat`](https://readynative.app/docs/features/payments/revenuecat) | RevenueCat (default) (most people pick this) | no - dev build required | in-app subscriptions + paywall · dev build required (no Expo Go)         |
| [`adapty`](https://readynative.app/docs/features/payments/adapty)         | Adapty                                       | no - dev build required | in-app subscriptions + Paywall Builder · dev build required (no Expo Go) |
| [`stripe`](https://readynative.app/docs/features/payments/stripe)         | Stripe Checkout                              | yes                     | web checkout via API routes (no native SDK) · Expo Go OK                 |
| [`none`](https://readynative.app/docs/features/payments/none)             | No payments                                  | yes                     | payments.useEntitlements() shim returns none                             |

* [`revenuecat`](https://readynative.app/docs/features/payments/revenuecat): needs `EXPO_PUBLIC_REVENUECAT_IOS_KEY`, `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY`
* [`adapty`](https://readynative.app/docs/features/payments/adapty): needs `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`
* [`stripe`](https://readynative.app/docs/features/payments/stripe): requires `backend` ∈ `api-routes`; needs `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID`

## Analytics (`analytics`) [#analytics-analytics]

| Option                                            | Label                                     | Expo Go | Hint                                                                                         |
| ------------------------------------------------- | ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| [`posthog`](https://readynative.app/docs/features/analytics/posthog)     | PostHog (default) (most people pick this) | yes     | product analytics + feature flags (analytics.isFeatureEnabled / useFeatureFlag) · Expo Go OK |
| [`amplitude`](https://readynative.app/docs/features/analytics/amplitude) | Amplitude                                 | yes     | product analytics · Expo Go OK (JS SDK, storage adapter)                                     |
| [`none`](https://readynative.app/docs/features/analytics/none)           | No analytics                              | yes     | analytics.track/identify/screen are no-ops, feature flags read undefined                     |

* [`posthog`](https://readynative.app/docs/features/analytics/posthog): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`; needs `EXPO_PUBLIC_POSTHOG_KEY`
* [`amplitude`](https://readynative.app/docs/features/analytics/amplitude): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`; needs `EXPO_PUBLIC_AMPLITUDE_KEY`

## Crash reporting (`crash`) [#crash-reporting-crash]

| Option                                  | Label                                    | Expo Go | Hint                                                      |
| --------------------------------------- | ---------------------------------------- | ------- | --------------------------------------------------------- |
| [`sentry`](https://readynative.app/docs/features/crash/sentry) | Sentry (default) (most people pick this) | yes     | JS + native crash reporting · Expo Go OK (JS errors only) |
| [`none`](https://readynative.app/docs/features/crash/none)     | No crash reporting                       | yes     | crash.capture is a no-op                                  |

* [`sentry`](https://readynative.app/docs/features/crash/sentry): needs `EXPO_PUBLIC_SENTRY_DSN`

## Push notifications (`push`) [#push-notifications-push]

| Option                                                         | Label                                                | Expo Go                 | Hint                                                                                               |
| -------------------------------------------------------------- | ---------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| [`expo-notifications`](https://readynative.app/docs/features/push/expo-notifications) | Expo Notifications (default) (most people pick this) | no - dev build required | Expo push service + local notifications · dev build required for remote push (Expo Go: local only) |
| [`none`](https://readynative.app/docs/features/push/none)                             | No push notifications                                | yes                     | nothing registered                                                                                 |

* [`expo-notifications`](https://readynative.app/docs/features/push/expo-notifications): requires `storage` ∈ `kv-store` | `mmkv` | `async-storage`

## Backend (`backend`) [#backend-backend]

| Option                                            | Label                                        | Expo Go | Hint                                                                       |
| ------------------------------------------------- | -------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| [`api-routes`](https://readynative.app/docs/features/backend/api-routes) | API routes (default) (most people pick this) | yes     | Expo Router +api.ts routes · src/server helpers · EAS Hosting · Expo Go OK |
| [`none`](https://readynative.app/docs/features/backend/none)             | No API routes                                | yes     | no src/app/api                                                             |

## Onboarding (`onboarding`) [#onboarding-onboarding]

| Option                                 | Label                     | Expo Go | Hint                                                   |
| -------------------------------------- | ------------------------- | ------- | ------------------------------------------------------ |
| [`on`](https://readynative.app/docs/features/onboarding/on)   | Onboarding flow (default) | yes     | 3-slide intro at /onboarding, redirect until completed |
| [`off`](https://readynative.app/docs/features/onboarding/off) | No onboarding             | yes     | app opens straight into the tabs                       |

## Location (`location`) [#location-location]

| Option                                                   | Label                                           | Expo Go | Hint                                                                            |
| -------------------------------------------------------- | ----------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| [`expo-location`](https://readynative.app/docs/features/location/expo-location) | Expo Location (default) (most people pick this) | yes     | foreground position + reverse geocoding, permission states handled · Expo Go OK |
| [`none`](https://readynative.app/docs/features/location/none)                   | No location                                     | yes     | no permission prompt, no expo-location                                          |

## Home-screen widgets (`widgets`) [#home-screen-widgets-widgets]

| Option                                                | Label                                          | Expo Go                 | Hint                                                                                                                                           |
| ----------------------------------------------------- | ---------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`expo-widgets`](https://readynative.app/docs/features/widgets/expo-widgets) | Expo Widgets (default) (most people pick this) | no - dev build required | iOS home-screen widget + Live Activity (Lock Screen, Dynamic Island) in SwiftUI (@expo/ui), fed from the app · dev build required (no Expo Go) |
| [`none`](https://readynative.app/docs/features/widgets/none)                 | No widgets                                     | yes                     | no app extension, widgets.update() is a no-op                                                                                                  |

## Privacy consent (`consent`) [#privacy-consent-consent]

| Option                                      | Label                                                         | Expo Go | Hint                                                                                                                       |
| ------------------------------------------- | ------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| [`consent`](https://readynative.app/docs/features/consent/consent) | Consent sheet (GDPR / CCPA) (default) (most people pick this) | yes     | asks before analytics + crash start (EU/EEA, UK, Switzerland, Canada, Brazil or everywhere); Settings toggles · Expo Go OK |
| [`none`](https://readynative.app/docs/features/consent/none)       | No consent sheet                                              | yes     | consent.get() reads all-true; analytics and crash SDKs start as before                                                     |

## Testing (`testing`) [#testing-testing]

| Option                                | Label                                                    | Expo Go | Hint                                              |
| ------------------------------------- | -------------------------------------------------------- | ------- | ------------------------------------------------- |
| [`jest`](https://readynative.app/docs/features/testing/jest) | Jest + Testing Library (default) (most people pick this) | yes     | jest-expo preset, RNTL, tests for stores/theme/ui |
| [`none`](https://readynative.app/docs/features/testing/none) | No test runner                                           | yes     | no jest; module tests are removed                 |


# Config (/docs/config)



## `readynative.config.ts` [#readynativeconfigts]

The one file you edit. It must stay importable under plain Node (no React Native imports;
only *types* from `src/`), because `app.config.ts` reads it while Expo resolves the native
config. The shape is `ReadyNativeConfig` from `src/lib/readynative-config.ts`.

| Block      | Field                                    | Meaning                                                                                      |
| ---------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
| `app`      | `name`                                   | Display name under the icon; variants append ` (Dev)` / ` (Preview)`                         |
|            | `slug`                                   | Expo project slug (EAS)                                                                      |
|            | `scheme`                                 | Deep-link scheme, e.g. `readynative` → `readynative://`                                      |
|            | `owner`                                  | Expo account / organisation slug owning the EAS project; empty → omitted                     |
|            | `easProjectId`                           | EAS project id printed by `bunx eas-cli init`; feeds `extra.eas.projectId` + `updates.url`   |
|            | `ios.bundleId`                           | iOS bundle identifier; variants append `.dev` / `.preview`                                   |
|            | `android.package`                        | Android application id; same suffix rule                                                     |
| `brand`    | `primary`                                | Hex colour; overrides the light `primary` token                                              |
|            | `accent`                                 | Hex colour; exposed as the `brandAccent` token                                               |
|            | `radius`                                 | Base corner radius in px (`radius.lg`); the other steps derive from it                       |
|            | `font`                                   | Font family name for the `fontFamily` token; you load the font file (see below)              |
| `urls`     | `website`, `support`, `privacy`, `terms` | Used by the settings screen; `support` may be a `mailto:` URL                                |
| `store`    | `appStoreId`                             | Numeric App Store id for review prompts / store links                                        |
|            | `playPackage`                            | Play Store package (usually equals `app.android.package`)                                    |
| `links`    | `domain`                                 | Bare host for iOS universal links / Android App Links (`app.example.com`). Empty → links off |
|            | `appleTeamId`                            | 10-character Apple Team ID; prefixes the AASA app ids                                        |
|            | `androidCertFingerprints`                | SHA-256 fingerprints of the Android signing certs (`eas credentials` prints them)            |
| `features` | `reviewPrompt`                           | Ask for a store review (`expo-store-review`)                                                 |
|            | `updatesBanner`                          | Show the "update available" banner backed by `expo-updates`                                  |

Who reads it:

* `app.config.ts` - names, bundle ids, scheme, `associatedDomains` / `intentFilters`.
* `src/theme/tokens.ts` - `brand` → colour, radius and `fontFamily` tokens (then
  `bun run gen:theme`).
* The settings screen - `urls`, `store`, `features`.
* `bun run doctor` - flags the `com.acme.app` placeholders, empty URLs / store ids, a
  `links.domain` without `appleTeamId` / `androidCertFingerprints`, and an unlinked EAS project
  (`app.easProjectId` empty and no `EAS_PROJECT_ID`) or a missing `updates.url`.
* `bun run gen:links` - `links` → `public/.well-known/apple-app-site-association` and
  `assetlinks.json`.

Import it in app code through `@/lib/readynative` (ESLint blocks direct imports of
`readynative.config`).

### Brand font [#brand-font]

`brand.font` is only a name. Nothing in the tree loads a font file, so until you do, the name
points at a font the device doesn't have and text falls back to the system font. Put the file
under `assets/fonts/` and load it under exactly the name in `brand.font`, holding the splash
screen until it's ready:

```tsx title="src/app/_layout.tsx"
import { useFonts } from "expo-font";

export default function RootLayout() {
  const [fontsLoaded] = useFonts({
    Inter: require("@/assets/fonts/Inter-Regular.ttf"),
  });

  useEffect(() => {
    if (!fontsLoaded) return;
    hydrateThemeMode().finally(() => {
      SplashScreen.hideAsync().catch((err: unknown) => {
        console.warn("[splash] hideAsync failed", err);
      });
    });
  }, [fontsLoaded]);

  if (!fontsLoaded) return null;
  // …the existing return
}
```

`expo-font` is already a dependency and `useFonts` works in Expo Go. The token reaches text
through the `stylesheet` and `unistyles` kits; with NativeWind set the family in your Tailwind
theme, with Tamagui in `tamagui.config.ts`. Each weight is its own file - load `Inter-Bold` under
its own name if you need real bold on Android.

### Universal links [#universal-links]

`links` is always wired but off until `domain` is set:

1. Set `domain`, `appleTeamId` and `androidCertFingerprints`.
2. `bun run gen:links` writes the two well-known files for the prod, preview and dev bundle
   ids into `public/.well-known/`. Host them over https at that domain - `expo export -p web`
   ships `public/` as-is, so the web build living there is enough.
3. Rebuild the native app: `associatedDomains` and `intentFilters` are native config that
   `app.config.ts` emits only when `links.domain` is non-empty.

Test on a simulator with `npx uri-scheme open https://<domain>/x --ios` (or `--android`).

## `app.config.ts` and variants [#appconfigts-and-variants]

`app.config.ts` is hand-written and stays that way; modules never edit it. It derives three
variants from `APP_VARIANT` (default `dev`):

| `APP_VARIANT` | Name suffix  | Bundle id / package suffix | EAS profile   |
| ------------- | ------------ | -------------------------- | ------------- |
| `dev`         | ` (Dev)`     | `.dev`                     | `development` |
| `preview`     | ` (Preview)` | `.preview`                 | `preview`     |
| `prod`        | *(none)*     | *(none)*                   | `production`  |

So `com.acme.app` becomes `com.acme.app.dev` for the dev build and all three can be installed
side by side. `eas.json` sets `APP_VARIANT` and `EXPO_PUBLIC_APP_VARIANT` per profile; locally
they come from `.env` (`.env.example` starts with `APP_VARIANT=dev`). The value is also exposed
as `extra.appVariant` and validated in `src/lib/env.ts`.

Other fixed choices in `app.config.ts`: `runtimeVersion: { policy: "appVersion" }`, typed
routes and the React Compiler on (`experiments`), and `web.output: "static"`.

`owner`, `extra.eas.projectId` and `updates.url` all come from `readynative.config.ts`:
`easProjectId` (or `EAS_PROJECT_ID`, which wins) becomes `extra.eas.projectId` and
`updates.url: https://u.expo.dev/<projectId>`. While the id is empty the whole `updates` key is
omitted - an empty URL would break `expo-updates`. `owner` is omitted when empty. See
[Ship to TestFlight](https://readynative.app/docs/ship-to-testflight#2-link-the-eas-project).

### Module app patch [#module-app-patch]

Modules contribute native config through `module.json` → `app.expo` (config plugins, extra
keys). `setup` merges every selected module's patch into `.readynative.json` → `modules.app`, and
`app.config.ts` applies it at load time: `plugins` are appended unique by plugin id, other
keys are deep-merged. Example: `push/expo-notifications` adds the `expo-notifications`
plugin, `auth/supabase` adds `expo-apple-authentication`.

## `.readynative.json` [#readynativejson]

Written by `setup`, read by `app.config.ts` and `doctor`:

```json
{
  "version": 1,
  "preset": "default",
  "selection": { "ui": "nativewind4", "data": "react-query", "...": "..." },
  "applied": true,
  "modules": {
    "app": { "expo": { "plugins": ["expo-apple-authentication"] } },
    "postSetup": ["Supabase: create a project, …"],
    "doctor": [{ "type": "env", "keys": ["EXPO_PUBLIC_SUPABASE_URL"], "module": "supabase" }]
  },
  "keepModules": true
}
```

`preset` is `null` when the selection matches no preset. `keepModules: false` plus a different
selection on the next `setup` run is the error that tells you `modules/` is gone.

## Environment keys [#environment-keys]

`.env` (gitignored) holds every key; `.env.example` (generated) lists them per module with a
`# docs:` link. Rules:

* Public keys start with `EXPO_PUBLIC_` and are the only ones rendered into `src/lib/env.ts`,
  each as `z.string().optional()` - a missing key degrades the module ("Configure X"), it never
  crashes at import time.
* `server: true` keys (`STRIPE_SECRET_KEY`, `BETTER_AUTH_SECRET`, …) have no prefix, live under
  the `# server (never EXPO_PUBLIC)` section, are read with `process.env.X` only in
  `src/app/api/**` / `src/server/**`, and never reach the bundle.
* `bun run doctor` checks every `required: true` key plus explicit `doctor` entries.


# Deploy your API routes (/docs/deploy-api-routes)



<Badge>
  Pro
</Badge>

Hey - by the end of this page your API routes answer at `https://your-app.expo.app`, with their
server keys set on EAS, and your builds call that URL instead of your laptop.

While you develop, `bun run start` serves `src/app/api/**` from the dev server. A release build
has no dev server, so anything that talks to your routes - Stripe Checkout, Better Auth, account
deletion - needs them deployed first.

## Before you start [#before-you-start]

* **Tier:** Pro. The `backend=api-routes` module isn't in Free or Starter.
* **Time:** about 30 minutes.
* **Runs in:** anything - the routes run on EAS Hosting, not on the device, so Expo Go works too.
* **Accounts:** an Expo account with a linked EAS project
  ([Ship to TestFlight](https://readynative.app/docs/ship-to-testflight#2-link-the-eas-project) has the commands). EAS
  Hosting has a free tier.
* **Previous tutorial:** [Add analytics and crash reporting](https://readynative.app/docs/add-analytics-and-crash).

**Picked `backend=api-routes` at setup?** Skip step 1. Step 1 needs `modules/`, so it works only
in a tree set up with `--keep-modules`; a finalized tree without it starts from a fresh clone -
see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## 1. Add the module [#1-add-the-module]

<Cmd>
  bun run setup --backend api-routes --yes --keep-modules
</Cmd>

It patches the app config with `web.output: "server"`, which is what makes API routes build (the
static web export is off while it's selected), and adds `src/app/api/health+api.ts`,
`src/app/api/echo+api.ts`, `src/app/api/privacy/delete+api.ts` and the helpers in
`src/server/`.

**You should see:** `src/app/api/` and `src/server/` in your tree.

## 2. Run the routes locally [#2-run-the-routes-locally]

<Cmd>
  bun run start
</Cmd>

In another terminal:

```bash
curl -s http://localhost:8081/api/health
```

**You should see:** `{"ok":true,"version":"1.0.0","variant":"dev"}` - the version is the one in
`package.json`.

## 3. Put the server keys on EAS [#3-put-the-server-keys-on-eas]

Deployed routes read their keys from an EAS environment, never from your `.env`. Server keys
(no `EXPO_PUBLIC_` prefix) go in as `sensitive` - **not** `secret`, which EAS Hosting can't
deploy. `EXPO_PUBLIC_*` keys your routes read (the Supabase ones, for example) go in as
`plaintext`. [Environment variables → On EAS](https://readynative.app/docs/environment-variables#on-eas) explains the
three visibilities.

```bash
bunx eas-cli env:set --name WEBHOOK_SECRET --value your-random-string --environment production --visibility sensitive
```

The others depend on your stack:

| Your stack                  | Server keys                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `payments=stripe`           | `STRIPE_SECRET_KEY`, `STRIPE_PRICE_ID`, `STRIPE_WEBHOOK_SECRET` (live values)                                            |
| `auth=better-auth`          | `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` (the deployed origin), `DATABASE_URL`                                            |
| `auth=clerk`                | `CLERK_SECRET_KEY` (or `CLERK_JWT_KEY`), `CLERK_WEBHOOK_SIGNING_SECRET`                                                  |
| `auth=supabase`             | none - `EXPO_PUBLIC_SUPABASE_URL` and `_ANON_KEY` as `plaintext`                                                         |
| Account deletion (optional) | `POSTHOG_PERSONAL_API_KEY` + `POSTHOG_PROJECT_ID`, `AMPLITUDE_API_KEY` + `AMPLITUDE_SECRET_KEY`, `REVENUECAT_SECRET_KEY` |

```bash
bunx eas-cli env:list --environment production
```

**You should see:** every key your routes read, in the `production` environment.

## 4. Deploy [#4-deploy]

A server deploy runs in this order: pull the environment so the export sees the same values,
export the web bundle (which carries the API routes), then deploy with the same environment:

```bash
bunx eas-cli env:pull --environment production
bunx expo export --platform web
bunx eas-cli deploy --environment production
```

`env:pull` writes `.env.local`, which also wins over `.env` in local development - delete it
once the deploy is done. The first `eas deploy` asks you to pick a preview subdomain, say
`trailmix`. Re-run the export before every deploy.

**You should see:** a preview URL such as `https://trailmix--abc123xyz.expo.app` and a link to the
deployment on expo.dev.

## 5. Smoke-test it [#5-smoke-test-it]

```bash
curl -s https://trailmix--abc123xyz.expo.app/api/health
```

**You should see:** `{"ok":true,...}`. The `variant` field reads `dev` on a deploy - it
reflects `EXPO_PUBLIC_APP_VARIANT`, which only builds set.

Happy with it? Promote it to the production URL:

```bash
bunx eas-cli deploy --prod --environment production
```

That deploys `dist/` again as the production deployment, at `https://trailmix.expo.app`.

## 6. Point the app at it [#6-point-the-app-at-it]

`EXPO_PUBLIC_API_URL` is compiled into each build and update, so set it per EAS environment: the
production URL for `production` and, if you want a staging backend, an alias for `preview`
(`bunx eas-cli deploy --alias staging` gives you `https://trailmix--staging.expo.app`):

```bash
bunx eas-cli env:set --name EXPO_PUBLIC_API_URL --value https://trailmix.expo.app --environment production --visibility plaintext
bunx eas-cli env:set --name EXPO_PUBLIC_API_URL --value https://trailmix--staging.expo.app --environment preview --visibility plaintext
```

Then ship it: a new build ([Ship to TestFlight](https://readynative.app/docs/ship-to-testflight)) or, since it's only a
JavaScript value, an update ([Your first update](https://readynative.app/docs/your-first-update)):

```bash
bunx eas-cli update --channel production --environment production --message "Use hosted API"
```

Keep `http://<lan-ip>:8081` in your local `.env` for development.

**You should see:** the installed build reach the hosted routes with your laptop's dev server
stopped - for example, the Stripe paywall shows its price, or Better Auth signs you in.

## 7. Re-wire what depends on it [#7-re-wire-what-depends-on-it]

Anything registered against your dev URL needs the deployed one now:

* **Stripe** (`/api/stripe/checkout`, `/entitlements`, `/webhook`, `/return`): in live mode, add a
  webhook endpoint at `https://trailmix.expo.app/api/stripe/webhook` and set its `whsec_…` as
  `STRIPE_WEBHOOK_SECRET` - see [Add a paywall](https://readynative.app/docs/add-a-paywall).
* **Better Auth** (`/api/auth/*`): `BETTER_AUTH_URL` must be the deployed origin, and every OAuth
  redirect URI (`https://trailmix.expo.app/api/auth/callback/google`, `…/apple`) re-registered
  against it. Swap the memory database for Postgres before real users arrive.
* **Account deletion** (`/api/privacy/delete`): Settings → Delete account calls it before the
  auth provider deletes the user, to erase them in PostHog, Amplitude and RevenueCat when those
  server keys are set. It answers 503 until server auth is configured.
* **Clerk** (`/api/webhooks/clerk`): point the `user.deleted` webhook at the deployed URL.

After changing keys, run step 4 again - a deploy reads the environment at deploy time.

**You should see:** if you use Stripe, successful deliveries to the new endpoint on the Stripe
dashboard's webhook page.

## Check it [#check-it]

```bash
curl -s https://trailmix.expo.app/api/health
```

<Cmd>
  bun run doctor
</Cmd>

The health route should answer `{"ok":true,...}`, and every backend row should be green.

## If it doesn't work [#if-it-doesnt-work]

* **404 on every `/api/*` URL** - the export ran without the module's `web.output: "server"`, or
  you deployed an old `dist/`. Run `bunx expo export --platform web` again, then deploy.
* **500 from a route that works locally** - a server key is missing from the environment you
  deployed with, or it's stored as `secret`. Fix it with `env:set --visibility sensitive` and
  deploy again.
* **The app still calls your laptop** - the build or update was made before
  `EXPO_PUBLIC_API_URL` was set on EAS, or a leftover `.env.local` overrode it locally. Publish
  an update with `--environment production`.
* **iOS refuses the request** - the URL must be https; EAS Hosting always is, so check for a
  leftover `http://` value.
* **Local dev suddenly uses production values** - delete the `.env.local` that `env:pull` wrote.

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

Your backend is live on EAS Hosting, with its keys on EAS and every build pointed at it - so
Checkout, sign-in and account deletion work without your laptop. To take the module out again,
see [API routes → Remove it](https://readynative.app/docs/features/backend/api-routes#remove-it). For when to outgrow
API routes, read [Do I need a backend?](https://readynative.app/docs/backend).

Next, get a build to testers: [Ship to TestFlight](https://readynative.app/docs/ship-to-testflight).


# Doctor (/docs/doctor)



<Cmd>
  bun run doctor
</Cmd>

It prints one line per check and exits non-zero if any of them failed. `✓` is fine, `!` is
advisory, `✗` fails the run, and `-` means the check didn't apply to your selection.

Store and release identity - the bundle id, package, app name, `urls`, store ids, the EAS
project link, `eas whoami` and the placeholder app icon - is expected to be unset on day one, so
those rows are grouped at the end under **Before you ship** as `!`: a fresh `default` setup exits 0. `bun run doctor --store` turns every one of them into `✗`, because by then they block a
submission.

```
✓ .readynative.json present  (preset saas)
✗ EXPO_PUBLIC_SUPABASE_URL (auth/supabase)  (missing in .env · dashboard: https://supabase.com/dashboard · guide: https://readynative.app/docs/features/auth/supabase#setup)
✓ package manager  (bun (bun.lock))

Before you ship:
! readynative.config.ts app.ios.bundleId set  (still "com.acme.app" - set your own reverse-DNS id)
! app icon replaced  (assets/images/icon.png is the ReadyNative placeholder - …)
```

## The rows [#the-rows]

| Row                                  | Green when                                                                                                                                         | If it's red                                                                     |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `.readynative.json present`          | `setup` has run and applied a selection. The detail shows the preset, or `custom`                                                                  | Run `bun run setup`                                                             |
| One row per env key                  | The key is set in `.env` or in the process environment                                                                                             | Follow the two links in the detail (below)                                      |
| `readynative.config.ts` placeholders | No `com.acme.app`, no default app name, no empty `urls` or `store` ids (before you ship), and a `links.domain` that has a team id and fingerprints | Fill them in - see [Config](https://readynative.app/docs/config)                                       |
| `app icon replaced`                  | `assets/images/icon.png` and `assets/brand/icon.png` are not the shipped placeholder (before you ship)                                             | Put your 1024px PNG at `assets/brand/icon.png` and run `bun run gen:assets`     |
| `eas whoami`                         | You're logged in (before you ship). Skipped entirely when `eas-cli` is not installed                                                               | `bunx eas-cli login` - see [Ship to TestFlight](https://readynative.app/docs/ship-to-testflight)       |
| Xcode / Android SDK                  | `xcode-select -p` resolves and `ANDROID_HOME` is set. Only checked when a selected module is `expoGo: false`                                       | Install the toolchain, or build the dev build on EAS instead                    |
| `bun >= 1.2` / `node >= 22.18`       | Both runtimes are on your PATH and recent enough (bun only fails for a bun tree)                                                                   | Install Node 24 LTS: below 22.18 node cannot run `scripts/*.ts`                 |
| `package manager`                    | Always. It reports the answer rather than judging it: `pnpm (pnpm-lock.yaml)`                                                                      | See [Package managers](https://readynative.app/docs/package-managers) if it isn't the one you expected |

## The two links on a missing key [#the-two-links-on-a-missing-key]

A missing env key prints where to get it and how to wire it up:

```
missing in .env · dashboard: <the vendor's page> · guide: <the setup walkthrough on this site>
```

The **dashboard** link comes from the module's `env[].docsUrl` - the exact vendor page that
issues that key. The **guide** link is the `#setup` anchor of the module's Features page here,
which is the numbered walkthrough naming every dashboard screen in order. Either part is
dropped when a module doesn't carry it, so a keyless module still reads as a sentence.

`setup` prints the same guide link once per selected service when it finishes, so you can start
collecting keys before you ever run `doctor`.

## The docs link at the bottom [#the-docs-link-at-the-bottom]

After the checklist, `doctor` prints:

```
Docs for your stack: https://readynative.app/docs/?stack=ui:nativewind4,auth:supabase,…
```

That query string is your `.readynative.json` selection. Open it and this whole site switches to
your stack: the tutorials show your options' code, the Features tree hides what you didn't pick.
You can also set it by hand in the **Your stack** panel at the top of the sidebar, or load it
there with &#x2A;*Import `.readynative.json`**.

Point the links at a local docs server by setting `READYNATIVE_DOCS_URL`.

## Running it elsewhere [#running-it-elsewhere]

`--root <dir>` runs the checks against another checkout:

<Cmd>
  bun run doctor --root ../my-other-app
</Cmd>


# Environment variables (/docs/environment-variables)



Every key lives in `.env` at the repo root (gitignored). `bun run setup` generates
`.env.example` with exactly the keys your selection needs, each with a `# docs:` link to the
dashboard that issues it; copy it to `.env` and fill in what you use. `bun run doctor` flags
the required ones that are still empty.

There are two kinds, and the prefix decides which:

* **`EXPO_PUBLIC_*` keys are public.** Metro inlines them into the JavaScript bundle, so anyone
  with the app can read them. Only publishable / anon / SDK keys belong here. They're typed in
  `src/lib/env.ts` as optional: a missing key makes its module show a "Configure X" state
  instead of crashing. Restart with `bun run start -- -c` after changing one.
* **Keys without the prefix are server-only.** They're read with `process.env.X` inside
  `src/app/api/**` and `src/server/**` (API routes, Pro with `backend=api-routes`) and never
  reach the bundle. Never rename
  one to `EXPO_PUBLIC_`. Build-time keys (`APP_VARIANT`, `SENTRY_AUTH_TOKEN`, …) work the same
  way: `app.config.ts` and config plugins read them while EAS builds, and the app never sees
  them.

## Template [#template]

Present in every tree, whatever you picked. The Free tier has no `eas.json`, so the per-profile
values don't apply there.

| Variable                  | Kind       | Default | What it does                                                                                            |
| ------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_APP_VARIANT` | public     | `dev`   | `dev` / `preview` / `prod` at runtime; set per profile in `eas.json`                                    |
| `EXPO_PUBLIC_API_URL`     | public     | -       | Base URL for relative requests (data clients, API routes, Stripe, Better Auth). Use `https` on a device |
| `APP_VARIANT`             | build time | `dev`   | Picks the name and bundle-id suffix in `app.config.ts`; set per profile in `eas.json`                   |
| `EAS_PROJECT_ID`          | build time | -       | Overrides `app.easProjectId`; feeds `extra.eas.projectId` and `updates.url`                             |

`EXPO_PUBLIC_API_URL` on a physical iPhone must be `https://`, a LAN IP, `localhost` or
`*.local`: App Transport Security blocks plain `http://` to anything else, and `src/lib/env.ts`
warns in dev when it sees one.

## Modules [#modules]

Only the modules you selected add keys. Every row below is a Pro module (auth, payments,
analytics, crash, backend) except `data/apollo`, which Starter can pick too; the
`backend/api-routes` rows, `src/server/webhooks` included, exist only in a Pro tree set up
with `backend=api-routes`. **Required** means the module stays in its
"Configure" state (and `doctor` fails) until the key is set.

| Variable                             | Module              | Kind       | Required       | What it is                                                                              |
| ------------------------------------ | ------------------- | ---------- | -------------- | --------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_SUPABASE_URL`           | auth/supabase       | public     | yes            | Project URL (Supabase → Project settings → API)                                         |
| `EXPO_PUBLIC_SUPABASE_ANON_KEY`      | auth/supabase       | public     | yes            | Anon / publishable key                                                                  |
| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`  | auth/clerk          | public     | yes            | Clerk publishable key                                                                   |
| `CLERK_SECRET_KEY`                   | auth/clerk          | server     | for API routes | Clerk secret key (`sk_…`); lets API routes verify the caller's session token            |
| `CLERK_JWT_KEY`                      | auth/clerk          | server     | no             | JWT public key (PEM), verifies tokens networkless instead of `CLERK_SECRET_KEY`         |
| `BETTER_AUTH_SECRET`                 | auth/better-auth    | server     | yes            | Session signing secret, `openssl rand -base64 32`                                       |
| `BETTER_AUTH_URL`                    | auth/better-auth    | server     | yes            | Callback base URL, same as `EXPO_PUBLIC_API_URL`                                        |
| `DATABASE_URL`                       | auth/better-auth    | server     | no             | Postgres connection string for persistent users and sessions                            |
| `APPLE_CLIENT_ID`                    | auth/better-auth    | server     | no             | Apple Services ID for Sign in with Apple                                                |
| `APPLE_CLIENT_SECRET`                | auth/better-auth    | server     | no             | Apple client secret (JWT)                                                               |
| `GOOGLE_CLIENT_ID`                   | auth/better-auth    | server     | no             | Google OAuth client id                                                                  |
| `GOOGLE_CLIENT_SECRET`               | auth/better-auth    | server     | no             | Google OAuth client secret                                                              |
| `EXPO_PUBLIC_REVENUECAT_IOS_KEY`     | payments/revenuecat | public     | yes            | RevenueCat public SDK key for iOS (`appl_…`)                                            |
| `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY` | payments/revenuecat | public     | yes            | RevenueCat public SDK key for Android (`goog_…`)                                        |
| `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`      | payments/adapty     | public     | yes            | Adapty public SDK key                                                                   |
| `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID`    | payments/adapty     | public     | no (`default`) | Placement whose paywall is shown                                                        |
| `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY` | payments/stripe     | public     | yes            | Stripe publishable key (`pk_…`)                                                         |
| `STRIPE_SECRET_KEY`                  | payments/stripe     | server     | yes            | Stripe secret key (`sk_…`)                                                              |
| `STRIPE_WEBHOOK_SECRET`              | payments/stripe     | server     | yes            | Webhook signing secret (`whsec_…`)                                                      |
| `STRIPE_PRICE_ID`                    | payments/stripe     | server     | yes            | Recurring price id (`price_…`)                                                          |
| `STRIPE_ENTITLEMENT`                 | payments/stripe     | server     | no (`pro`)     | Entitlement an active or trialing subscription grants                                   |
| `STRIPE_ALLOW_ANONYMOUS`             | payments/stripe     | server     | no (`false`)   | `true` lets checkout run with auth `none`, trusting client ids - demos only             |
| `EXPO_PUBLIC_POSTHOG_KEY`            | analytics/posthog   | public     | yes            | PostHog project API key                                                                 |
| `EXPO_PUBLIC_POSTHOG_HOST`           | analytics/posthog   | public     | no (US cloud)  | `https://eu.i.posthog.com` for the EU cloud                                             |
| `EXPO_PUBLIC_AMPLITUDE_KEY`          | analytics/amplitude | public     | yes            | Amplitude API key                                                                       |
| `EXPO_PUBLIC_SENTRY_DSN`             | crash/sentry        | public     | yes            | Sentry DSN                                                                              |
| `SENTRY_ORG`                         | crash/sentry        | build time | no             | Org slug, for source map uploads on native builds                                       |
| `SENTRY_PROJECT`                     | crash/sentry        | build time | no             | Project slug, same purpose                                                              |
| `SENTRY_AUTH_TOKEN`                  | crash/sentry        | build time | no             | Auth token with `project:releases` + `org:read`; without it, stack traces stay minified |
| `EXPO_PUBLIC_GRAPHQL_URL`            | data/apollo         | public     | no             | GraphQL endpoint                                                                        |
| `WEBHOOK_SECRET`                     | backend/api-routes  | server     | no             | Shared secret for incoming webhooks under `src/server/webhooks`                         |
| `CLERK_WEBHOOK_SIGNING_SECRET`       | backend/api-routes  | server     | no             | Signing secret of the Clerk `user.deleted` webhook (`/api/webhooks/clerk`)              |
| `POSTHOG_PERSONAL_API_KEY`           | backend/api-routes  | server     | no             | Lets account deletion erase the user in PostHog                                         |
| `POSTHOG_PROJECT_ID`                 | backend/api-routes  | server     | no             | PostHog project id, same purpose                                                        |
| `POSTHOG_API_HOST`                   | backend/api-routes  | server     | no             | PostHog API host, same purpose                                                          |
| `AMPLITUDE_API_KEY`                  | backend/api-routes  | server     | no             | Lets account deletion erase the user in Amplitude                                       |
| `AMPLITUDE_SECRET_KEY`               | backend/api-routes  | server     | no             | Amplitude secret key, same purpose                                                      |
| `AMPLITUDE_REGION`                   | backend/api-routes  | server     | no             | Amplitude region, same purpose                                                          |
| `REVENUECAT_SECRET_KEY`              | backend/api-routes  | server     | no             | Lets account deletion erase the customer in RevenueCat                                  |

Each module page under [Features](https://readynative.app/docs/features) has the dashboard steps for its keys. The two
[example apps](https://readynative.app/docs/examples) carry their own `.env.example` with the subset they use.

## On EAS [#on-eas]

Your `.env` is gitignored, so EAS never uploads it: a cloud build, `eas update` and an EAS
Hosting deploy all run without it. A key that works locally but is missing in a TestFlight build
almost always was never set on EAS.

Set each key in the EAS environment it's used in (`development`, `preview`, `production`). A
build picks the environment from its profile: `build.<profile>.environment` in `eas.json` if you
add one, otherwise `production` for store builds (the shipped `production` profile),
`development` for dev-client builds (`development`) and `preview` for the rest:

```bash
bunx eas-cli env:set --environment production --name EXPO_PUBLIC_SUPABASE_URL --value https://xyz.supabase.co --visibility plaintext
bunx eas-cli env:set --environment production --name STRIPE_SECRET_KEY --value sk_live_xxx --visibility sensitive
bunx eas-cli env:list --environment production
```

`env:set` creates or updates a variable (the older `env:create` still works but is deprecated).
`--visibility` takes three values:

* **`plaintext`** - visible on expo.dev, in EAS CLI and in logs. Fine for `EXPO_PUBLIC_*` keys:
  they end up in the bundle anyway.
* **`sensitive`** - masked in build and workflow logs, still readable in EAS CLI and on the
  dashboard behind a toggle. Use it for server keys your API routes read (`STRIPE_*`,
  `BETTER_AUTH_*`, `CLERK_SECRET_KEY`, `WEBHOOK_SECRET`): **EAS Hosting can't deploy `secret`
  variables**, only `plaintext` and `sensitive` ones. Also use it for `SENTRY_AUTH_TOKEN` if you
  upload source maps after `eas update` from your machine.
* **`secret`** - never readable outside EAS servers, not even by EAS CLI. Right for keys only an
  EAS build job needs (`SENTRY_AUTH_TOKEN` for native builds, an `NPM_TOKEN`). A secret isn't
  available while EAS CLI resolves `app.config.ts` on your machine, can't be pulled, and isn't
  used by `eas update`.

`bunx eas-cli env:pull --environment development` writes that environment's variables to
`.env.local` (pass `--path` for another file); `secret` ones appear only as a commented-out
`*****` line. Expo loads `.env.local` on top of `.env`, so a pulled value wins over the one in
`.env`. `bun run doctor` reads only `.env`, though, so it still lists pulled keys as missing;
pull with `--path .env` (it asks before overwriting) if you want doctor to see them.

`eas update` needs `--environment` on SDK 55 and later - see
[Your first update](https://readynative.app/docs/your-first-update#3-publish-it). `APP_VARIANT` and
`EXPO_PUBLIC_APP_VARIANT` are already set per profile in `eas.json`, so don't create them.

Your tree ships no CI workflows. If you add your own (see
[Expo's GitHub Actions guide](https://docs.expo.dev/eas-update/github-actions/)), EAS needs an
`EXPO_TOKEN` secret (expo.dev → Account settings → Access tokens); set `EAS_PROJECT_ID` there
too if you'd rather not commit the id.


# Example apps (/docs/examples)



## The weather demo [#the-weather-demo]

Starter and Pro open on a small weather app, so the first `bun ios` shows what the modules do
together instead of an empty screen. It is demo content: `bun run setup` removes it and leaves
a plain welcome screen, unless you pass `--with-examples`.

```bash
bun install
bun ios        # or: bun run start, for Expo Go
```

| What you see                                                                                                   | What it is built on                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The forecast where you are, with a "Location is off" fallback                                                  | `@/lib/location` ([location](https://readynative.app/docs/features/location)) - `null`, never an exception, when permission is denied                                          |
| Hourly strip, 10-day list with range bars, detail tiles, pull to refresh                                       | `@/ui` primitives only, so it renders the same on every UI stack                                                                                        |
| A native tab bar (Liquid Glass on iOS 26), large-title Cities stack, header search, context menus on each city | `NativeTabs`, native stack headers, `Stack.SearchBar`, `Link.Menu` from Expo Router                                                                     |
| City search in the app language, °C / °F                                                                       | Open-Meteo (free, no key), the persisted store on `createPersistedStore`                                                                                |
| The last forecast on the first frame, and offline                                                              | `@/lib/cache` feeding `useForecast()`, which each [data module](https://readynative.app/docs/features/data) ships in its own idiom                                             |
| English, Spanish, Russian, Chinese, Portuguese and Arabic - Arabic mirrors the layout                          | the [i18n](https://readynative.app/docs/features/i18n) module and `Intl` for dates, hours and digits                                                                           |
| The temperature on your Home Screen, and live on the Lock Screen / Dynamic Island                              | `@/lib/widgets` ([widgets](https://readynative.app/docs/features/widgets)): `widgets.update()` and `widgets.activity.start()` - no-ops until you pick `--widgets expo-widgets` |
| Tap a day for its details in a native sheet                                                                    | `Sheet` from `@/ui` (`@expo/ui`'s SwiftUI / Material 3 sheet)                                                                                           |
| System toasts, presses that track your finger at 120 Hz                                                        | `toast.show()` (Burnt on iOS builds) and `Pressable` (Pressto) from `@/ui`                                                                              |
| "See all 10 days with Pro", more than 3 saved cities                                                           | `@/lib/payments`; with `--payments none` nothing is locked                                                                                              |
| Share, "Notify me" and analytics events                                                                        | `@/lib/share`, `@/lib/push`, `@/lib/analytics` - each a no-op when its module is `none`                                                                 |

Where it lives, if you want to copy a pattern before setup deletes it:

* Screens - `src/screens/home/home-screen.tsx`, `src/screens/weather/*`
* Routes - `src/app/(tabs)/index.tsx`, `src/app/(tabs)/cities/{_layout,index,[id]}.tsx`
* Open-Meteo client, WMO codes, `Intl` formatting - `src/lib/weather/*`
* Saved cities and units - `src/stores/weather.ts`
* The forecast hook per data module - `src/hooks/use-forecast.ts`

Right-to-left needs a dev build: Expo Go resets the layout direction when it opens a project,
so Arabic text shows but the layout stays left-to-right there. The widget needs a dev build too.

The weather data comes from [Open-Meteo](https://open-meteo.com) under CC BY 4.0; the demo
credits it under the forecast. Keep that line if you keep the API.

## Pro example apps [#pro-example-apps]

<Badge>
  Pro
</Badge>

These are the apps I use to prove the modules work together. Each one is a **standalone app**:
`examples/<name>/` has its own `package.json`, lockfile and `.env.example`, and it boots with no
`.env` at all. Every screen is usable, and anything that needs a key you haven't set says so
*on that screen*, before you act, naming the exact variable. Both use the native tab bar
(`NativeTabs`), native stack headers with large titles and inset-grouped settings. Nothing in
your app imports `examples/`, so delete it whenever you like.

| Example                     | What it shows                                                                   | Platforms                              | Tier |
| --------------------------- | ------------------------------------------------------------------------------- | -------------------------------------- | ---- |
| [Field Notes](#field-notes) | Local-first journal with Supabase sync, reminders, place + weather, a paid tier | iOS, Android                           | Pro  |
| [Snap Recipe](#snap-recipe) | On-device food recognition, recipe matching, two payment rails                  | iOS; Android without photo recognition | Pro  |

Both apps sell their own paid tier (a RevenueCat entitlement called `pro`). That's the
example's paid tier, a feature of the demo app - not the ReadyNative Pro tier you bought.

## Field Notes [#field-notes]

A private journal in `examples/notes`: one note per moment - a title, a few lines, optionally a
photo and where you were. "Where I am" stamps the note with a place name (`expo-location`
reverse geocoding) and the weather right now (Open-Meteo), both keyless. Notes are written to
the device first and sync to Supabase once you sign in; a daily local notification nudges you
to write; the example's paid tier unlocks unlimited notes and export. It's the `saas` preset
plus `expo-image-picker`, `expo-location` and `@react-native-community/datetimepicker`.

```bash
cd examples/notes
bun install
bun ios
bun run test
```

`bun ios` (or `bun android`) compiles a dev build with `expo run:*`, which RevenueCat needs;
afterwards `bun run start:dev` serves it. `bun start` is `expo start --go` and runs everything
else in Expo Go. The camera only appears on a physical device.

### Where each pattern lives [#where-each-pattern-lives]

* Local-first store (zustand `persist` on `zustandStorage`) - `src/stores/entries.ts`
* Sync algebra: last-writer-wins, tombstones, cursor, with tests - `src/features/entries/merge.ts`
* Supabase push/pull on sign-in, foreground and after edits - `src/lib/sync.ts`,
  `supabase/entries.sql`
* Paid-tier gate that switches itself off while RevenueCat is unconfigured - `src/lib/pro.ts`
  (`isProGateActive`)
* Keyless place + weather stamp - `src/lib/weather.ts`, `src/features/entries/weather.ts`
* Daily local reminder that deep-links to `/entry/new` - `src/lib/reminders.ts`
* Large-title list with header search and swipe-to-delete -
  `src/screens/entries/entries-screen.tsx`, `entry-row.tsx`
* Modal editor with Cancel/Add in the navigation bar -
  `src/screens/entries/entry-editor-screen.tsx`
* Stacks nested in native tabs - `src/app/(tabs)/**`
* Inset-grouped settings with a native switch and time picker -
  `src/screens/settings/settings-screen.tsx`
* One shared "needs keys" state naming the env vars - `src/components/not-configured.tsx`
* Auth screens and a paywall that explain a missing key - `src/screens/auth/*`,
  `src/screens/paywall/paywall-screen.tsx`
* Deep link `fieldnotes://entry/<id>` - `src/app/(tabs)/(notes)/entry/[id].tsx`
* Empty-env boot test, keyless screen tests (list, settings, the "needs keys" state), Maestro
  flows - `src/__tests__/boot.test.tsx`, `src/screens/__tests__/*`, `.maestro/flows/*.yaml`

### Keys [#keys]

`examples/notes/README.md` has the full table. The short version: the Supabase URL and anon
key unlock accounts and cloud sync (run `supabase/entries.sql` first for the table and RLS);
the two RevenueCat keys turn the paid-tier gate *on* (without them nothing is capped, and
Settings and the paywall say so); `EXPO_PUBLIC_POSTHOG_KEY`, `EXPO_PUBLIC_SENTRY_DSN` and
`EXPO_PUBLIC_API_URL` are optional no-ops when empty. The daily reminder is a *local*
notification, so it works in Expo Go with no EAS project; remote push needs a linked EAS
project and a physical device.

Not included: photos stay on the device (no Supabase Storage upload), there is no "choose a new
password" screen, conflicts resolve silently in favour of the newer edit, and the weather stamp
is sampled when you tap "Where I am" - editing an old note re-stamps it with the weather now.

## Snap Recipe [#snap-recipe]

Photograph your fridge in `examples/snap-recipe`. MobileCLIP recognises the food **on the
phone** - no server, no key, the photo never leaves the device - and a bundled recipe book
suggests what to cook, marking which ingredients you already have. Save favourites, share a
recipe as text. Three scans are free; the example's paid tier makes them unlimited and sells
through **two rails**: native in-app purchase (App Store / Google Play via RevenueCat) and
Stripe Checkout. It's the `default` preset plus Clerk, API routes, Stripe, RevenueCat, Sentry
and PostHog.

```bash
cd examples/snap-recipe
bun install
bun run gen:clip
bun ios
bun run test
```

`bun start` is `expo start --go`: everything but photo recognition and RevenueCat purchases
runs in Expo Go. `bun ios` builds the dev build those two need; `bun run start:dev` serves it.

`bun run gen:clip` downloads MobileCLIP-S0 (about 110 MB, cached) and writes the class
embeddings for the recipe catalog; the weights aren't in git. It needs macOS (Core ML runs the
text encoder) and `python3`. Run it once per machine, and again after changing the ingredient
list in `src/features/recipes/catalog.ts`.

### Android and other platforms [#android-and-other-platforms]

Photo recognition is an iOS-only local module, so it runs on an iPhone or the iOS Simulator
from a dev build. On Android, the web and in Expo Go the scan screen says "Photo recognition
runs on iPhone" in place. The rest works there: **Try a sample fridge** opens a bundled photo
with three pre-baked recipes (`src/features/recipes/sample.ts`), so results, detail,
favourites and share run anywhere with zero keys. Sample scans are marked "Sample" and never
count against the free quota. `bun android` compiles the Android dev build, which the Google
Play rail needs.

Without the generated model, an iOS build falls back to Apple's built-in Vision classifier
(device only, a fixed vocabulary). For EAS builds, run `bun run gen:clip` in an
`eas-build-post-install` script, or the cloud build ships the fallback.

### Where each pattern lives [#where-each-pattern-lives-1]

* Local Expo module in Swift running MobileCLIP zero-shot over the photo and a grid of crops -
  `modules/food-vision`
* Label → ingredient → recipe matching, with tests - `src/features/recipes/catalog.ts`
* On-device downscale with `expo-image-manipulator` behind a react-query mutation -
  `src/lib/scan.ts`
* Two payment rails behind one payments contract, entitlements are the union -
  `src/lib/payments.ts`, `src/lib/store-purchases.ts`
* Stripe Checkout routes (checkout, entitlements, return, webhook) - `src/app/api/stripe/*`,
  `src/server/stripe.ts`
* Paid-tier gating on `payments.useEntitlements()` - `src/lib/quota.ts`
* One native stack per tab with a shared `recipe/[id]` route - `src/app/(tabs)/**`,
  `src/components/app-stack.tsx`
* Scans, favourites and the free counter persisted with zustand - `src/stores/scans.ts`
* Empty-env boot test, RevenueCat and Stripe tests with the SDKs mocked -
  `src/__tests__/boot.test.tsx`, `src/lib/__tests__/*`,
  `src/server/__tests__/stripe-routes.test.ts`
* Maestro: fresh install, no keys → sample fridge → results - `.maestro/flows/scan-empty.yaml`

### Paywall and keys [#paywall-and-keys]

Hitting the scan limit opens RevenueCat's **native paywall** as a modal (Apple's purchase sheet
on buy); `/paywall` lists the store plans with "Compare all plans", and Stripe as "Or pay by
card" only where App Review allows it (US storefront on iOS). Settings has "Manage" on the
paid-tier row and, in dev builds, Developer → **Preview paywall**.
[Add web checkout next to the App Store](https://readynative.app/docs/add-web-checkout) walks through the same setup
for your own app.

`examples/snap-recipe/README.md` lists every key and what happens without it. Server-only keys
(`STRIPE_SECRET_KEY`, `STRIPE_PRICE_ID`) have no `EXPO_PUBLIC_` prefix and must never gain one;
on EAS Hosting set them with `--visibility sensitive` - `secret` variables can't be deployed to
EAS Hosting (see [Environment variables](https://readynative.app/docs/environment-variables)).
The RevenueCat keys are public SDK keys. `examples/snap-recipe/docs/RECOGNITION-MODELS.md`
compares the models you can swap in (MobileCLIP, YOLO26, RF-DETR, Create ML, barcode and text
reading, cloud vision) with their licences.

<Callout type="warn" title="Before you ship anything based on Snap Recipe">
  * **MobileCLIP licence:** the Hugging Face weights point at a permissive Apple licence, but
    Apple's repo moved MobileCLIP to a **research-only** licence in August 2025. Treat the model
    as research-only until you've settled it: read `modules/food-vision/MODEL-LICENSE.md`, and
    swap in a permissively licensed model for a commercial release.
  * **The store rail is in-app purchase, not Apple Pay.** Apple's sheet charges the Apple ID's
    payment method. Apple Pay proper is only for physical goods and services.
  * **App Review 3.1.1:** digital subscriptions in an iOS app must be offered through in-app
    purchase. A Stripe link-out is allowed on the US storefront; elsewhere it can get the build
    rejected.
  * **Disclosure:** show price, period, auto-renewal and how to cancel next to the buy button,
    and link Terms and Privacy (`urls` in `readynative.config.ts`).
  * **Plain-http API on a device:** iOS only allows `http://` to LAN IPs, `localhost`, `*.local`
    and dot-less hosts. A tunnel or deployed API must be `https://`.
  * **The free-scan counter lives on the device.** Count scans per user server-side if the free
    tier must hold.
</Callout>


# Expo Go or a dev build (/docs/expo-go-vs-dev-build)



Hey - by the end of this page you'll know whether your stack runs in Expo Go, and if it doesn't,
you'll have a dev build on your simulator or phone that `bun run start:dev` connects to.

**Expo Go** is the app from the App Store and Play Store. It carries a fixed set of native
modules, so it opens your project in seconds with no build - as long as your stack needs nothing
more. A **dev build** is your own app with Expo's developer tools inside: every native module you
picked, your icon and bundle id, and the same fast refresh from your dev server. You build it
once and rebuild only when native code changes.

## Before you start [#before-you-start]

* **Tier:** any. On the Free tier every module runs in Expo Go.
* **Time:** none if you stay in Expo Go. A local dev build takes 10-20 minutes the first time; an
  EAS one about 20-40 minutes in the queue.
* **Accounts:** none locally. For EAS, a free [Expo account](https://expo.dev/signup), plus the
  paid Apple Developer Program to install an iOS build on a real iPhone.
* **Previous tutorial:** [Quickstart](https://readynative.app/docs/ship-in-5-minutes).

## 1. Check what your stack needs [#1-check-what-your-stack-needs]

Six options have native code Expo Go doesn't carry:

| Option                    | Why it needs a dev build                            |
| ------------------------- | --------------------------------------------------- |
| `storage=mmkv`            | MMKV is a native key-value store                    |
| `ui=unistyles`            | Unistyles is a C++ style engine on Nitro Modules    |
| `payments=revenuecat`     | StoreKit and Play Billing                           |
| `payments=adapty`         | StoreKit and Play Billing                           |
| `push=expo-notifications` | Remote push - Expo Go can't receive it since SDK 53 |
| `widgets=expo-widgets`    | The widget is an iOS app extension                  |

Two more run in Expo Go with less: `crash=sentry` reports JS errors there but needs a dev build
for native crashes, and `analytics=amplitude` fills in the full device context only in a dev
build. Local notifications work in Expo Go. Right-to-left layout (Arabic) also needs a dev build:
Expo Go resets the layout direction whenever it opens a project.

`setup` already made the call - look at the `start` script in `package.json`:

* `expo start --go` - every module you picked runs in Expo Go. `bun run start` opens it there.
* `expo start --dev-client` - at least one needs a dev build. `bun run start` targets your dev
  build, and Expo Go won't load the project.

On Starter and Pro, `bun run doctor` checks the Xcode and Android SDK toolchains only when one of
your modules needs them. The Free tier has no `doctor`; before a local build, check by hand that
`xcode-select -p` prints a path inside `Xcode.app` (iOS) and that `ANDROID_HOME` points at your
Android SDK (Android).

**You should see:** `--go` or `--dev-client` in the `start` script. On `--go`, you're done -
come back when you add a native module.

## 2. Build it locally [#2-build-it-locally]

With Xcode (iOS) or Android Studio (Android) installed, one command generates the native
project, compiles it and installs it on the simulator or emulator:

<Cmd>
  bun run ios
</Cmd>

<Cmd>
  bun run android
</Cmd>

These are `expo run:ios` and `expo run:android`. The first run compiles every native module
from source, so it takes a while; later runs reuse the build cache. For a plugged-in phone, add
`--device`:

<Cmd>
  bunx expo run:ios --device
</Cmd>

The `ios/` and `android/` folders this creates are generated - never edit them. Native
settings live in `app.config.ts`, `readynative.config.ts` and config plugins, and a rebuild
regenerates the folders.

**You should see:** "YourApp (Dev)" installed next to any other variant, opening the Expo
development launcher and then your app.

## 3. Or build it on EAS [#3-or-build-it-on-eas]

No Mac, or you'd rather not install Xcode? EAS builds it in the cloud with the `development`
profile from `eas.json` (`developmentClient: true`, internal distribution). Link the project
first - [Ship to TestFlight](https://readynative.app/docs/ship-to-testflight#2-link-the-eas-project) has the commands -
then:

```bash
bunx eas-cli build --profile development --platform android
```

The Android build is an `.apk` that installs on any phone or emulator from the link EAS prints.

iOS needs one more step. Internal builds install only on registered devices, so register your
iPhone first - the command shows a QR code to open on the phone, which installs a profile that
tells EAS the device's id:

```bash
bunx eas-cli device:create
bunx eas-cli build --profile development --platform ios
```

A device registered after a build needs a new build. To build for the iOS Simulator instead,
add a profile that extends `development`:

```json title="eas.json"
"development-simulator": {
  "extends": "development",
  "ios": { "simulator": true }
}
```

and build it with `--profile development-simulator`.

**You should see:** a QR code and install link when the build finishes. On iOS, enable
**Developer Mode** (Settings → Privacy & Security) the first time you open it.

## 4. Start the dev server for it [#4-start-the-dev-server-for-it]

<Cmd>
  bun run start:dev
</Cmd>

That's `expo start --dev-client`: the QR code opens your dev build, not Expo Go. On a
`--dev-client` stack, `bun run start` does the same.

**You should see:** your dev build connect and load the app; saving a file refreshes it as in
Expo Go.

## When to rebuild [#when-to-rebuild]

Rebuild the dev build when something native changes: a module or library with native code, a
config plugin, the name, bundle id, scheme, icon or splash. JavaScript changes never need a
rebuild - they come from the dev server. When the app on the device and your tree disagree, the
dev build usually tells you with a "native module not found" error.

## If it doesn't work [#if-it-doesnt-work]

* **"Project is incompatible with this version of Expo Go" or a missing native module** - your
  stack needs a dev build. See
  [A native module is missing in Expo Go](https://readynative.app/docs/troubleshooting#a-native-module-is-missing-in-expo-go).
* **`bun run ios` fails before compiling** - `xcode-select -p` must point at Xcode (Starter and
  Pro: the "Xcode (dev build)" row of `bun run doctor` checks it), or `ANDROID_HOME` at your
  Android SDK for Android.
* **The iOS EAS build won't install** - the device wasn't registered when the build ran.
  `bunx eas-cli device:create`, then build again.
* **The dev build opens but can't reach the dev server** - phone and computer must be on the same
  network, or start with `bunx expo start --dev-client --tunnel`.
* **The build fails on credentials** - see
  [EAS build or credentials fail](https://readynative.app/docs/troubleshooting#eas-build-or-credentials-fail).

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Next [#next]

You can run every module you picked. Next, make the app yours:
[Make it yours](https://readynative.app/docs/make-it-yours).


# FAQ (/docs/faq)



## Expo Go or a dev build? [#expo-go-or-a-dev-build]

Every module runs in [Expo Go](https://expo.dev/go) except the five that ship native code:
`storage=mmkv`, `ui=unistyles`, `payments=revenuecat`, `payments=adapty` and remote push with
`push=expo-notifications`. `bun run setup` prints the verdict for your selection
(`Expo Go: yes` / `NO - a dev build is required`), and each module page shows an Expo Go badge.
[Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build) explains why and walks you through making
one.

## Can I change a module after `setup`? [#can-i-change-a-module-after-setup]

Only if `modules/` still exists. `setup` deletes it unless you passed `--keep-modules`; with the
folder present, this re-resolves the plan, copies the new module, removes the old one's files and
regenerates providers and env:

<Cmd>
  bun run setup --payments stripe --backend api-routes --yes --keep-modules
</Cmd>

A finalized tree can't switch: `setup` is a stub once `modules/` is gone, and copying the folder
back from upstream doesn't restore the module system. Clone a fresh copy of your tier repo, run
`setup` there with the new selection, and port your own code (screens, stores,
`readynative.config.ts`) across. Removing a module by hand is possible - every module page has
a **Remove it** section listing its files, dependencies and env keys. Pulling fixes into a
finalized tree is covered in [Update from upstream](https://readynative.app/docs/update-from-upstream#finalized-tree).

## How do I add my own module? [#how-do-i-add-my-own-module]

This needs `modules/`, so it works in a tree set up with `--keep-modules`:

```bash
bun run gen module analytics mixpanel
```

creates `modules/analytics/mixpanel/{module.json,files/,docs.md}`. Then:

1. Fill `module.json`: `label`, `hint`, `expoGo`, `dependencies`, `files[]` (root-relative,
   mirrored under `files/`), `providers`, `env` (every key with a `docsUrl`, secrets as
   `server: true`), `requires` / `conflicts`, `postSetup`. The schema is zod in
   `scripts/lib/schema.ts`; every field except `id` / `category` / `label` has a default.
2. For a service category, implement the shim contract from `src/lib/shims/<category>.ts`
   under `files/src/lib/<category>.ts` with the same export names, so core code keeps
   importing `@/lib/<category>`.
3. Add the option to `CATALOG` in `scripts/lib/catalog.ts` (first entry = default).
4. Write `docs.md` (what it adds, keys, dashboards, a "Manual E2E checklist").
5. Apply it and check it: `bun run setup --analytics mixpanel --yes --keep-modules`, then
   `bun run typecheck`, `bun run lint` and `bunx expo export -p ios -p android`.

The full contract is in the [module spec](https://readynative.app/docs/module-spec).

## Why is there no `className` on the kit's primitives? [#why-is-there-no-classname-on-the-kits-primitives]

Because three of the five UI stacks have no Tailwind. The primitives' props are token-typed
(`p={4}`, `bg="card"`, `radius="lg"`), and `style` is the single escape hatch, so the same
screens compile on `nativewind4`, `nativewind5`, `tamagui`, `unistyles` or `stylesheet`. Inside
a NativeWind kit you can use classes freely, and once `setup` has finalized your tree the kit in
`src/components/ui` is plain code you own - add `className` if you want it. See
[Styling](https://readynative.app/docs/styling).

## Does it run on the web? [#does-it-run-on-the-web]

`app.config.ts` sets `web.output: "static"` (`"server"` with `backend=api-routes`), and
`bun run web` starts `expo start --web`. Web is best-effort: the checks I run before each release
export iOS and Android only. NativeWind and Tamagui render fine on web; `unistyles` is
native-first (its web shell in `src/app/+html.tsx` is not a gate); RevenueCat and native push
have no web path. `expo export -p web` ships the `public/` folder (including `.well-known/` from
`gen:links`) as-is, which is enough to host universal-link files.

The Free tier ships without a `web` script and without `react-dom` and `react-native-web`, so it
doesn't run on the web out of the box. The `web` block in `app.config.ts` is still there; add
the two packages, then start the web target:

```bash
bunx expo install react-dom react-native-web
bunx expo start --web
```

## Why NativeWind 4 and not NativeWind 5 as the default? [#why-nativewind-4-and-not-nativewind-5-as-the-default]

NativeWind 5 is still a release candidate (`nativewind@5.0.0-rc.0` with
`react-native-css@3.1.0-rc.0`), so the default is the stable release: NativeWind 4.2 on
Tailwind 3 (`nativewind@4.2.7`), which the committed tree and every preset use and which gets
the most testing. The theme is generated as HSL triples into `tailwind.config.js`. Want
Tailwind 4 now? `bun run setup --ui nativewind5` - labelled "RC · Tailwind 4" in the picker -
gives you the same primitives on NativeWind 5, and adds the `lightningcss` override to
`package.json` that NativeWind 5 needs. When NativeWind 5 ships a stable release, it becomes
the default in an update.

## Tamagui and the React Compiler [#tamagui-and-the-react-compiler]

`experiments.reactCompiler` is on for every stack, including Tamagui 2 with the optimising
compiler: `tsc`, jest and `expo export` pass with both enabled. Only device runs can prove the
Reanimated press animations; if they misbehave, set
`"app": { "expo": { "experiments": { "reactCompiler": false } } }` in
`modules/ui/tamagui/module.json` (or your `.readynative.json` → `modules.app`) and rebuild. The
first Tamagui build prints a few benign `[tamagui] skipped loading … warning-001` lines and
writes a `.tamagui/` cache folder (gitignored).

## What does `bun run doctor` check? [#what-does-bun-run-doctor-check]

Your selection, the env keys your modules need, the placeholders in `readynative.config.ts`
(and that it loads under Node), your EAS login, the app icon, the native toolchains when a module
needs them, and the bun and Node versions. Store and release placeholders are listed under
"Before you ship" as warnings, so a fresh setup exits 0; `bun run doctor --store` turns them
into failures. Every row is explained in [Doctor](https://readynative.app/docs/doctor).

## Where do API keys go? [#where-do-api-keys-go]

In `.env` at the repo root (gitignored); `.env.example` is generated with every key your
selection needs and a `# docs:` link per key. `EXPO_PUBLIC_*` keys are bundled into the app, and
a missing one degrades its module ("Configure Supabase") instead of crashing. Keys without the
prefix (`STRIPE_SECRET_KEY`, `BETTER_AUTH_SECRET`, …) are server-only: they're never written to
`src/lib/env.ts`, so they can't leak into the bundle. For EAS builds, the same keys go in EAS
environment variables. [Environment variables](https://readynative.app/docs/environment-variables) has every key and
the visibility each kind needs on EAS.

## How long do updates last? [#how-long-do-updates-last]

For as long as ReadyNative is maintained - every paid license includes lifetime updates, and
your GitHub access stays. [License → Lifetime updates](https://readynative.app/docs/license#lifetime-updates) says what
"lifetime" means, and [Update from upstream](https://readynative.app/docs/update-from-upstream) shows how to pull a
release in.

## Can I get a refund? [#can-i-get-a-refund]

No refunds once you have access to the repo, except where the law requires otherwise; Polar,
the merchant of record, handles those. See [License → Refunds](https://readynative.app/docs/license#refunds).

## Why is `setup` one-way? [#why-is-setup-one-way]

So the shipped app is a plain Expo project: no runtime module registry, no unused adapters,
no dependencies for stacks you didn't pick. Keeping `modules/` around (`--keep-modules`) costs
nothing but disk space and keeps the door open for changes and upstream merges. [How setup
works](https://readynative.app/docs/how-setup-works) has what finalizing changes.

## How do I get help? [#how-do-i-get-help]

Through [the support form](https://readynative.app/support/) on the landing site - questions
before you buy, bugs, invoices, extra seats. That's the only channel: there's no support email,
so nothing gets lost in a mailbox. Paid but no repo? Open the customer-portal link in Polar's
receipt email and connect your GitHub account
([Get access](https://readynative.app/docs/after-you-buy#2-connect-github-in-the-polar-portal) has the steps). Still
stuck? Pick "Paid, no repo access" on
[the support form](https://readynative.app/support/?topic=access) and leave the email you paid
with.


# Amplitude (/docs/features/analytics/amplitude)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/analytics/amplitude - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="analytics" option="amplitude" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This sends product analytics to Amplitude: `src/lib/analytics.ts` initialises `@amplitude/analytics-react-native` 1.x on the first analytics consent (only when the key is set) and implements `analytics.track/identify/screen`, with a pass-through `AnalyticsProvider` (order 40, since the SDK has no React provider). `screen` maps to `trackScreenView` (`[Amplitude] Screen Viewed`) and `identify` maps to `setUserId` plus an `Identify` call for user properties, where `null` unsets a property. If you set up with `--with-examples` there's an example at `/examples/analytics` with a list of the last events sent. `@/lib/analytics` keeps the same API whichever option you pick - pick Amplitude when your team already lives in its funnels and cohorts.

## Setup [#setup]

```bash
bun run setup --analytics amplitude
```

1. Open [app.amplitude.com](https://app.amplitude.com) → \[Settings] → \[Projects] → your project and copy the API key into `.env` as `EXPO_PUBLIC_AMPLITUDE_KEY`. It's publishable and safe in the client. Without it every call is a no-op and the example shows "Configure EXPO\_PUBLIC\_AMPLITUDE\_KEY".
2. If your data has to stay in the EU, add `serverZone: "EU"` to the `init` options in `src/lib/analytics.ts`.
3. Restart the dev server with `bun run start -- -c` so the key is picked up, then open \[Analytics] → \[User Look-Up] in Amplitude and watch for `[Amplitude] Session Start`.
4. Persistence - session and the event queue - goes through the storage adapter (`createAdapterStorage()` on `@/lib/storage`), so the SDK's default async-storage is never loaded; `disableCookies` is on and `migrateLegacyData` is off.
5. For the full device context (`Application Installed/Updated` events, `idfv`, app-set-id), make a dev build with `npx expo run:ios` or `npx expo run:android`. Expo Go still works - the SDK's native module is optional, and device and OS fields then come from the JS user agent.

<Callout type="info" title="Going to production?">
  Use a separate Amplitude project for production so your own test events don't skew the charts, and swap the key per build profile (`eas.json` `env`). The key is public, so there's nothing to keep secret - don't point release builds at your dev project.
</Callout>

6. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                         | Where to get it                                                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_AMPLITUDE_KEY` | [https://app.amplitude.com/analytics/settings/projects](https://app.amplitude.com/analytics/settings/projects) → your project → API key. Publishable. |

Dashboards: the events stream at [app.amplitude.com](https://app.amplitude.com) → Data → Events (or Analytics → User Look-Up for one user) · [project settings and API key](https://app.amplitude.com/analytics/settings/projects). Deps: `@amplitude/analytics-react-native ^1.8`, which pulls `@amplitude/analytics-core` (async-storage comes along as a transitive dep but is unused).

## Usage [#usage]

Track an event and identify the user:

```ts
import { analytics } from "@/lib/analytics";

analytics.track("checkout_started", { plan: "pro" });
analytics.identify(user.id, { email: user.email });
```

Reset on sign-out, which gives you a new device id and an anonymous user:

```ts
import { analytics } from "@/lib/analytics";

analytics.reset();
```

Screens are already tracked for you by the root layout, but you can send one by hand:

```ts
import { analytics } from "@/lib/analytics";

analytics.screen("/checkout");
```

## Consent [#consent]

`init` runs only on the first "yes" to analytics consent, with `optOut: false` and `trackingOptions: { ipAddress: false, adid: false, carrier: false }`; before that nothing is initialised or sent. Withdrawing consent calls `setOptOut(true)`, consent again `setOptOut(false)`. With `consent/consent` that means nothing runs in the EU/EEA, UK, CH, CA, BR until the sheet is answered, it runs elsewhere, and the Settings → Privacy toggle flips it live. `isAnalyticsConfigured` only means the key is set; `isAnalyticsActive()` tells you whether the SDK is running. `analytics.reset()` sets the user id to `undefined` and issues a new device id, leaving `optOut` alone - the root layout's `useSignOutCleanup` calls it through `wipeLocalData()` on every sign-out, and on account deletion.

Privacy declarations: UserID and CoarseLocation are declared `linked: true` - `identify` links them to the user, and Amplitude derives a coarse location server-side.

## Feature flags [#feature-flags]

`analytics.isFeatureEnabled` / `getFeatureFlag` / `useFeatureFlag` exist for parity with PostHog but always return `undefined` here: Amplitude Analytics has no flags, Amplitude Experiment is a separate SDK (`@amplitude/experiment-react-native-client`). Gate on `=== true` so code stays correct across providers.

## Tracking (ATT) [#tracking-att]

The module installs `expo-tracking-transparency` with a purpose string in `app.config.ts` (`NSUserTrackingUsageDescription`) and ships `src/lib/tracking.ts` - the same `tracking.getStatus() / requestPermission()` + `useTrackingStatus()` surface as the core shim. First-party product analytics is **not** tracking, so `features.tracking` defaults to `false` in `readynative.config.ts`: nothing ever prompts and you answer "No" to tracking in App Store Connect. Flip it to `true` when you link data across companies (ads attribution, IDFA): `AnalyticsProvider` then asks once the app is in the foreground (iOS answers `denied` silently if asked from the background) and `analytics.identify` waits for `granted`. To pitch the value first, remove that call from the provider and call `tracking.requestPermission()` behind your own explainer screen. `app.config.ts` adds the `expo-tracking-transparency` plugin only when `features.tracking` is `true`. With it `false` the plugin is dropped, `com.google.android.gms.permission.AD_ID` goes into `android.blockedPermissions`, and the privacy manifest gets `NSPrivacyTracking: false`; the `NSUserTrackingUsageDescription` string stays, because the library is still linked and App Store Connect flags a linked ATT framework without one (ITMS-90683). `doctor --store` reports the flag/library state either way.

## Gotchas [#gotchas]

* Storage `reset()` is a no-op, because the adapter can't enumerate keys. Only Amplitude's disabled legacy migration calls it.
* `bun run setup --analytics none` removes everything; with `--with-examples`, `/examples/analytics` then shows "Module not installed".
* Expo Go works, but without the optional native module there are no `Application Installed/Updated` events and no `idfv` or app-set-id. Make a dev build for the full context.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Put a real `EXPO_PUBLIC_AMPLITUDE_KEY` in `.env`, run `bun run start -- -c`, and open the app on a device (Expo Go is fine).
2. Amplitude → Analytics → User Look-Up → search by device, or wait for `[Amplitude] Session Start`: a user appears within about a minute.
3. Examples → "Analytics event" → tap **Track event** → `example_pressed` with `source=examples/analytics` shows in that user's event stream. The SDK flushes every second or 30 events.
4. Tap **Identify user**: the user gets `user_id=demo-user` and the user property `plan=free`.
5. Navigate between tabs and watch one `[Amplitude] Screen Viewed` arrive per pathname.
6. Remove the key and restart: the example shows "Configure EXPO\_PUBLIC\_AMPLITUDE\_KEY" and the app still boots.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --analytics none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/analytics.tsx`, `src/lib/__tests__/analytics-amplitude.test.ts`, `src/lib/__tests__/tracking.test.ts`, `src/screens/examples/analytics-example-screen.tsx`.
2. **Replace, don't delete** `src/lib/analytics.ts`, `src/lib/tracking.ts`: core code imports them, so swap in the no-op version from `modules/analytics/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @amplitude/analytics-react-native expo-tracking-transparency`.
4. **Drop the config plugin** `expo-tracking-transparency` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<AnalyticsProvider>` and its import from `src/providers.tsx`.
6. **Remove the env keys** `EXPO_PUBLIC_AMPLITUDE_KEY` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_AMPLITUDE_KEY` from `src/lib/env.ts`.
7. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
8. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/analytics/amplitude/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --analytics amplitude
</Cmd>

Module id: `analytics/amplitude`.

### Dependencies [#dependencies]

| Package                             | Version   | Kind                        |
| ----------------------------------- | --------- | --------------------------- |
| `@amplitude/analytics-react-native` | `^1.8.0`  | dependency                  |
| `expo-tracking-transparency`        | `~57.0.2` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-tracking-transparency` (with options)

### Environment keys [#environment-keys]

| Key                         | Required | Server-only | Example                            | Docs                                                               |
| --------------------------- | -------- | ----------- | ---------------------------------- | ------------------------------------------------------------------ |
| `EXPO_PUBLIC_AMPLITUDE_KEY` | yes      | no          | `0123456789abcdef0123456789abcdef` | [dashboard](https://app.amplitude.com/analytics/settings/projects) |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects &#x2A;App interactions (events, screens)*, &#x2A;Device or other ids (device id)*, &#x2A;User IDs (when you call analytics.identify)*, &#x2A;Approximate location (derived from the request IP)*; shared with Amplitude (processor). Source of truth: [vendor disclosure](https://amplitude.com/privacy).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type                 | Linked to user | Tracking | Purposes  |
| -------------------- | -------------- | -------- | --------- |
| `ProductInteraction` | yes            | no       | Analytics |
| `DeviceID`           | yes            | no       | Analytics |
| `UserID`             | yes            | no       | Analytics |
| `CoarseLocation`     | yes            | no       | Analytics |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider            | From              |
| ----- | ------------------- | ----------------- |
| 40    | `AnalyticsProvider` | `@/lib/analytics` |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_AMPLITUDE_KEY`

### After setup [#after-setup]

1. Amplitude: create a project at [https://app.amplitude.com](https://app.amplitude.com) (Settings > Projects), copy its API key into EXPO\_PUBLIC\_AMPLITUDE\_KEY.
2. Amplitude: open Data > Events (or User Look-Up), call `analytics.track("hello")` from any screen (or open /examples/analytics with `--with-examples`) and watch it arrive.
3. Amplitude: install/update lifecycle events and idfv/app-set-id need the SDK's native module - make a dev build (`npx expo run:ios`); Expo Go tracks everything else.
4. App Tracking Transparency: expo-tracking-transparency is installed, but app.config.ts only adds its plugin, the NSUserTrackingUsageDescription purpose string and NSPrivacyTracking: true when `features.tracking` is true in readynative.config.ts - set it only if you link data across companies (ads attribution, IDFA); the prompt then runs once the app is active and `analytics.identify` waits for it. With it off (the default) Android's AD\_ID permission is blocked and you answer 'No' to tracking in App Store Connect.

### Files [#files]

<details>
  <summary>
    6 files copied to the project root
  </summary>

  * `src/app/examples/analytics.tsx`
  * `src/lib/__tests__/analytics-amplitude.test.ts`
  * `src/lib/__tests__/tracking.test.ts`
  * `src/lib/analytics.ts`
  * `src/lib/tracking.ts`
  * `src/screens/examples/analytics-example-screen.tsx`
</details>


# Analytics (/docs/features/analytics)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/analytics/README.md - do not edit. */}

<Badge>
  Pro
</Badge>

Hey - here's how analytics work in ReadyNative.

This category owns product events: the three calls you make from screens, and the automatic screen event the root layout sends on every route change.

`@/lib/analytics` always exists, whichever option you pick: `analytics.track()`, `analytics.identify()` and `analytics.screen()` read the same in every one of them, and `analytics/none` is a no-op. Calls you write against the shim keep working when you switch options, and nothing crashes when the key is missing - every option degrades to a no-op.

Pick **PostHog** if you want events and feature flags from one service with a generous free tier, and the option to self-host later; it's the default here. Pick **Amplitude** if your team already lives in its funnels and cohorts, or you have an existing project to send to.

This category is part of ReadyNative Pro.

## Options [#options]

One option per category - `--analytics <option>` picks it:

<Cmd>
  bun run setup --analytics posthog
</Cmd>

| Option                     | Label             | Expo Go | Hint                                                                                         |
| -------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
| [`posthog`](./posthog)     | PostHog (default) | yes     | product analytics + feature flags (analytics.isFeatureEnabled / useFeatureFlag) · Expo Go OK |
| [`amplitude`](./amplitude) | Amplitude         | yes     | product analytics · Expo Go OK (JS SDK, storage adapter)                                     |
| [`none`](./none)           | No analytics      | yes     | analytics.track/identify/screen are no-ops, feature flags read undefined                     |


# No analytics (/docs/features/analytics/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/analytics/none - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="analytics" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-op analytics option: no SDK, no network calls, no third-party account. It owns `src/lib/analytics.ts` as a re-export of the core shim, so `@/lib/analytics` keeps the same API whichever option you pick - `analytics.track`, `analytics.identify` and `analytics.screen` all do nothing. Pick this while you're still building, or when you'd rather not collect anything at all.

## Setup [#setup]

```bash
bun run setup --analytics none
```

There's nothing to configure and no keys to paste. The root layout still calls `analytics.screen(pathname)` on every route change; it goes nowhere.

When you want the numbers, switch with `bun run setup --analytics posthog` or `--analytics amplitude`.

## Usage [#usage]

The calls exist and are safe to write today, so screens don't need rewriting when you switch:

```ts
import { analytics } from "@/lib/analytics";

analytics.track("checkout_started", { plan: "pro" }); // no-op
analytics.identify(user.id, { email: user.email }); // no-op
analytics.isFeatureEnabled("new-paywall"); // undefined - gate on `=== true`
```

## Gotchas [#gotchas]

* Events sent while this option is selected are gone - nothing is buffered and replayed when you switch.
* Nothing here needs a dev build; Expo Go is fine.

## Reference [#reference]

Everything below is generated from `modules/analytics/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --analytics none
</Cmd>

Module id: `analytics/none`.

### Files [#files]

<details>
  <summary>
    2 files copied to the project root
  </summary>

  * `src/lib/analytics.ts`
  * `src/lib/tracking.ts`
</details>


# PostHog (/docs/features/analytics/posthog)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/analytics/posthog - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="analytics" option="posthog" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This sends product analytics to PostHog: `src/lib/analytics.ts` builds a `posthog-react-native` 4.x client once analytics consent is given and implements `analytics.track/identify/screen`, with an `AnalyticsProvider` (order 40) that follows consent and asks for ATT when enabled. `PostHogProvider` is not mounted - it needs a client at mount, and swapping one in after consent would remount the app - so `usePostHog()` and posthog-react-native's own hooks don't work; use `analytics.*`, `useFeatureFlag`, or `getPostHog()` / `usePostHogClient()` for the raw client (both `undefined` until consent). The root layout already calls `analytics.screen(pathname)` on every route change, so screen autocapture is off and touch autocapture is off too. If you set up with `--with-examples` there's an example at `/examples/analytics` with a list of the last events sent. `@/lib/analytics` keeps the same API whichever option you pick - pick PostHog when you want events, feature flags and a generous free tier from one service you can also self-host.

## Setup [#setup]

```bash
bun run setup --analytics posthog
```

1. Create a project at [app.posthog.com](https://app.posthog.com), then open \[Settings] → \[Project] and copy the Project API key (`phc_…`) into `.env` as `EXPO_PUBLIC_POSTHOG_KEY`. It's publishable and safe in the client. Without it every call is a no-op and the example shows "Configure EXPO\_PUBLIC\_POSTHOG\_KEY".
2. If your project lives in the EU, set `EXPO_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com` in `.env`. It's optional and defaults to `https://us.i.posthog.com`.
3. Restart the dev server with `bun run start -- -c` so the new env vars are picked up, then open \[Activity] → \[Live events] in PostHog and watch for `Application Opened` and `$screen`.
4. Persistence goes through the storage adapter (`customStorage: storage` from `@/lib/storage`), not `expo-file-system`, so it follows your storage module. `expo-application`, `expo-device` and `expo-localization` are installed to fill in `$app_version`, `$device_name` and `$locale`.

<Callout type="info" title="Going to production?">
  Use a separate PostHog project for production so your own test events don't skew the funnels, and swap the key per build profile (`eas.json` `env`). The key is public, so there's nothing to keep secret - don't point release builds at your dev project.
</Callout>

5. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                        | Where to get it                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `EXPO_PUBLIC_POSTHOG_KEY`  | [https://app.posthog.com/settings/project](https://app.posthog.com/settings/project) → Project API key (`phc_…`). Publishable. |
| `EXPO_PUBLIC_POSTHOG_HOST` | optional; `https://us.i.posthog.com` (default) or `https://eu.i.posthog.com` for EU projects                                   |

Dashboards: [Live events](https://app.posthog.com/activity/explore) · [People](https://app.posthog.com/persons) · [Project settings](https://app.posthog.com/settings/project). Deps: `posthog-react-native ^4.71`, `expo-application`, `expo-device`, `expo-localization`. Expo Go works, since it's all JS.

## Usage [#usage]

Track an event and identify the user:

```ts
import { analytics } from "@/lib/analytics";

analytics.track("checkout_started", { plan: "pro" });
analytics.identify(user.id, { email: user.email });
```

Reset on sign-out, so the next person isn't the same person:

```ts
import { analytics } from "@/lib/analytics";

analytics.reset();
```

Feature flags are on the contract, so feature code stays provider-agnostic:

```tsx
import { analytics, useFeatureFlag } from "@/lib/analytics";

// Reactive: `undefined` until flags load, then the boolean or variant key.
const paywall = useFeatureFlag("new-paywall");
if (paywall === true) return <NewPaywall />;

// One-shot, outside React:
if (analytics.isFeatureEnabled("new-paywall")) analytics.track("paywall_variant", { v: "new" });
const copy = analytics.getFeatureFlag("cta-copy"); // "variant-b" | true | false | undefined
```

Flags load after boot and after every `identify`; `useFeatureFlag` re-renders on each load. Payloads and forced reloads use the raw client: `getPostHog()?.getFeatureFlagPayload("flag")`, `getPostHog()?.reloadFeatureFlagsAsync()`. With `--analytics none` or `amplitude` every flag reads `undefined`, so gate on `=== true`.

## Consent [#consent]

No PostHog client exists until `consent.get().analytics` is true. The consent store is loaded when `@/lib/consent` is imported and the module follows it from import time on, so no event, `/flags` or remote-config request leaves the device before consent. On "yes" the client is created with `defaultOptIn: false` and `optIn()` is called explicitly; withdrawing calls `optOut()` and detaches the client (every call is then a no-op); consent again re-attaches the same client - a second one is never constructed. With `consent/consent` that means: nothing runs in the EU/EEA, UK, CH, CA, BR until the sheet is answered, it runs elsewhere, and the Settings → Privacy toggle flips it live. With `consent/none` it reads `true`. `isAnalyticsConfigured` only means the key is set.

`analytics.reset()` with a live client calls `reset([InstalledAppBuild, InstalledAppVersion])`, so both the anonymous id and the device id are regenerated, then re-applies consent (`optIn` / `optOut`) because PostHog's reset clears its persisted opt-out. With no live client it deletes the stored identity (storage key `.posthog-rn.json`), and a detached client is reset when consent comes back. The root layout's `useSignOutCleanup` calls `wipeLocalData()` - which calls `analytics.reset()` - on every sign-out, not only the Settings button, and on account deletion.

Privacy declarations: ProductInteraction, DeviceID, UserID and CoarseLocation, all `linked: true` - `identify` links them to the user and PostHog's GeoIP gives a coarse location.

## Tracking (ATT) [#tracking-att]

The module installs `expo-tracking-transparency` with a purpose string in `app.config.ts` (`NSUserTrackingUsageDescription`) and ships `src/lib/tracking.ts` - the same `tracking.getStatus() / requestPermission()` + `useTrackingStatus()` surface as the core shim. First-party product analytics is **not** tracking, so `features.tracking` defaults to `false` in `readynative.config.ts`: nothing ever prompts and you answer "No" to tracking in App Store Connect. Flip it to `true` when you link data across companies (ads attribution, IDFA): `AnalyticsProvider` then asks once the app is in the foreground (iOS answers `denied` silently if asked from the background) and `analytics.identify` waits for `granted`. To pitch the value first, remove that call from the provider and call `tracking.requestPermission()` behind your own explainer screen. `app.config.ts` adds the `expo-tracking-transparency` plugin only when `features.tracking` is `true`. With it `false` the plugin is dropped, `com.google.android.gms.permission.AD_ID` goes into `android.blockedPermissions`, and the privacy manifest gets `NSPrivacyTracking: false`; the `NSUserTrackingUsageDescription` string stays, because the library is still linked and App Store Connect flags a linked ATT framework without one (ITMS-90683). `doctor --store` reports the flag/library state either way.

## Gotchas [#gotchas]

* Session replay and surveys aren't enabled - they need extra native packages and a dev build.
* `bun run setup --analytics none` removes everything; with `--with-examples`, `/examples/analytics` then shows "Module not installed".

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Put a real `EXPO_PUBLIC_POSTHOG_KEY` in `.env`, run `bun run start -- -c`, and open the app on a device (Expo Go is fine).
2. Open PostHog → Activity → Live events and wait for `Application Opened` and a `$screen` for `/`.
3. Examples → "Analytics event" → tap **Track event** → `example_pressed` with `source=examples/analytics` appears in Live events. The SDK flushes every 10 seconds or 20 events, so background the app to force a flush.
4. Tap **Identify user**, then search People for `demo-user`: the person exists with `plan=free`.
5. Navigate between tabs and watch one `$screen` event arrive per pathname.
6. Remove the key and restart: the example shows "Configure EXPO\_PUBLIC\_POSTHOG\_KEY" and the app still boots.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --analytics none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/analytics.tsx`, `src/lib/__tests__/analytics-posthog.test.ts`, `src/lib/__tests__/tracking.test.ts`, `src/screens/examples/analytics-example-screen.tsx`.
2. **Replace, don't delete** `src/lib/analytics.ts`, `src/lib/tracking.ts`: core code imports them, so swap in the no-op version from `modules/analytics/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove expo-application expo-localization expo-tracking-transparency posthog-react-native`. Keep any of `expo-localization` (also used by `i18n/i18next`, `i18n/lingui`, `consent/consent`) that another module you picked still needs.
4. **Drop the config plugin** `expo-tracking-transparency` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<AnalyticsProvider>` and its import from `src/providers.tsx`.
6. **Remove the env keys** `EXPO_PUBLIC_POSTHOG_KEY`, `EXPO_PUBLIC_POSTHOG_HOST` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_POSTHOG_KEY`, `EXPO_PUBLIC_POSTHOG_HOST` from `src/lib/env.ts`.
7. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
8. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/analytics/posthog/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --analytics posthog
</Cmd>

Module id: `analytics/posthog` (the default for this category).

### Dependencies [#dependencies]

| Package                      | Version   | Kind                        |
| ---------------------------- | --------- | --------------------------- |
| `expo-application`           | `~57.0.3` | dependency (`expo install`) |
| `expo-device`                | `~57.0.2` | dependency (`expo install`) |
| `expo-localization`          | `~57.0.2` | dependency (`expo install`) |
| `expo-tracking-transparency` | `~57.0.2` | dependency (`expo install`) |
| `posthog-react-native`       | `^4.75.0` | dependency                  |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-tracking-transparency` (with options)

### Environment keys [#environment-keys]

| Key                        | Required | Server-only | Example                                           | Docs                                                  |
| -------------------------- | -------- | ----------- | ------------------------------------------------- | ----------------------------------------------------- |
| `EXPO_PUBLIC_POSTHOG_KEY`  | yes      | no          | `phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` | [dashboard](https://app.posthog.com/settings/project) |
| `EXPO_PUBLIC_POSTHOG_HOST` | no       | no          | `https://us.i.posthog.com`                        | [dashboard](https://app.posthog.com/settings/project) |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects &#x2A;App interactions (events, screens)*, &#x2A;Device or other ids (distinct id, device id)*, &#x2A;User IDs (when you call analytics.identify)*, &#x2A;Approximate location (GeoIP from the request IP)*; shared with PostHog (processor). Source of truth: [vendor disclosure](https://posthog.com/docs/privacy).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type                 | Linked to user | Tracking | Purposes  |
| -------------------- | -------------- | -------- | --------- |
| `ProductInteraction` | yes            | no       | Analytics |
| `DeviceID`           | yes            | no       | Analytics |
| `UserID`             | yes            | no       | Analytics |
| `CoarseLocation`     | yes            | no       | Analytics |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider            | From              |
| ----- | ------------------- | ----------------- |
| 40    | `AnalyticsProvider` | `@/lib/analytics` |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_POSTHOG_KEY`

### After setup [#after-setup]

1. PostHog: create a project at [https://app.posthog.com](https://app.posthog.com), copy the Project API key into EXPO\_PUBLIC\_POSTHOG\_KEY.
2. PostHog: EU cloud? set EXPO\_PUBLIC\_POSTHOG\_HOST=[https://eu.i.posthog.com](https://eu.i.posthog.com) (default is the US cloud).
3. PostHog: open Activity > Live events, call `analytics.track("hello")` from any screen (or open /examples/analytics with `--with-examples`) and watch it arrive.
4. App Tracking Transparency: expo-tracking-transparency is installed, but app.config.ts only adds its plugin, the NSUserTrackingUsageDescription purpose string and NSPrivacyTracking: true when `features.tracking` is true in readynative.config.ts - set it only if you link data across companies (ads attribution, IDFA); the prompt then runs once the app is active and `analytics.identify` waits for it. With it off (the default) Android's AD\_ID permission is blocked and you answer 'No' to tracking in App Store Connect.

### Files [#files]

<details>
  <summary>
    6 files copied to the project root
  </summary>

  * `src/app/examples/analytics.tsx`
  * `src/lib/__tests__/analytics-posthog.test.ts`
  * `src/lib/__tests__/tracking.test.ts`
  * `src/lib/analytics.ts`
  * `src/lib/tracking.ts`
  * `src/screens/examples/analytics-example-screen.tsx`
</details>


# Better Auth (/docs/features/auth/better-auth)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/auth/better-auth - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="auth" option="better-auth" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is self-hosted auth: no third-party dashboard, no per-user pricing, and the server lives in your own tree at `src/server/auth.ts`, mounted at `/api/auth/*` through `src/app/api/auth/[...all]+api.ts`. It ships email/password plus Apple and Google (each enabled only when its keys are set), the screens `src/app/(auth)/{sign-in,sign-up,reset}` with `src/screens/auth/*`, and `src/hooks/use-auth-redirect.ts` (signed-out → `/(auth)/sign-in`, signed-in inside `(auth)` → `/`). It requires `backend/api-routes`, since it needs somewhere to run. `@/lib/auth` keeps the same API whichever option you pick - pick Better Auth when you want the user table to be yours.

## Setup [#setup]

```bash
bun run setup --auth better-auth --backend api-routes
```

1. Decide where the API routes are served and put that origin in `.env` as `EXPO_PUBLIC_API_URL`: `http://<lan-ip>:8081` while `npx expo start` runs, or `https://<project>.expo.app` after you deploy. Without it the module is disabled: always `unauthenticated`, no redirect, and sign-in shows "Configure EXPO\_PUBLIC\_API\_URL".
2. Generate a server secret with `openssl rand -base64 32` and put it in `.env` as `BETTER_AUTH_SECRET`, then set `BETTER_AUTH_URL` to the same origin you used in step 1. Both go under the `# server (never EXPO_PUBLIC)` heading in `.env.example`. Better Auth warns about a missing secret in dev and refuses to start in production without one.
3. Swap the database. The shipped server uses `better-auth/adapters/memory`, kept on `globalThis` because the Expo dev server re-evaluates the route per request: zero infra, but every user is gone on restart and it can't run on multi-instance hosting. Replace `database:` in `src/server/auth.ts` with a real adapter (`pg` Pool, Drizzle, Prisma or Kysely), put the connection string in `.env` as `DATABASE_URL`, and run `npx @better-auth/cli migrate`.
4. Plug an email provider into `src/server/email.ts` (see "Sending email" below). `sendResetPassword` in `src/server/auth.ts` sends through it; until you do, dev logs a notice without the address or the link and production throws, so password reset emails are never silently dropped.
5. For Apple sign-in, create a Services ID in the \[Apple Developer] portal → \[Certificates, Identifiers & Profiles] → \[Identifiers] → \[Services IDs], and a key to sign the client-secret JWT. Put them in `.env` as `APPLE_CLIENT_ID` and `APPLE_CLIENT_SECRET`, and add `${BETTER_AUTH_URL}/api/auth/callback/apple` as the redirect URI. Turn on the Sign in with Apple capability for your app's bundle id while you're in that portal.
6. For Google sign-in, create a **Web** OAuth client in \[Google Cloud Console] → \[APIs & Services] → \[Credentials], add `${BETTER_AUTH_URL}/api/auth/callback/google` as an authorized redirect URI, and put the pair in `.env` as `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. Set the Android package name on the client if you build an Android release.

<Callout type="info" title="Going to production?">
  Deploy the API routes (EAS Hosting or your own host), point `EXPO_PUBLIC_API_URL` and `BETTER_AUTH_URL` at that https origin, and re-register every OAuth redirect URI against it. Set the server keys in EAS rather than in `.env`: `eas env:set --environment production --visibility sensitive` (EAS Hosting can't deploy `secret` variables). And do not ship the memory adapter.
</Callout>

7. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                                         | Where                   | Get it                                                                                                                                                                                                                                                                                       |
| ------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL`                       | client                  | the API routes origin: `http://<lan-ip>:8081` in dev, `https://<project>.expo.app` after deploy                                                                                                                                                                                              |
| `BETTER_AUTH_SECRET`                        | server                  | `openssl rand -base64 32` - [https://www.better-auth.com/docs/installation](https://www.better-auth.com/docs/installation)                                                                                                                                                                   |
| `BETTER_AUTH_URL`                           | server                  | same origin as `EXPO_PUBLIC_API_URL`                                                                                                                                                                                                                                                         |
| `DATABASE_URL`                              | server (after the swap) | your Postgres - [https://www.better-auth.com/docs/concepts/database](https://www.better-auth.com/docs/concepts/database)                                                                                                                                                                     |
| `APPLE_CLIENT_ID` / `APPLE_CLIENT_SECRET`   | server, optional        | Services ID + key JWT - [https://developer.apple.com/account/resources/identifiers/list/serviceId](https://developer.apple.com/account/resources/identifiers/list/serviceId), [https://www.better-auth.com/docs/authentication/apple](https://www.better-auth.com/docs/authentication/apple) |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | server, optional        | Web OAuth client - [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)                                                                                                                                                                    |

Deps: `better-auth`, `@better-auth/expo`, `expo-secure-store` (config plugin), `expo-network`. Expo Go works. Jest gets root `__mocks__` for `better-auth/react`, `@better-auth/expo/client` and `expo-secure-store` (those packages are ESM-only or native), plus tests for the session mapping and the redirect hook.

## Usage [#usage]

Read the session anywhere:

```ts
import { auth } from "@/lib/auth";

const session = auth.useSession();
if (session.status === "authenticated") console.log(session.user.email);
```

Email sign-up and sign-in:

```ts
import { signUpWithEmail, signInWithEmail } from "@/lib/auth";

await signUpWithEmail(name, email, password);
await signInWithEmail(email, password);
```

Social sign-in and sign-out:

```ts
import { auth, signInWithProvider } from "@/lib/auth";

await signInWithProvider("google"); // or "apple"
await auth.signOut();
```

`auth.openSignIn()` opens `/(auth)/sign-in` from anywhere; Settings → Developer tools uses it. A signed-in user is sent straight back, so sign out first.

### Server routes [#server-routes]

API routes never trust a user id from the client. The app attaches credentials with `auth.getAuthHeaders()` (the session cookie Better Auth keeps in SecureStore, as a `cookie` header; `{}` while signed out), and the route resolves the caller with `serverAuth.getRequestUser(request)` from `src/server/session.ts` (`auth.api.getSession({ headers })` against Better Auth's own session table). It returns `null` for a missing or invalid credential.

```ts
import { auth } from "@/lib/auth";

const res = await fetch(url, { headers: await auth.getAuthHeaders() });
```

```ts
import { serverAuth } from "@/server/session";

const user = await serverAuth.getRequestUser(request);
if (!user) return new Response("Unauthorized", { status: 401 });
```

### Delete account [#delete-account]

Settings ships a confirm-guarded "Delete account" row (App Store Review 5.1.1(v), Play "Account deletion") that calls `auth.deleteAccount(options?: { password?: string })` → `authClient.deleteUser()`; `src/server/auth.ts` enables it with `user: { deleteUser: { enabled: true } }`, which is required. Better Auth 1.7 deletes immediately with a fresh session (`session.freshAge`, default 1 day, measured from session creation). The module sets it explicitly from `SESSION_FRESH_AGE_SECONDS` in `src/lib/auth-policy.ts`, shared by the server and the app, and `auth.prepareDeleteAccount()` applies the same rule to `authClient.getSession()` before Settings erases anything else (analytics, purchases), so a cancelled password prompt leaves everything as it was. A stale session (in the pre-flight, or `SESSION_EXPIRED` from the server) becomes `code: "REAUTH_REQUIRED"`; Settings then shows a "Confirm it's you" password sheet and retries with `{ password }` (a valid password skips the freshness check). `INVALID_PASSWORD` asks again; `CREDENTIAL_ACCOUNT_NOT_FOUND` (a social-only user has no password) maps to `SIGN_IN_AGAIN`, and Settings tells the user to sign in again first. Better Auth deletes the user and their sessions/accounts and the client store flips to signed-out. To confirm by email instead, set `sendDeleteAccountVerification` in `src/server/auth.ts` to confirm by email before `beforeDelete`/`afterDelete` run. Rows in your own tables that reference the user are yours to remove in `afterDelete`.

## Sending email [#sending-email]

`src/server/email.ts` exports `sendEmail({ to, subject, text, html? })`, the one place server code sends mail. It ships without a provider: replace `const deliver = null` with a function that calls yours. Resend (`bun add resend`, `RESEND_API_KEY` in `.env` as a server key):

```ts
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);
const deliver = async (email: Email) => {
  const { error } = await resend.emails.send({ from: "App <noreply@your-domain.com>", ...email });
  if (error) throw new Error(`[email] Resend: ${error.message}`);
};
```

Postmark (`bun add postmark`, `POSTMARK_SERVER_TOKEN`):

```ts
import { ServerClient } from "postmark";

const postmark = new ServerClient(process.env.POSTMARK_SERVER_TOKEN ?? "");
const deliver = async (email: Email) => {
  await postmark.sendEmail({
    From: "noreply@your-domain.com",
    To: email.to,
    Subject: email.subject,
    TextBody: email.text,
    HtmlBody: email.html,
  });
};
```

Both run on EAS Hosting (they only need `fetch`); verify your sending domain with the provider first, and set the key with `eas env:set --environment production --visibility sensitive`. Better Auth awaits the hook, so a provider error reaches the client as a failed "Send reset link" - it's logged server-side too. The reset link opens `${BETTER_AUTH_URL}/api/auth/reset-password/<token>`, which redirects to `/?token=…` on that origin; the page that asks for the new password and calls `authClient.resetPassword({ newPassword, token })` is yours to add (a web route, or a deep link into the app).

## Gotchas [#gotchas]

* `EXPO_PUBLIC_API_URL` is shared with the data modules. When both are selected, the first module's example value wins in `.env.example`.
* Native Sign in with Apple (the `expo-apple-authentication` id-token flow) is not wired; the button uses the web OAuth flow through the system browser. `appBundleIdentifier` is already passed, so you can add the id-token flow client-side.
* Better Auth warns about a missing `BETTER_AUTH_SECRET` in dev and refuses to start in production without one.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Set `EXPO_PUBLIC_API_URL=http://<lan-ip>:8081`, `BETTER_AUTH_URL` to the same, and a random `BETTER_AUTH_SECRET`, then run `bun run start`.
2. `curl -s $BETTER_AUTH_URL/api/auth/ok` returns `{"ok":true}`.
3. The app opens on `/(auth)/sign-in` after onboarding. Tap "Create one" → name, email, password → you land on Home and Settings shows the Account card.
4. Examples → "Auth session" shows name, email and id; "Sign out" takes you back to sign-in.
5. Sign in with the same email and a wrong password → toast "Invalid email or password"; the correct one lands on Home. Kill and reopen the app → still signed in, from the SecureStore cookie.
6. Tap "Forgot password?" → enter the email → "Check your inbox"; with no email provider plugged in, the `npx expo start` terminal shows `[email] No email provider is configured` (never the link). With one, the email arrives.
7. With Apple or Google keys set, "Continue with Google" opens the browser and returns via `readynative://` with an authenticated session.
8. Restart the dev server → the users are gone. That's the memory adapter, and it's expected until you swap the database.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --auth none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `__mocks__/@better-auth/expo/client.ts`, `__mocks__/better-auth/react.ts`, `__mocks__/expo-secure-store.ts`, `src/app/(auth)/_layout.tsx`, `src/app/(auth)/reset.tsx`, `src/app/(auth)/sign-in.tsx`, `src/app/(auth)/sign-up.tsx`, `src/app/api/auth/[...all]+api.ts`, `src/app/examples/auth.tsx`, `src/hooks/__tests__/use-auth-redirect.test.tsx`, `src/lib/__tests__/auth-better-auth-disabled.test.tsx`, `src/lib/__tests__/auth-better-auth.test.tsx`, `src/lib/auth-policy.ts`, `src/screens/auth/reset-screen.tsx`, `src/screens/auth/sign-in-screen.tsx`, `src/screens/auth/sign-up-screen.tsx`, `src/screens/examples/auth-example-screen.tsx`, `src/server/__tests__/email.test.ts`, `src/server/__tests__/session-better-auth.test.ts`, `src/server/auth.ts`, `src/server/email.ts`.
2. **Replace, don't delete** `src/hooks/use-auth-redirect.ts`, `src/lib/auth.ts`, `src/server/session.ts`: core code imports them, so swap in the no-op version from `modules/auth/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @better-auth/expo better-auth expo-network expo-secure-store`.
4. **Drop the config plugin** `expo-secure-store` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Remove the env keys** `EXPO_PUBLIC_API_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `DATABASE_URL`, `APPLE_CLIENT_ID`, `APPLE_CLIENT_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_API_URL` from `src/lib/env.ts`.
6. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
7. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/auth/better-auth/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --auth better-auth
</Cmd>

Module id: `auth/better-auth`.

### Dependencies [#dependencies]

| Package             | Version   | Kind                        |
| ------------------- | --------- | --------------------------- |
| `@better-auth/expo` | `^1.7.5`  | dependency                  |
| `better-auth`       | `^1.7.5`  | dependency                  |
| `expo-network`      | `~57.0.2` | dependency (`expo install`) |
| `expo-secure-store` | `~57.0.4` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-secure-store`

### Environment keys [#environment-keys]

| Key                    | Required | Server-only | Example                                | Docs                                                                                  |
| ---------------------- | -------- | ----------- | -------------------------------------- | ------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL`  | no       | no          | `http://localhost:8081`                | [dashboard](https://www.better-auth.com/docs/integrations/expo)                       |
| `BETTER_AUTH_SECRET`   | yes      | yes         | `generate-with-openssl-rand-base64-32` | [dashboard](https://www.better-auth.com/docs/installation#set-environment-variables)  |
| `BETTER_AUTH_URL`      | yes      | yes         | `http://localhost:8081`                | [dashboard](https://www.better-auth.com/docs/installation#set-environment-variables)  |
| `DATABASE_URL`         | no       | yes         | `postgres://user:pass@host:5432/app`   | [dashboard](https://www.better-auth.com/docs/installation#configure-database)         |
| `APPLE_CLIENT_ID`      | no       | yes         | `com.acme.app.web`                     | [dashboard](https://developer.apple.com/account/resources/identifiers/list/serviceId) |
| `APPLE_CLIENT_SECRET`  | no       | yes         | `eyJ...`                               | [dashboard](https://www.better-auth.com/docs/authentication/apple)                    |
| `GOOGLE_CLIENT_ID`     | no       | yes         | `xxx.apps.googleusercontent.com`       | [dashboard](https://console.cloud.google.com/apis/credentials)                        |
| `GOOGLE_CLIENT_SECRET` | no       | yes         | `GOCSPX-...`                           | [dashboard](https://console.cloud.google.com/apis/credentials)                        |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects &#x2A;Email address, name (account)*, *Session tokens*; shared with Nobody - stored on your own backend. Source of truth: [vendor disclosure](https://www.better-auth.com/docs/concepts/database).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type           | Linked to user | Tracking | Purposes         |
| -------------- | -------------- | -------- | ---------------- |
| `EmailAddress` | yes            | no       | AppFunctionality |
| `Name`         | yes            | no       | AppFunctionality |
| `UserID`       | yes            | no       | AppFunctionality |

### Compatibility [#compatibility]

* Requires `backend` = [`api-routes`](https://readynative.app/docs/features/backend/api-routes)

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_API_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`

### After setup [#after-setup]

1. Better Auth: `openssl rand -base64 32` → BETTER\_AUTH\_SECRET in .env; BETTER\_AUTH\_URL = the API routes origin (http\://\<lan-ip>:8081 in dev, the EAS Hosting URL in prod)
2. Better Auth: the shipped src/server/auth.ts uses the in-memory adapter (users vanish on restart) - swap it for Postgres/Drizzle/Prisma before shipping (docs.md)
3. Apple sign-in: create a Services ID (APPLE\_CLIENT\_ID) + key (APPLE\_CLIENT\_SECRET JWT) at developer.apple.com and add BETTER\_AUTH\_URL/api/auth/callback/apple as a return URL
4. Google sign-in: create a Web OAuth client at console.cloud.google.com with BETTER\_AUTH\_URL/api/auth/callback/google as an authorised redirect URI
5. Set the same server keys on EAS Hosting: `eas env:set --environment production --name BETTER_AUTH_SECRET --value … --visibility sensitive` (EAS Hosting can't deploy `secret` variables), then `eas deploy --environment production`

### Files [#files]

<details>
  <summary>
    24 files copied to the project root
  </summary>

  * `__mocks__/@better-auth/expo/client.ts`
  * `__mocks__/better-auth/react.ts`
  * `__mocks__/expo-secure-store.ts`
  * `src/app/(auth)/_layout.tsx`
  * `src/app/(auth)/reset.tsx`
  * `src/app/(auth)/sign-in.tsx`
  * `src/app/(auth)/sign-up.tsx`
  * `src/app/api/auth/[...all]+api.ts`
  * `src/app/examples/auth.tsx`
  * `src/hooks/__tests__/use-auth-redirect.test.tsx`
  * `src/hooks/use-auth-redirect.ts`
  * `src/lib/__tests__/auth-better-auth-disabled.test.tsx`
  * `src/lib/__tests__/auth-better-auth.test.tsx`
  * `src/lib/auth-policy.ts`
  * `src/lib/auth.ts`
  * `src/screens/auth/reset-screen.tsx`
  * `src/screens/auth/sign-in-screen.tsx`
  * `src/screens/auth/sign-up-screen.tsx`
  * `src/screens/examples/auth-example-screen.tsx`
  * `src/server/__tests__/email.test.ts`
  * `src/server/__tests__/session-better-auth.test.ts`
  * `src/server/auth.ts`
  * `src/server/email.ts`
  * `src/server/session.ts`
</details>


# Clerk (/docs/features/auth/clerk)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/auth/clerk - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="auth" option="clerk" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This wires Clerk into the app: email/password with a 6-digit code step, Sign in with Apple, Google SSO, and a hosted user database you never have to run. You get `src/app/(auth)/{sign-in,sign-up,reset}` with `src/screens/auth/*`, the redirect hook `src/hooks/use-auth-redirect.ts` (signed-out users land on `/(auth)/sign-in`, signed-in users leave `(auth)`, onboarding wins first), and, with `--with-examples`, an example at `src/app/examples/auth.tsx`. `@/lib/auth` keeps the same API whichever option you pick - pick Clerk when you want user management, organizations and a polished dashboard without owning a database.

## Setup [#setup]

```bash
bun run setup --auth clerk
```

1. Create an application at [clerk.com](https://clerk.com), then open \[Dashboard] → \[API keys]. Copy the publishable key (`pk_test_…`) into `.env` as `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`. Without it `ClerkProvider` is never mounted: `useSession()` stays `unauthenticated`, there's no redirect, and sign-in shows "Configure Clerk".
2. In Clerk, open \[User & Authentication] → \[Email, phone, username] and enable **Email address** and **Password**, with verification set to **Email verification code** - the shipped sign-up and reset screens expect the code step.
3. Open \[SSO connections] → \[Apple] and enable it. Add your iOS bundle id under Clerk's "Apple → Native" section so the native sheet is accepted.
4. Turn on the Sign in with Apple capability for that bundle id in the \[Apple Developer] portal → \[Certificates, Identifiers & Profiles] → \[Identifiers] → your app id.
5. Open \[SSO connections] → \[Google] and enable it. Development instances work with Clerk's shared credentials, so there's nothing to paste yet.
6. Open \[Native applications] and add the iOS bundle id and the Android package from `readynative.config.ts`, so Clerk accepts native requests from your app.
7. Screens call `useT()` with English keys. If you selected an i18n module and haven't added `ru` entries, they render in English - keys fall back to themselves.

<Callout type="info" title="Going to production?">
  Swap the key for the production instance's `pk_live_…`, and give Google your own OAuth client: create one in \[Google Cloud Console] → \[APIs & Services] → \[Credentials] and paste the client id and secret into Clerk's Google connection. Clerk's shared credentials are development-only.
</Callout>

8. If you use API routes that need the caller (payments/stripe), copy the **Secret key** from \[Dashboard] → \[API keys] into `.env` as `CLERK_SECRET_KEY`, under the `# server (never EXPO_PUBLIC)` heading - never with an `EXPO_PUBLIC_` prefix. Alternatively set `CLERK_JWT_KEY` to the JWT public key (PEM) from the same page to verify tokens without a network call. With neither set, `getRequestUser` throws. For EAS Hosting add it with `eas env:set --environment production --visibility sensitive` (`secret` variables don't deploy to EAS Hosting).
9. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                                               | Where                                                                                                                                                             |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`               | [Dashboard → API keys](https://dashboard.clerk.com/last-active?path=api-keys) (`pk_test_…`)                                                                       |
| `CLERK_SECRET_KEY` (server)                       | [Dashboard → API keys](https://dashboard.clerk.com/last-active?path=api-keys) (`sk_test_…`); needed by API routes that verify the caller                          |
| `CLERK_JWT_KEY` (server, optional)                | Dashboard → API keys → JWT public key (PEM); [networkless verification](https://clerk.com/docs/guides/sessions/manual-jwt-verification) instead of the secret key |
| `CLERK_WEBHOOK_SIGNING_SECRET` (server, optional) | Dashboard → Webhooks → your `/api/webhooks/clerk` endpoint → Signing secret (`whsec_…`); with `backend/api-routes`, for `user.deleted`                            |

Deps: `@clerk/expo ^4.6.6` (the maintained package; `@clerk/clerk-expo` is deprecated), `expo-secure-store`, `expo-auth-session`, `expo-apple-authentication`, `expo-crypto` (`expo-web-browser` is a core dep). Config plugins: `@clerk/expo`, `expo-apple-authentication`, `expo-secure-store`.

## Usage [#usage]

Read the session anywhere:

```ts
import { auth } from "@/lib/auth";

const session = auth.useSession();
if (session.status === "authenticated") console.log(session.user.email);
```

Sign up in two steps, because Clerk mails a code:

```ts
import { signUpWithEmail, verifySignUpCode } from "@/lib/auth";

const result = await signUpWithEmail(email, password);
if (result.status === "needs_verification") await verifySignUpCode(code);
```

Social sign-in and sign-out:

```ts
import { auth, signInWithApple, canSignInWithApple, signInWithGoogle } from "@/lib/auth";

if (canSignInWithApple) await signInWithApple();
await signInWithGoogle();
await auth.signOut();
```

`auth.openSignIn()` opens `/(auth)/sign-in` from anywhere; Settings → Developer tools uses it. A signed-in user is sent straight back, so sign out first.

### Server routes [#server-routes]

API routes never trust a user id from the client. The app attaches credentials with `auth.getAuthHeaders()` (`authorization: Bearer <session token>`; `{}` while signed out), and the route resolves the caller with `serverAuth.getRequestUser(request)` from `src/server/session.ts` (`verifyToken` from `@clerk/backend`, keyed by `CLERK_SECRET_KEY`, or networkless by `CLERK_JWT_KEY`). It returns `null` for a missing or invalid credential, and throws when neither `CLERK_SECRET_KEY` nor `CLERK_JWT_KEY` is set - answer 503 then.

```ts
import { auth } from "@/lib/auth";

const res = await fetch(url, { headers: await auth.getAuthHeaders() });
```

```ts
import { serverAuth } from "@/server/session";

const user = await serverAuth.getRequestUser(request);
if (!user) return new Response("Unauthorized", { status: 401 });
```

### Delete account [#delete-account]

Settings ships a confirm-guarded "Delete account" row (App Store Review 5.1.1(v), Play "Account deletion") that calls `auth.deleteAccount()` → `clerk.user.delete()`. Turn on **User & Authentication → Settings → Allow users to delete their accounts** in the Clerk dashboard first - with it off (`user.deleteSelfEnabled` is false) `deleteAccount()` throws a clear error saying so. Clerk ends the session itself once the user is gone; `useAuthRedirect` sends them to sign-in. Data you keep outside Clerk needs a `user.deleted` webhook: with `backend/api-routes`, `POST /api/webhooks/clerk` handles `user.deleted` and erases that user in the configured vendors. In the Clerk dashboard → \[Webhooks], add the endpoint `https://<your-api>/api/webhooks/clerk` subscribed to `user.deleted`, and put its signing secret (`whsec_…`) in `.env` as `CLERK_WEBHOOK_SIGNING_SECRET` (server, never `EXPO_PUBLIC_`).

## Gotchas [#gotchas]

* Clerk's iOS SDK requires iOS 17; the config plugin raises the deployment target for dev builds.
* Sign-in steps that need a second factor (MFA) or extra fields surface as an error toast. If you enable those in the dashboard, add screens for them.
* Expo Go is fine for the flows shipped here: Clerk's native module is optional (`requireOptionalNativeModule`) and only backs Clerk's native views and biometrics, which this module doesn't use.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Put the key in `.env`, run `npx expo start` (or a dev build), and open a fresh install: onboarding → `/(auth)/sign-in`.
2. Sign up with a new email → code step → enter the mailed code → you land on `/` and Settings shows the Account card with the email.
3. Settings → Sign out → back on sign-in.
4. Sign in with a wrong password → error toast with Clerk's message, no navigation.
5. On iOS, tap Continue with Apple → native sheet → signed in (the first time creates the user, the second signs in).
6. Tap Continue with Google → system browser → back in the app signed in.
7. Tap Forgot password → code step → code plus a new password → signed in with the new password.
8. Kill and reopen the app → still signed in, token read from secure store.
9. Examples → Auth session → the JSON shows `status: "authenticated"`.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --auth none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/(auth)/_layout.tsx`, `src/app/(auth)/reset.tsx`, `src/app/(auth)/sign-in.tsx`, `src/app/(auth)/sign-up.tsx`, `src/app/examples/auth.tsx`, `src/lib/__tests__/auth-clerk.test.tsx`, `src/screens/auth/auth-form.ts`, `src/screens/auth/reset-screen.tsx`, `src/screens/auth/sign-in-screen.tsx`, `src/screens/auth/sign-up-screen.tsx`, `src/screens/examples/auth-example-screen.tsx`, `src/server/__tests__/session-clerk.test.ts`.
2. **Replace, don't delete** `src/hooks/use-auth-redirect.ts`, `src/lib/auth.ts`, `src/server/session.ts`: core code imports them, so swap in the no-op version from `modules/auth/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @clerk/backend @clerk/expo expo-apple-authentication expo-auth-session expo-crypto expo-secure-store`.
4. **Drop the config plugins** `@clerk/expo`, `expo-apple-authentication`, `expo-secure-store` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads them from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<AuthProvider>` and its import from `src/providers.tsx`.
6. **Remove the env keys** `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`, `CLERK_JWT_KEY` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` from `src/lib/env.ts`.
7. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
8. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/auth/clerk/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --auth clerk
</Cmd>

Module id: `auth/clerk`.

### Dependencies [#dependencies]

| Package                     | Version    | Kind                        |
| --------------------------- | ---------- | --------------------------- |
| `@clerk/backend`            | `^3.19.0`  | dependency                  |
| `@clerk/expo`               | `^4.6.8`   | dependency                  |
| `expo-apple-authentication` | `~57.0.2`  | dependency (`expo install`) |
| `expo-auth-session`         | `~57.0.12` | dependency (`expo install`) |
| `expo-crypto`               | `~57.0.3`  | dependency (`expo install`) |
| `expo-secure-store`         | `~57.0.4`  | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `@clerk/expo`
* `expo-apple-authentication`
* `expo-secure-store`

### Environment keys [#environment-keys]

| Key                                 | Required | Server-only | Example                         | Docs                                                                        |
| ----------------------------------- | -------- | ----------- | ------------------------------- | --------------------------------------------------------------------------- |
| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | yes      | no          | `pk_test_...`                   | [dashboard](https://dashboard.clerk.com/last-active?path=api-keys)          |
| `CLERK_SECRET_KEY`                  | no       | yes         | `sk_test_...`                   | [dashboard](https://dashboard.clerk.com/last-active?path=api-keys)          |
| `CLERK_JWT_KEY`                     | no       | yes         | `-----BEGIN PUBLIC KEY-----...` | [dashboard](https://clerk.com/docs/guides/sessions/manual-jwt-verification) |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects &#x2A;Email address, phone, name (account)*, *Session tokens*, *Device identifiers*; shared with Clerk (processor). Source of truth: [vendor disclosure](https://clerk.com/legal/privacy).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type           | Linked to user | Tracking | Purposes         |
| -------------- | -------------- | -------- | ---------------- |
| `EmailAddress` | yes            | no       | AppFunctionality |
| `PhoneNumber`  | yes            | no       | AppFunctionality |
| `Name`         | yes            | no       | AppFunctionality |
| `UserID`       | yes            | no       | AppFunctionality |
| `DeviceID`     | yes            | no       | AppFunctionality |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider       | From         |
| ----- | -------------- | ------------ |
| 30    | `AuthProvider` | `@/lib/auth` |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`

### After setup [#after-setup]

1. Clerk: create an application, copy the Publishable key (API keys) into .env as EXPO\_PUBLIC\_CLERK\_PUBLISHABLE\_KEY.
2. Clerk: API routes that need the caller (payments/stripe) verify the session token with @clerk/backend - copy the Secret key into .env as CLERK\_SECRET\_KEY (server-only; for EAS Hosting also `eas env:set --environment production --visibility sensitive`).
3. Clerk: User & Authentication → Email → enable Email address + Password + Email verification code.
4. Clerk: User & Authentication → Settings → enable "Allow users to delete their accounts" (Settings → Delete account calls user.delete()).
5. Clerk: SSO connections → Apple: add the iOS bundle id (native Sign in with Apple); Google: add your own OAuth client for production.
6. Clerk: Native applications → add the iOS bundle id / Android package so native flows are allowed.
7. Apple: enable the Sign in with Apple capability for the bundle id (EAS does it on the first build).
8. Dev builds: the @clerk/expo plugin raises the iOS deployment target to 17.0.

### Files [#files]

<details>
  <summary>
    15 files copied to the project root
  </summary>

  * `src/app/(auth)/_layout.tsx`
  * `src/app/(auth)/reset.tsx`
  * `src/app/(auth)/sign-in.tsx`
  * `src/app/(auth)/sign-up.tsx`
  * `src/app/examples/auth.tsx`
  * `src/hooks/use-auth-redirect.ts`
  * `src/lib/__tests__/auth-clerk.test.tsx`
  * `src/lib/auth.ts`
  * `src/screens/auth/auth-form.ts`
  * `src/screens/auth/reset-screen.tsx`
  * `src/screens/auth/sign-in-screen.tsx`
  * `src/screens/auth/sign-up-screen.tsx`
  * `src/screens/examples/auth-example-screen.tsx`
  * `src/server/__tests__/session-clerk.test.ts`
  * `src/server/session.ts`
</details>


# Auth (/docs/features/auth)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/auth/README.md - do not edit. */}

<Badge>
  Pro
</Badge>

Hey - here's how auth works in ReadyNative.

This category owns everything about the signed-in user: the sign-in, sign-up and reset screens under `src/app/(auth)`, the redirect hook that decides where a signed-out person lands, and the Account card in Settings.

`@/lib/auth` always exists, whichever option you pick: `auth.useSession()` and `auth.signOut()` read the same in every one of them, and `auth/none` is a no-op that reports a signed-out session. Screens you write against the shim keep working when you switch options.

Pick **Supabase** if you also want a Postgres database and row-level security behind the same account - it's the cheapest path from zero to a real backend. Pick **Clerk** if you'd rather buy user management outright: hosted accounts, a good dashboard, organizations, and a code-based sign-up flow that's already wired here. Pick **Better Auth** if the user table has to be yours - it runs on your own API routes (`backend/api-routes` is required), with no third-party dashboard and no per-user pricing, in exchange for owning the database and the mail provider.

This category is part of ReadyNative Pro.

## Options [#options]

One option per category - `--auth <option>` picks it:

<Cmd>
  bun run setup --auth supabase
</Cmd>

| Option                         | Label                   | Expo Go | Hint                                                                                          |
| ------------------------------ | ----------------------- | ------- | --------------------------------------------------------------------------------------------- |
| [`supabase`](./supabase)       | Supabase Auth (default) | yes     | email+password, Apple (native), Google (OAuth) · session on the storage adapter · Expo Go OK  |
| [`clerk`](./clerk)             | Clerk                   | yes     | email+code verification, Apple (native), Google (SSO) · @clerk/expo · Expo Go OK for JS flows |
| [`better-auth`](./better-auth) | Better Auth             | yes     | self-hosted on the API routes · email/password + Apple/Google · Expo Go OK                    |
| [`none`](./none)               | No auth                 | yes     | auth.useSession() shim returns signed-out, signOut resolves                                   |


# No auth (/docs/features/auth/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/auth/none - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="auth" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-op auth option: the app has no accounts, no sign-in screens and no sign-in service to configure. It owns `src/lib/auth.ts` as a re-export of the core shim, so `@/lib/auth` keeps the same API whichever option you pick - `auth.useSession()` returns a signed-out session and `auth.signOut()` resolves. It also owns `src/hooks/use-auth-redirect.ts` as a no-op `useAuthRedirect()`, so the core root layout is identical for every auth option (the hook documents the contract a real module has to implement). Pick this while you're building screens that don't need a user yet.

## Setup [#setup]

```bash
bun run setup --auth none
```

There's nothing to configure and no keys to paste. The Settings "Account" card only renders for an authenticated session, so it stays hidden.

When you do want accounts, switch with `bun run setup --auth supabase`, `--auth clerk` or `--auth better-auth`.

## Usage [#usage]

The calls exist and are safe to write today, so screens don't need rewriting when you switch:

```ts
import { auth } from "@/lib/auth";

const session = auth.useSession(); // always { status: "unauthenticated" }
await auth.signOut(); // resolves, does nothing
```

`auth.deleteAccount()` also resolves without doing anything, so the Settings "Delete account" row (which only renders for a signed-in user) compiles against this option.

`auth.getAuthHeaders()` resolves to `{}`, and the server half, `src/server/session.ts`, exports a `serverAuth` whose `getRequestUser(request)` always returns `null` (`provider: "none"`). API routes that need a caller therefore answer 401 - payments/stripe does unless you set `STRIPE_ALLOW_ANONYMOUS=true`.

## Gotchas [#gotchas]

* Anything gated on `session.status === "authenticated"` never renders while this option is selected. That includes the Settings Account card.
* Nothing here needs a dev build; Expo Go is fine.

## Reference [#reference]

Everything below is generated from `modules/auth/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --auth none
</Cmd>

Module id: `auth/none`.

### Files [#files]

<details>
  <summary>
    3 files copied to the project root
  </summary>

  * `src/lib/auth.ts`
  * `src/hooks/use-auth-redirect.ts`
  * `src/server/session.ts`
</details>


# Supabase Auth (/docs/features/auth/supabase)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/auth/supabase - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="auth" option="supabase" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This gives you email/password, Sign in with Apple and Google sign-in on top of `@supabase/supabase-js`, plus the screens to use them: `src/app/(auth)/{sign-in,sign-up,reset,new-password}` with `src/screens/auth/*`, a redirect hook in `src/hooks/use-auth-redirect.ts` that sends signed-out users to `/(auth)/sign-in` and signed-in users out of `(auth)` (onboarding still wins first), and, with `--with-examples`, an example at `src/app/examples/auth.tsx`. `@/lib/auth` keeps the same API whichever option you pick, so `auth.useSession()` and `auth.signOut()` read the same here as under Clerk or Better Auth - what you also get from Supabase is a Postgres database and row-level security behind the same account. The session is persisted through the storage adapter (`@/lib/storage`), so it follows whichever storage module you selected.

## Setup [#setup]

```bash
bun run setup --auth supabase
```

1. Create a project at [supabase.com](https://supabase.com), then open \[Project Settings] → \[API]. Copy the Project URL into `.env` as `EXPO_PUBLIC_SUPABASE_URL` and the anon / publishable key as `EXPO_PUBLIC_SUPABASE_ANON_KEY`. Until both are set auth is disabled: no redirect, `useSession()` stays `unauthenticated`, and the sign-in screen shows "Configure Supabase".
2. In Supabase, open \[Authentication] → \[URL Configuration] → \[Redirect URLs] and add `readynative://` (the scheme from your `readynative.config.ts`) and `readynative://new-password`. Without this the Google and password-reset round trips never come back to the app. In Expo Go the links start with `exp://<lan-ip>:8081/--/` instead, so add `exp://**` for your dev project only.
3. Open \[Authentication] → \[Providers] → \[Email] and leave "Confirm email" on (the default). Sign-up then returns `needs_verification` and the user signs in after clicking the mail.
4. Open \[Authentication] → \[Providers] → \[Apple] and enable it. Set Client IDs to your iOS bundle id - the native flow uses `signInWithIdToken`, so you don't need a Services ID.
5. Turn on the Sign in with Apple capability for that bundle id in the \[Apple Developer] portal → \[Certificates, Identifiers & Profiles] → \[Identifiers] → your app id. The `expo-apple-authentication` config plugin handles the rest.
6. Open \[Authentication] → \[Providers] → \[Google] and enable it with a **Web** OAuth client created in \[Google Cloud Console] → \[APIs & Services] → \[Credentials]. Paste Supabase's callback URL into that client's authorized redirect URIs. The app itself never needs a Google client id.
7. Screens call `useT()` with English keys. If you selected an i18n module and haven't added `ru` entries, they render in English - keys fall back to themselves.

<Callout type="info" title="Going to production?">
  Point the app at your production Supabase project: the URL and anon key change, and every redirect URL from step 2 has to exist in that project too. The Google web client needs the production Supabase callback URL added as well.
</Callout>

8. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                             | Where                                                       |
| ------------------------------- | ----------------------------------------------------------- |
| `EXPO_PUBLIC_SUPABASE_URL`      | Dashboard → Project Settings → API → Project URL            |
| `EXPO_PUBLIC_SUPABASE_ANON_KEY` | Dashboard → Project Settings → API → anon / publishable key |

Deps: `@supabase/supabase-js ^2.116`, `expo-apple-authentication`, `expo-auth-session`, `expo-crypto` (`expo-web-browser` is a core dep). Config plugin: `expo-apple-authentication`.

## Usage [#usage]

Read the session anywhere:

```ts
import { auth } from "@/lib/auth";

const session = auth.useSession();
if (session.status === "authenticated") console.log(session.user.email);
```

Sign in with email or with Apple:

```ts
import { signInWithEmail, signInWithApple, canSignInWithApple } from "@/lib/auth";

await signInWithEmail(email, password);
if (canSignInWithApple) await signInWithApple();
```

Sign out, and reach the raw client when you need Postgres:

```ts
import { auth, supabase } from "@/lib/auth";

await auth.signOut();
const { data } = await supabase!.from("profiles").select("*");
```

`auth.openSignIn()` opens `/(auth)/sign-in` from anywhere; Settings → Developer tools uses it. A signed-in user is sent straight back, so sign out first.

### Server routes [#server-routes]

API routes never trust a user id from the client. The app attaches credentials with `auth.getAuthHeaders()` (`authorization: Bearer <access token>`, refreshed first if expired; `{}` while signed out), and the route resolves the caller with `serverAuth.getRequestUser(request)` from `src/server/session.ts` (`supabase.auth.getUser(jwt)`: signature, expiry, and that the user still exists; it reads the same `EXPO_PUBLIC_SUPABASE_*` keys). It returns `null` for a missing or invalid credential.

```ts
import { auth } from "@/lib/auth";

const res = await fetch(url, { headers: await auth.getAuthHeaders() });
```

```ts
import { serverAuth } from "@/server/session";

const user = await serverAuth.getRequestUser(request);
if (!user) return new Response("Unauthorized", { status: 401 });
```

### Delete account [#delete-account]

Settings ships a confirm-guarded "Delete account" row (App Store Review 5.1.1(v), Play "Account deletion") that calls `auth.deleteAccount()`. The anon client cannot delete auth users, so the module ships `supabase/migrations/20260921000000_delete_user.sql`: a `security definer` function `public.delete_user()` that deletes `auth.users` for `auth.uid()`, granted to `authenticated` only. Supabase forbids `delete from storage.objects` in SQL (a trigger added in January 2026; the Storage API is the documented way), so a second migration, `supabase/migrations/20260924000000_delete_user_storage.sql`, adds `public.list_user_objects()` (`security definer`, returns the caller's objects by `owner_id`), `public.account_deletion_ready()` and two RLS policies on `storage.objects`, "readynative: owners read their own objects" (select) and "readynative: owners delete their own objects" (delete) - `remove()` needs both. Both are scoped to the signed-in user's own files (`owner_id = auth.uid()`) in every bucket; nobody can read or delete anyone else's objects through them. To narrow them to some buckets, add `and bucket_id in ('avatars', 'uploads')` to both `using` clauses in the migration - files in other buckets then survive account deletion, so delete those from your server. Apply both (`supabase db push` or the SQL editor) - `doctor --store` notes when the file is missing. `deleteAccount()` lists the user's files, removes them bucket by bucket with `supabase.storage.from(bucket).remove(paths)` in batches of 1000, re-lists and throws if anything is left (the account is kept), then calls the `delete_user` RPC and `signOut({ scope: "local" })`; `useAuthRedirect` sends the user to sign-in. Before any of that - and before Settings erases the user's analytics and purchase data on your server - `auth.prepareDeleteAccount()` calls `public.account_deletion_ready()` (shipped with the storage migration; `true` once `delete_user()` exists) and `list_user_objects()`, so a missing migration or a broken storage policy stops the deletion while nothing has been touched. If a migration isn't applied (PostgREST `PGRST202`, or `account_deletion_ready()` returning `false`) the error names the migration file to apply. Your own tables clean up with `references auth.users (id) on delete cascade`; anything else, delete inside the function before the `auth.users` row.

## Gotchas [#gotchas]

* The Google flow uses the implicit grant (tokens in the callback URL) as in Supabase's Expo guide; PKCE `code` callbacks are handled too.
* Password reset is a round trip: "Forgot password?" (`/(auth)/reset`) calls `resetPassword(email)`, whose link opens `/(auth)/new-password` (`passwordResetRedirectUri()`). That screen reads the link with `Linking.useLinkingURL()`, activates the recovery session with `startPasswordRecovery(url)` (implicit-flow tokens in the fragment, or a PKCE `code`), and saves the new password with `updatePassword()` → `supabase.auth.updateUser({ password })`. An expired or already-used link shows "This link is invalid or has expired" with a button to request a new one. The recovery session is a real sign-in: a user who opens the link and leaves stays signed in on that device. `use-auth-redirect.ts` skips `new-password` so the screen isn't bounced to Home the moment the session starts. With the default implicit flow the link works on any device that has the app; if you switch the client to `flowType: "pkce"`, it only works on the device that asked for it.
* Expo Go works for everything here: Sign in with Apple runs in Expo Go on iOS, and Google opens the system browser.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Put both keys in `.env`, run `npx expo start`, and open a fresh install: onboarding → `/(auth)/sign-in`.
2. Sign up with a new email → toast "Check your email" → confirm the mail → sign in → you land on `/` and Settings shows the Account card.
3. Settings → Sign out → back on sign-in.
4. Sign in with a wrong password → error toast with Supabase's message, no navigation.
5. On iOS, tap Continue with Apple → native sheet → signed in; the name appears in Settings on the first sign-in.
6. Tap Continue with Google → system browser → back in the app signed in (this needs the redirect URL from setup step 2).
7. Tap Forgot password → the mail arrives → the link opens the app at `readynative://new-password` → enter a new password twice → "Password updated" and you land on Home. Sign out, sign in with the new password, sign out again and open the same link → "This link is invalid or has expired".
8. Kill and reopen the app → still signed in, session restored from storage.
9. Examples → Auth session → the JSON shows `status: "authenticated"`.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --auth none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/(auth)/_layout.tsx`, `src/app/(auth)/new-password.tsx`, `src/app/(auth)/reset.tsx`, `src/app/(auth)/sign-in.tsx`, `src/app/(auth)/sign-up.tsx`, `src/app/examples/auth.tsx`, `src/lib/__tests__/auth-supabase.test.tsx`, `src/screens/auth/auth-form.ts`, `src/screens/auth/new-password-screen.tsx`, `src/screens/auth/reset-screen.tsx`, `src/screens/auth/sign-in-screen.tsx`, `src/screens/auth/sign-up-screen.tsx`, `src/screens/examples/auth-example-screen.tsx`, `src/server/__tests__/session-supabase.test.ts`, `supabase/migrations/20260921000000_delete_user.sql`, `supabase/migrations/20260924000000_delete_user_storage.sql`.
2. **Replace, don't delete** `src/hooks/use-auth-redirect.ts`, `src/lib/auth.ts`, `src/server/session.ts`: core code imports them, so swap in the no-op version from `modules/auth/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @supabase/supabase-js expo-apple-authentication expo-auth-session expo-crypto`.
4. **Drop the config plugin** `expo-apple-authentication` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<AuthProvider>` and its import from `src/providers.tsx`.
6. **Remove the env keys** `EXPO_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_ANON_KEY` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_ANON_KEY` from `src/lib/env.ts`.
7. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
8. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/auth/supabase/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --auth supabase
</Cmd>

Module id: `auth/supabase` (the default for this category).

### Dependencies [#dependencies]

| Package                     | Version    | Kind                        |
| --------------------------- | ---------- | --------------------------- |
| `@supabase/supabase-js`     | `^2.116.0` | dependency                  |
| `expo-apple-authentication` | `~57.0.2`  | dependency (`expo install`) |
| `expo-auth-session`         | `~57.0.12` | dependency (`expo install`) |
| `expo-crypto`               | `~57.0.3`  | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-apple-authentication`

### Environment keys [#environment-keys]

| Key                             | Required | Server-only | Example                          | Docs                                                               |
| ------------------------------- | -------- | ----------- | -------------------------------- | ------------------------------------------------------------------ |
| `EXPO_PUBLIC_SUPABASE_URL`      | yes      | no          | `https://xyzcompany.supabase.co` | [dashboard](https://supabase.com/dashboard/project/_/settings/api) |
| `EXPO_PUBLIC_SUPABASE_ANON_KEY` | yes      | no          | `sb_publishable_...`             | [dashboard](https://supabase.com/dashboard/project/_/settings/api) |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects &#x2A;Email address, name (account)*, *Auth tokens*, &#x2A;IP address (auth logs)*; shared with Supabase (processor). Source of truth: [vendor disclosure](https://supabase.com/privacy).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type           | Linked to user | Tracking | Purposes         |
| -------------- | -------------- | -------- | ---------------- |
| `EmailAddress` | yes            | no       | AppFunctionality |
| `Name`         | yes            | no       | AppFunctionality |
| `UserID`       | yes            | no       | AppFunctionality |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider       | From         |
| ----- | -------------- | ------------ |
| 30    | `AuthProvider` | `@/lib/auth` |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_ANON_KEY`

### After setup [#after-setup]

1. Supabase: create a project, copy Project URL + anon/publishable key from Settings → API into .env (EXPO\_PUBLIC\_SUPABASE\_URL, EXPO\_PUBLIC\_SUPABASE\_ANON\_KEY).
2. Supabase: run supabase/migrations/20260921000000\_delete\_user.sql (SQL editor or `supabase db push`) - the Settings → Delete account row calls rpc('delete\_user').
3. Supabase: Authentication → URL Configuration → add `readynative://` and `readynative://new-password` (your scheme) to Redirect URLs - Google sign-in and the password-reset link return through them.
4. Supabase: Authentication → Providers → Apple: enable, add the iOS bundle id to Client IDs (native Sign in with Apple).
5. Supabase: Authentication → Providers → Google: enable with a Web OAuth client id/secret from Google Cloud Console.
6. Apple: enable the Sign in with Apple capability for the bundle id (EAS does it on the first build).

### Files [#files]

<details>
  <summary>
    19 files copied to the project root
  </summary>

  * `src/app/(auth)/_layout.tsx`
  * `src/app/(auth)/new-password.tsx`
  * `src/app/(auth)/reset.tsx`
  * `src/app/(auth)/sign-in.tsx`
  * `src/app/(auth)/sign-up.tsx`
  * `src/app/examples/auth.tsx`
  * `src/hooks/use-auth-redirect.ts`
  * `src/lib/__tests__/auth-supabase.test.tsx`
  * `src/lib/auth.ts`
  * `src/screens/auth/auth-form.ts`
  * `src/screens/auth/new-password-screen.tsx`
  * `src/screens/auth/reset-screen.tsx`
  * `src/screens/auth/sign-in-screen.tsx`
  * `src/screens/auth/sign-up-screen.tsx`
  * `src/screens/examples/auth-example-screen.tsx`
  * `src/server/__tests__/session-supabase.test.ts`
  * `src/server/session.ts`
  * `supabase/migrations/20260921000000_delete_user.sql`
  * `supabase/migrations/20260924000000_delete_user_storage.sql`
</details>


# API routes (/docs/features/backend/api-routes)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/backend/api-routes - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="backend" option="api-routes" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This turns on Expo Router's server routes so your app has a backend in the same tree: `src/app/api/health+api.ts` answers `GET /api/health` with `{ ok, version, variant }`, `src/app/api/echo+api.ts` answers `POST /api/echo { message }` with zod validation and a 400 on bad input, and `src/server/` holds the pieces you'll reuse - `json.ts` (`json()`, `error()`, `readJson(request, schema)`, `handle()` which maps BadRequest to 4xx and anything else to 500 without leaking a stack), `env.ts` (`serverEnv()`, zod over `process.env` for keys that must never be `EXPO_PUBLIC_`), and `webhooks/README.md` with the handler pattern. If you set up with `--with-examples` there's an example at `/examples/api`. Pick this when a module needs a server - `auth/better-auth` requires it and `payments/stripe` wants it - or when you'd rather not stand up a separate backend yet.

## Setup [#setup]

```bash
bun run setup --backend api-routes
```

1. The module patches the app config with `web.output: "server"`, which is what makes API routes build. Your native export is unaffected, but the static web export is gone while this module is selected.
2. Run `bun run start`. The dev server serves `src/app/api/**` at `http://localhost:8081/api/*` - check it with `curl -s http://localhost:8081/api/health`, which returns `{"ok":true,...}`.
3. Set `EXPO_PUBLIC_API_URL` in `.env` to `http://<your-lan-ip>:8081` and restart with `bun run start -- -c`. A physical device can't reach `localhost`, and the example screen shows an EmptyState while the key is unset.
4. Add any server-only key to `.env` under the `# server (never EXPO_PUBLIC)` heading. The shipped one is `WEBHOOK_SECRET` (any random string), read through `serverEnv().WEBHOOK_SECRET`.
5. Deploy when you're ready: `bunx eas-cli login && bunx eas-cli init` (it prints the project id - paste it into `readynative.config.ts` → `app.easProjectId`), then `npx expo export -p web` and `eas deploy` - add `--prod` for the production alias. The guide is at [https://docs.expo.dev/eas/hosting/get-started/](https://docs.expo.dev/eas/hosting/get-started/).
6. Write custom webhooks against the pattern in `src/server/webhooks/README.md`: verify the secret, parse with zod, and return 2xx only once you've actually handled it. The auth (`/api/auth/[...all]`) and payments handlers ship with their own modules.

<Callout type="info" title="Going to production?">
  Set the server keys in EAS rather than `.env`: `eas env:set --environment production --name WEBHOOK_SECRET --value … --visibility sensitive`, and deploy with `eas deploy --environment production` so the routes see them (EAS Hosting can't deploy `secret` variables). Point `EXPO_PUBLIC_API_URL` at `https://<project>.expo.app` per build profile in `eas.json` `env`, and optionally set `expo.extra.router.origin` so relative `fetch("/api/…")` calls resolve ([https://docs.expo.dev/router/reference/api-routes/#deployment](https://docs.expo.dev/router/reference/api-routes/#deployment)). A native release build has no API routes without a deployed server.
</Callout>

7. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                                         | Where                                                  | Get it                                                                                      |
| ------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL`                       | client (`env.API_URL`); shared with the data modules   | `http://<lan-ip>:8081` while `expo start` runs, else the hosted URL                         |
| `WEBHOOK_SECRET`                            | server only (`serverEnv().WEBHOOK_SECRET`), `.env`/EAS | any random string; also `eas env:set --environment production --visibility sensitive`       |
| `POSTHOG_PERSONAL_API_KEY`                  | server only, optional                                  | PostHog → Settings → Personal API keys, scope `person:write`; used by `/api/privacy/delete` |
| `POSTHOG_PROJECT_ID`                        | server only, optional                                  | PostHog → Project settings → Project ID                                                     |
| `POSTHOG_API_HOST`                          | server only, optional                                  | default `https://us.posthog.com`; `https://eu.posthog.com` for EU projects                  |
| `AMPLITUDE_API_KEY`, `AMPLITUDE_SECRET_KEY` | server only, optional                                  | Amplitude → Settings → Projects → your project → API key and Secret key                     |
| `AMPLITUDE_REGION`                          | server only, optional                                  | `eu` for EU-hosted projects; US otherwise                                                   |
| `REVENUECAT_SECRET_KEY`                     | server only, optional                                  | RevenueCat → Project settings → API keys → secret key                                       |
| `CLERK_WEBHOOK_SIGNING_SECRET`              | server only, optional                                  | Clerk → Webhooks → your `/api/webhooks/clerk` endpoint → Signing secret (`whsec_…`)         |

Server keys are listed in `.env.example` under `# server (never EXPO_PUBLIC)`; `bun run doctor` checks the ones a module marks `required`. Expo Go works, since the routes run on the dev server or EAS Hosting, not on the device.

## Usage [#usage]

Write a route as a `+api.ts` file, using the shared helpers:

```ts
// src/app/api/greet+api.ts
import { z } from "zod";
import { handle, json, readJson } from "@/server/json";

const Body = z.object({ name: z.string().min(1) });

export const POST = handle(async (request) => {
  const { name } = await readJson(request, Body);
  return json({ greeting: `Hi ${name}` });
});
```

Read a server-only key - never `process.env` directly, and never from client code:

```ts
import { serverEnv } from "@/server/env";

const secret = serverEnv().WEBHOOK_SECRET;
```

Call it from the app against the configured origin:

```ts
import { env } from "@/lib/env";

const res = await fetch(`${env.API_URL}/api/health`);
```

### Account deletion [#account-deletion]

`POST /api/privacy/delete` authenticates the caller with `serverAuth.getRequestUser` (401 signed out, 503 when server auth isn't configured) and erases the verified user id in every service whose server keys are set:

* PostHog: `POST {POSTHOG_API_HOST}/api/projects/{POSTHOG_PROJECT_ID}/persons/bulk_delete/` with `POSTHOG_PERSONAL_API_KEY`, `distinct_ids`, `delete_events: true` and `delete_recordings: true`.
* Amplitude: the User Privacy API v1, `POST https://amplitude.com/api/2/deletions/users` (`https://analytics.eu.amplitude.com` with `AMPLITUDE_REGION=eu`), Basic auth `AMPLITUDE_API_KEY:AMPLITUDE_SECRET_KEY`, `user_ids` and `ignore_invalid_id: true`.
* RevenueCat: `DELETE https://api.revenuecat.com/v1/subscribers/{app_user_id}` with `REVENUECAT_SECRET_KEY`; a 404 counts as deleted.

It answers 200 `{ results }` when every service succeeded and 502 when one failed - the app then keeps the account so the user can retry. Settings calls `deleteServerData()` from `@/lib/account-data` (a POST to `${EXPO_PUBLIC_API_URL}/api/privacy/delete` with `auth.getAuthHeaders()`) right before `auth.deleteAccount()`; with `backend=none` it's a no-op. PostHog and Amplitude can only find the user if the app called `analytics.identify(session.user.id)`; RevenueCat's app user id is already the auth user id.

With Clerk, `POST /api/webhooks/clerk` handles `user.deleted` the same way. It verifies the Svix / Standard Webhooks signature with WebCrypto (no SDK, `src/server/standard-webhooks.ts`) against `CLERK_WEBHOOK_SIGNING_SECRET` with a 5-minute timestamp tolerance, and answers 404 while the secret is unset.

## Gotchas [#gotchas]

* `web.output: "server"` makes `npx expo export -p web` produce a server bundle for EAS Hosting or Node, so the static web export is gone while this module is selected.
* API routes aren't available in a native release build without a deployed server - point `EXPO_PUBLIC_API_URL` at EAS Hosting before you ship.
* `EXPO_PUBLIC_API_URL` is shared with the data and auth modules; when several are selected, the first one's example value wins in `.env.example`.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Run `bun run start`, then `curl -s localhost:8081/api/health` → `{"ok":true,"version":"1.0.0","variant":"dev"}`.
2. `curl -s -X POST localhost:8081/api/echo -H 'content-type: application/json' -d '{"message":"hi"}'` echoes it back; sending `{}` gives a 400 with `{ error }`.
3. Set `EXPO_PUBLIC_API_URL` to the LAN URL and open Examples → "API route" on a device: it shows `ok · version · variant`. Unset it and you get the EmptyState.
4. After `eas deploy`, repeat step 1 against `https://<project>.expo.app`.

## Remove it [#remove-it]

Remove [`auth/better-auth`](https://readynative.app/docs/features/auth/better-auth) and [`payments/stripe`](https://readynative.app/docs/features/payments/stripe) first if you use it - it requires this module.

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --backend none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/api/echo+api.ts`, `src/app/api/health+api.ts`, `src/app/api/privacy/delete+api.ts`, `src/app/api/webhooks/clerk+api.ts`, `src/app/examples/api.tsx`, `src/screens/examples/api-example-screen.tsx`, `src/server/__tests__/privacy.test.ts`, `src/server/__tests__/routes.test.ts`, `src/server/env.ts`, `src/server/json.ts`, `src/server/privacy.ts`, `src/server/standard-webhooks.ts`, `src/server/webhooks/README.md`.
2. **Replace, don't delete** `src/lib/account-data.ts`: core code imports it, so swap in the no-op version from `modules/backend/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Remove the env keys** `EXPO_PUBLIC_API_URL`, `WEBHOOK_SECRET`, `POSTHOG_PERSONAL_API_KEY`, `POSTHOG_PROJECT_ID`, `POSTHOG_API_HOST`, `AMPLITUDE_API_KEY`, `AMPLITUDE_SECRET_KEY`, `AMPLITUDE_REGION`, `REVENUECAT_SECRET_KEY`, `CLERK_WEBHOOK_SIGNING_SECRET` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_API_URL` from `src/lib/env.ts`.
4. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/backend/api-routes/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --backend api-routes
</Cmd>

Module id: `backend/api-routes` (the default for this category).

### Environment keys [#environment-keys]

| Key                            | Required | Server-only | Example                                           | Docs                                                                      |
| ------------------------------ | -------- | ----------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL`          | no       | no          | `http://localhost:8081`                           | [dashboard](https://docs.expo.dev/router/reference/api-routes/)           |
| `WEBHOOK_SECRET`               | no       | yes         | `change-me`                                       | [dashboard](https://docs.expo.dev/router/reference/api-routes/#security)  |
| `POSTHOG_PERSONAL_API_KEY`     | no       | yes         | `phx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` | [dashboard](https://posthog.com/docs/api#private-endpoint-authentication) |
| `POSTHOG_PROJECT_ID`           | no       | yes         | `12345`                                           | [dashboard](https://app.posthog.com/settings/project)                     |
| `POSTHOG_API_HOST`             | no       | yes         | `https://us.posthog.com`                          | [dashboard](https://posthog.com/docs/api)                                 |
| `AMPLITUDE_API_KEY`            | no       | yes         | -                                                 | [dashboard](https://amplitude.com/docs/apis/analytics/user-privacy)       |
| `AMPLITUDE_SECRET_KEY`         | no       | yes         | -                                                 | [dashboard](https://amplitude.com/docs/apis/analytics/user-privacy)       |
| `AMPLITUDE_REGION`             | no       | yes         | `us`                                              | [dashboard](https://amplitude.com/docs/apis/analytics/user-privacy)       |
| `REVENUECAT_SECRET_KEY`        | no       | yes         | `sk_xxxxxxxxxxxxxxxxxxxxxxxx`                     | [dashboard](https://www.revenuecat.com/docs/api-v1/customers)             |
| `CLERK_WEBHOOK_SIGNING_SECRET` | no       | yes         | `whsec_xxxxxxxxxxxxxxxxxxxxxxxx`                  | [dashboard](https://clerk.com/docs/webhooks/sync-data)                    |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_API_URL`

### After setup [#after-setup]

1. API routes: `expo start` serves src/app/api/\*\* on the dev server; set EXPO\_PUBLIC\_API\_URL=http\://\<lan-ip>:8081 in .env for a device
2. Deploy: `npx eas-cli login`, `eas init`, then `npx expo export -p web && eas deploy` (EAS Hosting) and point EXPO\_PUBLIC\_API\_URL at the hosted URL
3. Server secrets (WEBHOOK\_SECRET, …) live in .env locally and in `eas env:set --environment production --visibility sensitive` for EAS Hosting - never EXPO\_PUBLIC\_
4. Account deletion: Settings → Delete account first calls POST /api/privacy/delete, which erases the user in PostHog / Amplitude / RevenueCat when their server keys are set (POSTHOG\_PERSONAL\_API\_KEY + POSTHOG\_PROJECT\_ID, AMPLITUDE\_API\_KEY + AMPLITUDE\_SECRET\_KEY, REVENUECAT\_SECRET\_KEY). With Clerk, point a `user.deleted` webhook at /api/webhooks/clerk and set CLERK\_WEBHOOK\_SIGNING\_SECRET.

### Files [#files]

<details>
  <summary>
    14 files copied to the project root
  </summary>

  * `src/app/api/echo+api.ts`
  * `src/app/api/health+api.ts`
  * `src/app/api/privacy/delete+api.ts`
  * `src/app/api/webhooks/clerk+api.ts`
  * `src/app/examples/api.tsx`
  * `src/lib/account-data.ts`
  * `src/screens/examples/api-example-screen.tsx`
  * `src/server/__tests__/privacy.test.ts`
  * `src/server/__tests__/routes.test.ts`
  * `src/server/env.ts`
  * `src/server/json.ts`
  * `src/server/privacy.ts`
  * `src/server/standard-webhooks.ts`
  * `src/server/webhooks/README.md`
</details>


# Backend (/docs/features/backend)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/backend/README.md - do not edit. */}

<Badge>
  Pro
</Badge>

Hey - here's how the backend category works in ReadyNative.

This one is about whether your app ships a server of its own. With Expo Router, a `+api.ts` file under `src/app/api/` is a route handler that runs on the dev server in development and on EAS Hosting in production - same repo, same TypeScript, one deploy.

Unlike the other categories there's no `@/lib/backend` shim, because there's no client API to keep stable. What stays constant is `EXPO_PUBLIC_API_URL`: the origin your app calls, whether that's routes in this tree or a backend you run elsewhere. `backend/none` is the no-op - it just means no routes here.

Pick **API routes** when a module needs a server (`auth/better-auth` requires it, `payments/stripe` wants it for Checkout and webhooks) or when you'd rather write one endpoint than stand up a separate service. Pick **none** when your backend already exists somewhere else, or when the app doesn't need one - it also keeps the static web export, which API routes replace with a server bundle.

This category is part of ReadyNative Pro.

## Options [#options]

One option per category - `--backend <option>` picks it:

<Cmd>
  bun run setup --backend api-routes
</Cmd>

| Option                       | Label                | Expo Go | Hint                                                                       |
| ---------------------------- | -------------------- | ------- | -------------------------------------------------------------------------- |
| [`api-routes`](./api-routes) | API routes (default) | yes     | Expo Router +api.ts routes · src/server helpers · EAS Hosting · Expo Go OK |
| [`none`](./none)             | No API routes        | yes     | no src/app/api                                                             |


# No API routes (/docs/features/backend/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/backend/none - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="backend" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-backend option: no `src/app/api/*+api.ts` routes, no `src/server/` helpers, and `web.output` stays as it is, so `npx expo export -p web` still produces a static site. Pick this when the app talks to a backend you already run somewhere else, or when it doesn't need a server at all.

## Setup [#setup]

```bash
bun run setup --backend none
```

There's nothing to configure. If you're calling an API you host elsewhere, set `EXPO_PUBLIC_API_URL` in `.env` to its origin and use it from `@/lib/env` - the data modules read the same key.

When you want routes in this tree, switch with `bun run setup --backend api-routes`.

## Usage [#usage]

Fetch from wherever your backend lives:

```ts
import { env } from "@/lib/env";

const res = await fetch(`${env.API_URL}/health`);
```

## Gotchas [#gotchas]

* `auth/better-auth` requires `backend/api-routes`, so `bun run setup` won't let you pair it with this option. `payments/stripe` only wants it: its routes are then never served and the paywall shows "Configure Stripe".
* Nothing here needs a dev build; Expo Go is fine.

## Reference [#reference]

Everything below is generated from `modules/backend/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --backend none
</Cmd>

Module id: `backend/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/account-data.ts`
</details>


# Consent sheet (GDPR / CCPA) (/docs/features/consent/consent)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/consent/consent - do not edit. */}

<OptionBanner cat="consent" option="consent" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This asks before anything is sent: `src/lib/consent.ts` implements the `@/lib/consent` contract on top of the core consent store, and `ConsentProvider` (order 85, in `src/components/consent-sheet.tsx`) mounts the sheet above the app. The `analytics/*` and `crash/*` modules follow the consent store from import time on and only create their SDK clients once the matching category is consented to, so PostHog, Amplitude and Sentry send nothing - no events, no flags request, no crash report - until the user says yes where the law wants that. Setup picks this option automatically whenever an analytics or crash module is selected (and `none` when neither is); pass `--consent` to override.

## Setup [#setup]

```bash
bun run setup --consent consent
```

Setup installs `expo-localization` (for the device region), registers `ConsentProvider`, and adds the sheet and its tests. The only knob is in `readynative.config.ts`:

```ts
privacy: { askEverywhere: false }, // true: ask every user, whatever the region
```

## How it decides [#how-it-decides]

| Device                                                                                                                                              | Undecided reads as | Sheet                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------- |
| Any locale region (region setting or language region) in the EU/EEA, UK, Switzerland, Canada or Brazil, a `Europe/*` time zone, or no region at all | `false`            | shown once, after onboarding           |
| Anywhere else (California included)                                                                                                                 | `true`             | never; Settings → Privacy has switches |
| `privacy.askEverywhere: true`                                                                                                                       | `false`            | shown to everyone                      |

`CA` is Canada - a device cannot tell US states apart, so California users get the CCPA opt-out ("Do not sell or share", below) rather than a sheet.

`consent.needsPrompt()` is true when the stored record is not for the current `CONSENT_VERSION` (`src/stores/consent.ts`) and the device is in the ask group. Once the sheet is dismissed (any way - "Only necessary" is the default for Android back / swipe down) the record is written and it does not show again. **Raise `CONSENT_VERSION` when the sheet asks for something new**: every user in the ask group is asked again, and until they answer their old choices read as undecided.

The record persists under `readynative:consent` and survives sign-out (`wipeLocalData()` keeps it):

```ts
interface ConsentState {
  analytics: boolean | null; // null = undecided
  crash: boolean | null;
  doNotSell: boolean;
  version: number | null; // CONSENT_VERSION the answer was given to
  decidedAt: string | null; // ISO dates
  updatedAt: string | null;
  source: "sheet" | "settings" | "do-not-sell" | "legacy" | null;
}
```

The sheet and the Settings switches only show the categories this build has (`privacyCategories` in `src/lib/privacy-categories.ts`: `analytics` when an analytics module is selected, `crash` when a crash module is). With neither, the sheet never opens.

## Usage [#usage]

```ts
import { consent } from "@/lib/consent";

if (consent.get().analytics) analytics.track("paywall_seen");

const { crash } = consent.useConsent(); // reactive, inside a component
consent.set({ analytics: false }); // what the Settings switches do
consent.setDoNotSell(true); // the CCPA switch: analytics reads as off while it is on
```

`consent.reprompt()` shows the sheet now, whatever the region and the stored answer, until it's answered; Settings → Developer tools uses it.

Adding a category (say `marketing`): add it to `ConsentCategory` and `ConsentState` in `src/stores/consent.ts`, a row in `consent-sheet.tsx` and Settings, include it in `privacyCategories`, and read it where you need it.

## Gotchas [#gotchas]

* The sheet waits 400 ms after the first screen so `useOnboardingRedirect` can win; on the `onboarding` route it never opens. `ConsentProvider` loads the onboarding store itself, so with `onboarding/off` the sheet opens on the first screen.
* Region comes from the device (locales and time zone), not IP. A French user with a US region and a US time zone sees no sheet; the Settings switches are always there. Set `privacy.askEverywhere` if that trade-off is not good enough for you.
* With AsyncStorage the consent store loads asynchronously, so events fired before it has loaded (the first screen view) are dropped rather than sent without a known answer. kv-store and MMKV load it synchronously.
* This is a consent *mechanism*, not legal advice: your privacy policy still has to say what you collect (see `bun run gen:privacy`).

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --consent none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there: `src/components/__tests__/consent-sheet.test.tsx`, `src/components/consent-sheet.tsx`, `src/lib/__tests__/consent.test.ts`.
2. **Replace, don't delete** `src/lib/consent.ts`: core code imports it, so swap in the no-op version from `modules/consent/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove expo-localization`. Keep any of `expo-localization` (also used by `i18n/i18next`, `i18n/lingui`, `analytics/posthog`) that another module you picked still needs.
4. **Drop the config plugin** `expo-localization` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<ConsentProvider>` and its import from `src/providers.tsx`.
6. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/consent/consent/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --consent consent
</Cmd>

Module id: `consent/consent` (the default for this category).

### Dependencies [#dependencies]

| Package             | Version   | Kind                        |
| ------------------- | --------- | --------------------------- |
| `expo-localization` | `~57.0.2` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-localization`

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider          | From                         |
| ----- | ----------------- | ---------------------------- |
| 85    | `ConsentProvider` | `@/components/consent-sheet` |

### After setup [#after-setup]

1. Consent: test it - set the simulator region to Germany (Settings → General → Language & Region) and relaunch: the sheet appears after onboarding. Set region and time zone to the US: no sheet, and the Settings → Privacy toggles are on. `privacy.askEverywhere: true` in readynative.config.ts asks everyone.
2. Consent: the sheet text is yours to edit in src/components/consent-sheet.tsx; keep 'Only necessary' as easy to reach as 'Accept all' (that is what regulators check).

### Files [#files]

<details>
  <summary>
    4 files copied to the project root
  </summary>

  * `src/components/__tests__/consent-sheet.test.tsx`
  * `src/components/consent-sheet.tsx`
  * `src/lib/__tests__/consent.test.ts`
  * `src/lib/consent.ts`
</details>


# Privacy consent (/docs/features/consent)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/consent/README.md - do not edit. */}

Hey - here's how privacy consent works in ReadyNative. This category is a yes/no: does a consent
sheet ask before analytics and crash reporting start?

What stays the same either way: the consent store (`src/stores/consent.ts`, key
`readynative:consent`), the `@/lib/consent` contract (`consent.get() / useConsent() / set() /
setDoNotSell()`), and the Settings Privacy card ("Export my data", and "Do not sell or share"
whenever an analytics module is selected) are core. The analytics and crash modules follow the
consent store and only create their SDK clients once their category is consented to, so the SDK
files are identical under both options. Setup picks the option for you - `consent` when an
analytics or crash module is selected, `none` otherwise - and `bun run setup --consent <option>`
overrides it.

* **consent** - a sheet after onboarding wherever a device locale region or the time zone points
  to the EU/EEA, UK, Switzerland, Canada or Brazil (and wherever the device has no region; or
  everywhere with `privacy.askEverywhere`): one switch per category the build has, "Accept all" or
  "Only necessary". SDKs stay off there until answered; elsewhere they start on and the Settings
  switches turn them off. Needs `expo-localization` (installed by the module).
* **none** - nothing asks; undecided reads as consented, "Do not sell or share" still turns
  analytics off. Right when you ship no analytics or crash module (the default preset).

## Options [#options]

One option per category - `--consent <option>` picks it:

<Cmd>
  bun run setup --consent consent
</Cmd>

| Option                 | Label                                 | Expo Go | Hint                                                                                                                       |
| ---------------------- | ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| [`consent`](./consent) | Consent sheet (GDPR / CCPA) (default) | yes     | asks before analytics + crash start (EU/EEA, UK, Switzerland, Canada, Brazil or everywhere); Settings toggles · Expo Go OK |
| [`none`](./none)       | No consent sheet                      | yes     | consent.get() reads all-true; analytics and crash SDKs start as before                                                     |


# No consent sheet (/docs/features/consent/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/consent/none - do not edit. */}

<OptionBanner cat="consent" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Nothing asks the user anything: `src/lib/consent.ts` is a re-export of the core shim, so an undecided category reads as consented and the analytics / crash SDKs start on the first launch. What the user did say still counts: the Settings "Do not sell or share" switch (shown when an analytics module is selected) turns analytics off, and an explicit `false` in the consent store (`src/stores/consent.ts`) is honoured - a later `bun run setup --consent consent` keeps both. Setup picks this option when no analytics or crash module is selected; pick it by hand (`--consent none`) only when your app never ships to a region with consent rules.

## Setup [#setup]

```bash
bun run setup --consent none
```

That's it - there's nothing to configure.

## Usage [#usage]

```ts
import { consent } from "@/lib/consent";

consent.get(); // { analytics: true, crash: true } until "Do not sell or share" is on
consent.setDoNotSell(true); // → { analytics: false, crash: true }
consent.needsPrompt(); // always false
```

## Gotchas [#gotchas]

* With `analytics/*` or `crash/sentry` selected, this option means events flow from the first launch and there are no per-category switches in Settings (only "Do not sell or share", which covers analytics). In the EU/UK that needs a consent mechanism of your own; `consent/consent` ships one, and setup selects it for you unless you pass `--consent none`.

## Reference [#reference]

Everything below is generated from `modules/consent/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --consent none
</Cmd>

Module id: `consent/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/consent.ts`
</details>


# Crash reporting (/docs/features/crash)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/crash/README.md - do not edit. */}

<Badge>
  Pro
</Badge>

Hey - here's how crash reporting works in ReadyNative.

This category owns the errors you didn't see coming: the one call you make for handled errors, and the app-wide boundary that keeps a render error from turning into a white screen.

`@/lib/crash` always exists, whichever option you pick: `crash.capture(err, ctx)` reads the same in both, and `crash/none` is a no-op that only logs in dev. Calls you write against the shim keep working when you switch options, and a missing DSN never crashes the app - it just means nothing is sent.

Pick **Sentry** for the reports: JS and native crashes, breadcrumbs, source-mapped stack traces, and an error boundary whose fallback is the app's own ErrorState with Retry. Pick **none** while you're building alone and nobody else can hit a bug you can't reproduce - it's one command to switch later, and the calls you already wrote keep compiling.

This category is part of ReadyNative Pro.

## Options [#options]

One option per category - `--crash <option>` picks it:

<Cmd>
  bun run setup --crash sentry
</Cmd>

| Option               | Label              | Expo Go | Hint                                                      |
| -------------------- | ------------------ | ------- | --------------------------------------------------------- |
| [`sentry`](./sentry) | Sentry (default)   | yes     | JS + native crash reporting · Expo Go OK (JS errors only) |
| [`none`](./none)     | No crash reporting | yes     | crash.capture is a no-op                                  |


# No crash reporting (/docs/features/crash/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/crash/none - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="crash" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-op crash option: no SDK, no DSN, nothing leaving the device. It owns `src/lib/crash.ts` as a re-export of the core shim, so `@/lib/crash` keeps the same API whichever option you pick - `crash.capture(err, ctx)` does nothing beyond a `console.error` in dev. Pick this while you're building alone; pick Sentry before real users can hit a bug you can't reproduce.

## Setup [#setup]

```bash
bun run setup --crash none
```

There's nothing to configure and no keys to paste.

When you want the reports, switch with `bun run setup --crash sentry`.

## Usage [#usage]

The call exists and is safe to write today, so screens don't need rewriting when you switch:

```ts
import { crash } from "@/lib/crash";

crash.capture(err, { screen: "checkout", orderId }); // logs in dev, no-op otherwise
```

## Gotchas [#gotchas]

* The shim has no `CrashBoundary`, so don't import one - that component comes with `crash/sentry`. An unhandled render error takes down the tree it's in.
* Nothing here needs a dev build; Expo Go is fine.

## Reference [#reference]

Everything below is generated from `modules/crash/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --crash none
</Cmd>

Module id: `crash/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/crash.ts`
</details>


# Sentry (/docs/features/crash/sentry)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/crash/sentry - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="crash" option="sentry" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This reports crashes and handled errors to Sentry: `src/lib/crash.ts` calls `Sentry.init` once crash consent is given (only when the DSN is set, with `environment` from `APP_VARIANT`, errors only, no traces), `crash.capture(err, ctx)` maps to `captureException` with `ctx` as `extra`, and `CrashBoundary` is a `Sentry.ErrorBoundary` whose fallback is the kit's `ErrorState` with Retry. `CrashProvider` (order 40) mounts that boundary app-wide, with its own ThemeProvider since it sits above the ui provider. If you set up with `--with-examples` there's an example at `/examples/crash` and tests for both the capture path and the boundary. `@/lib/crash` keeps the same API whichever option you pick - Sentry is the one service option here, and it's what you want the moment real users can hit a bug you can't reproduce.

## Setup [#setup]

```bash
bun run setup --crash sentry
```

1. Create a project at [sentry.io](https://sentry.io) (platform: React Native), then open \[Settings] → \[Projects] → your project → \[Client Keys (DSN)] and copy the DSN into `.env` as `EXPO_PUBLIC_SENTRY_DSN`. It's public and safe in the client. Without it the SDK isn't initialised, `crash.capture` only logs in dev, and the example shows "Configure EXPO\_PUBLIC\_SENTRY\_DSN".
2. Take the org and project slugs from the project URL and set them as the build-time secrets `SENTRY_ORG` and `SENTRY_PROJECT` - never with an `EXPO_PUBLIC_` prefix.
3. Create a token at \[Settings] → \[Auth Tokens] with the scopes `project:releases` and `org:read`, and set it as `SENTRY_AUTH_TOKEN`. These three are only used at build time, to upload source maps.
4. If you install with bun, run `bun pm trust @sentry/cli` once on an existing tree. bun blocks lifecycle scripts by default and `@sentry/cli` downloads its binary in `postinstall`; without it, source-map uploads fail. The module adds `trustedDependencies: ["@sentry/cli"]` to `package.json`, so a fresh `bun install` handles it for you.
5. The config plugin `["@sentry/react-native", { organization: "", project: "", url }]` is added to `.readynative.json` and applied by `app.config.ts`. The empty org and project make the plugin fall back to the `SENTRY_ORG` and `SENTRY_PROJECT` env vars at build time, so there's nothing to edit. (The plugin id is the package name, not `@sentry/react-native/expo`: same code, and `expo install` would otherwise try to add it to the dynamic config and fail.)

<Callout type="info" title="Going to production?">
  Put `SENTRY_ORG`, `SENTRY_PROJECT` and `SENTRY_AUTH_TOKEN` in EAS (`eas env:set --environment production --visibility sensitive`) so release builds and `eas update` can upload source maps - without them, stack traces stay minified. Use a separate Sentry project (or at least rely on the `environment` tag, which follows `APP_VARIANT`) so production issues aren't buried in your dev noise.
</Callout>

6. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                                                                                     | Where to get it                                                                                                                                                                                                        |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_SENTRY_DSN`                                                                | [https://sentry.io/settings/projects/](https://sentry.io/settings/projects/) → project → Client Keys (DSN). Public; safe in the client.                                                                                |
| `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_AUTH_TOKEN` (EAS secrets, never `EXPO_PUBLIC_`) | org/project slugs from the project URL; token from [https://sentry.io/settings/auth-tokens/](https://sentry.io/settings/auth-tokens/) (scopes `project:releases`, `org:read`). Build time only, for source-map upload. |

Dashboards: Issues at `https://sentry.io/organizations/<org>/issues/` · Releases (source maps) at `…/releases/` · [Client Keys](https://sentry.io/settings/projects/). Deps: `@sentry/react-native ~7.11.0` - the version Expo SDK 57 pins, so 8.x isn't an option until that pin moves (`npx expo install --fix` downgrades anything newer).

## Usage [#usage]

Report a handled error with context:

```ts
import { crash } from "@/lib/crash";

crash.capture(err, { screen: "checkout", orderId });
```

Wrap a risky subtree so a render error doesn't take the app down:

```tsx
import { CrashBoundary } from "@/lib/crash";

<CrashBoundary>{riskySubtree}</CrashBoundary>;
```

Tag the signed-in user, so issues say who hit them:

```ts
import * as Sentry from "@sentry/react-native";

Sentry.setUser({ id: user.id });
```

## Consent and PII [#consent-and-pii]

`Sentry.init` runs only once `consent.get().crash` is true (and the DSN is set). Until then no JS or native crash report, session or client report leaves the device - native crash files from a previous run wait for the next init. Withdrawing consent calls `Sentry.close()`; consent again runs a new `Sentry.init`. `beforeSend` / `beforeSendTransaction` still return `null` while crash consent is false, and `crash.capture` is a no-op then. With `consent/consent` that is the EU/EEA, UK, CH, CA, BR until the sheet is answered; the Settings → Privacy toggle takes effect live. `isCrashConfigured` only means the DSN is set; `isCrashRunning()` tells you whether the SDK is initialised.

Everything that does go out passes `scrubEvent()`: `user.ip_address`, `user.email`, `user.username`, `request.headers`, `request.cookies`, `request.query_string` and `request.data` are dropped, the query string is stripped from `request.url`, and emails (`[email]`), JWTs, `Bearer …` tokens and `token=` / `password=` / `api_key=` / `secret=` values are masked in the message, `logentry`, exception values, `extra` (secret-named keys become `[redacted]`) and breadcrumbs. `beforeBreadcrumb` (`scrubBreadcrumb`) strips query strings and fragments from `data.url`, `data.from` and `data.to` on http and navigation breadcrumbs. `user.id` stays so you can count affected users. `sendDefaultPii` is off. `ctx` is scrubbed too, but still keep `crash.capture(err, ctx)` contexts free of personal data.

In Sentry, turn on \[Project Settings] → \[Security & Privacy] → "Prevent Storing of IP Addresses": the connection still reveals the device IP to Sentry, which also derives geo data from it.

## Gotchas [#gotchas]

* There's no Metro plugin (`withSentryConfig` in `metro.config.js`, which the ui module owns), so JS bundles carry no Sentry Debug IDs and uploads match by release and dist instead. Run `npx sentry-expo-upload-sourcemaps dist` after `eas update`; EAS native builds upload through the plugin's gradle and xcode scripts. Add the Metro plugin yourself if you want Debug IDs.
* `Sentry.wrap(RootLayout)` - touch breadcrumbs and the profiler - isn't applied, because core owns `_layout.tsx`. Wrap it there if you want them.
* `bun run setup --crash none` removes everything; with `--with-examples`, `/examples/crash` then shows "Module not installed".
* Expo Go covers JS errors, breadcrumbs and the boundary. Native crashes, offline caching and `Sentry.nativeCrash()` need a dev build.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Put a real `EXPO_PUBLIC_SENTRY_DSN` in `.env`, run `bun run start -- -c`, and open the app on a device (Expo Go is fine for JS errors).
2. Examples → "Crash reporting" → **Capture test error**: Issues shows `Error: Test error from /examples/crash` with `extra.source = examples/crash` within about a minute, environment `dev`.
3. Tap **Throw render error**: the card shows "Something went wrong · Render error from /examples/crash" with Retry, the rest of the screen still works, and a second issue appears with `mechanism: react-error-boundary`. Tap **Disarm**, then **Retry**, and "Renders fine until you throw." is back.
4. On a dev build only, add `Sentry.nativeCrash()` to a button and relaunch: a native crash issue appears (symbolication needs `SENTRY_AUTH_TOKEN`).
5. Remove the DSN and restart: the example shows "Configure EXPO\_PUBLIC\_SENTRY\_DSN" and the app still boots.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --crash none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/crash.tsx`, `src/lib/__tests__/crash-boundary.test.tsx`, `src/lib/__tests__/crash-sentry.test.ts`, `src/screens/examples/crash-example-screen.tsx`.
2. **Replace, don't delete** `src/lib/crash.ts`: core code imports it, so swap in the no-op version from `modules/crash/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @sentry/react-native`.
4. **Drop the config plugin** `@sentry/react-native` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<CrashProvider>` and its import from `src/providers.tsx`.
6. **Remove the env keys** `EXPO_PUBLIC_SENTRY_DSN` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_SENTRY_DSN` from `src/lib/env.ts`.
7. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
8. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/crash/sentry/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --crash sentry
</Cmd>

Module id: `crash/sentry` (the default for this category).

### Dependencies [#dependencies]

| Package                | Version   | Kind                        |
| ---------------------- | --------- | --------------------------- |
| `@sentry/react-native` | `~7.11.0` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `@sentry/react-native` (with options)

### Environment keys [#environment-keys]

| Key                      | Required | Server-only | Example                                          | Docs                                              |
| ------------------------ | -------- | ----------- | ------------------------------------------------ | ------------------------------------------------- |
| `EXPO_PUBLIC_SENTRY_DSN` | yes      | no          | `https://examplePublicKey@o0.ingest.sentry.io/0` | [dashboard](https://sentry.io/settings/projects/) |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects *Crash logs*, &#x2A;Diagnostics (performance)*, *Device info*; shared with Sentry (processor). Source of truth: [vendor disclosure](https://docs.sentry.io/security-legal-pii/security/mobile-privacy/).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type                  | Linked to user | Tracking | Purposes         |
| --------------------- | -------------- | -------- | ---------------- |
| `CrashData`           | no             | no       | AppFunctionality |
| `PerformanceData`     | no             | no       | AppFunctionality |
| `OtherDiagnosticData` | no             | no       | AppFunctionality |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider        | From          |
| ----- | --------------- | ------------- |
| 40    | `CrashProvider` | `@/lib/crash` |

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_SENTRY_DSN`

### After setup [#after-setup]

1. Sentry: create a React Native project at [https://sentry.io](https://sentry.io), copy its DSN (Settings > Projects > \<project> > Client Keys) into EXPO\_PUBLIC\_SENTRY\_DSN.
2. Sentry: for source maps set EAS secrets SENTRY\_ORG, SENTRY\_PROJECT and SENTRY\_AUTH\_TOKEN ([https://sentry.io/settings/auth-tokens/](https://sentry.io/settings/auth-tokens/), scopes project:releases + org:read); the config plugin uploads on native builds, `npx sentry-expo-upload-sourcemaps dist` after `eas update`.
3. Sentry: call `crash.capture(new Error("test"))` from any screen (or Examples > Crash reporting with `--with-examples`) → the issue appears under Issues within a minute.

### Files [#files]

<details>
  <summary>
    5 files copied to the project root
  </summary>

  * `src/app/examples/crash.tsx`
  * `src/lib/__tests__/crash-boundary.test.tsx`
  * `src/lib/__tests__/crash-sentry.test.ts`
  * `src/lib/crash.ts`
  * `src/screens/examples/crash-example-screen.tsx`
</details>


# Apollo Client (/docs/features/data/apollo)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/data/apollo - do not edit. */}

<OptionBanner cat="data" option="apollo" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Apollo Client 4 is the GraphQL data layer, wired up in `src/lib/apollo.tsx`. I'd pick it when your backend speaks GraphQL - you get a normalised `InMemoryCache`, `useQuery` / `useMutation` and a `cache-and-network` default - and I'd stay on `react-query` or `swr` for REST. Refetch-on-foreground is already handled: the client uses Apollo 4.3's `RefetchEventManager` with the `windowFocus` source swapped for an `AppState` observable, so every active query refetches when the app comes back unless it sets `refetchOn: false`.

## Setup [#setup]

```bash
bun run setup --data apollo
```

1. Put your GraphQL endpoint in `.env` as `EXPO_PUBLIC_GRAPHQL_URL`, for example `https://countries.trevorblades.com/graphql`. It's optional - the example query is skipped until you set it.
2. For an authenticated API, add an `ApolloLink` (`@apollo/client/link/context`) inside `createApolloClient` in `src/lib/apollo.tsx`.

Setup installs `@apollo/client` ^4.3, `graphql` ^16 and `rxjs` ^7.8 (a required peer of v4), and adds `src/lib/apollo.tsx` (`apolloClient` plus `ApolloProvider` at order 20), and a `MockedProvider` test, plus `src/hooks/use-example-query.ts` and the `/examples/query` route and screen with `--with-examples`.

| Key                       | Required | What it is              |
| ------------------------- | -------- | ----------------------- |
| `EXPO_PUBLIC_GRAPHQL_URL` | no       | The `HttpLink` endpoint |

## Usage [#usage]

In Apollo 4 the React hooks live in `@apollo/client/react` and the core in `@apollo/client`:

```ts
import { gql } from "@apollo/client";
import { useQuery } from "@apollo/client/react";

const ME = gql`
  query Me {
    me {
      id
      name
    }
  }
`;

const { data, loading, error, refetch } = useQuery(ME);
```

Mutations use `useMutation` from the same entry point. With `--with-examples`, `src/hooks/use-example-query.ts` shows the typed shape with a `TypedDocumentNode`.

For readable error messages in development, import `loadDevMessages` and `loadErrorMessages` from `@apollo/client/dev` and call both in `src/lib/apollo.tsx` behind `__DEV__`.

## Gotchas [#gotchas]

* Expo Go works - it's pure JS, and Metro's package-exports resolution (SDK 53+) handles the v4 entry points.
* On every sign-out and account deletion `wipeLocalData()` runs the `onWipeLocalData` hooks, and `src/lib/apollo.tsx` registers `apolloClient.clearStore()` there, so the next user never sees the previous user's cached responses.
* `InMemoryCache` is lost on restart. To persist it, add `apollo3-cache-persist` (it works with v4) and `await persistCache({ cache, storage })` before rendering, using the adapter from `@/lib/storage`.
* The `online` refetch source is Apollo's default (the browser `online` event, a no-op on native). For offline-aware refetches add `@react-native-community/netinfo` and pass an `online` source to `RefetchEventManager`; `@apollo/client/link/retry` covers transient failures.
* No codegen is wired - the example hand-types its `TypedDocumentNode`. Add `@graphql-codegen/cli` if you want schema-derived types.
* Swapping stacks: `bun run setup --data none` (or `--data react-query` / `--data swr`) removes the files, deps, provider and env key, and with the examples, `/examples/query` falls back to the core "Module not installed" screen.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --data none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/query.tsx`, `src/hooks/__tests__/use-example-query.test.tsx`, `src/hooks/use-example-query.ts`, `src/lib/apollo.tsx`, `src/screens/examples/query-example-screen.tsx`.
2. **Replace, don't delete** `src/hooks/use-forecast.ts`: core code imports it, so swap in the no-op version from `modules/data/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @apollo/client graphql rxjs`.
4. **Unwrap the provider**: delete `<ApolloProvider>` and its import from `src/providers.tsx`.
5. **Remove the env keys** `EXPO_PUBLIC_GRAPHQL_URL` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_GRAPHQL_URL` from `src/lib/env.ts`.
6. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/data/apollo/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --data apollo
</Cmd>

Module id: `data/apollo`.

### Dependencies [#dependencies]

| Package          | Version    | Kind       |
| ---------------- | ---------- | ---------- |
| `@apollo/client` | `^4.3.0`   | dependency |
| `graphql`        | `^16.14.2` | dependency |
| `rxjs`           | `^7.8.2`   | dependency |

### Environment keys [#environment-keys]

| Key                       | Required | Server-only | Example                                      | Docs |
| ------------------------- | -------- | ----------- | -------------------------------------------- | ---- |
| `EXPO_PUBLIC_GRAPHQL_URL` | no       | no          | `https://countries.trevorblades.com/graphql` | -    |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider         | From           |
| ----- | ---------------- | -------------- |
| 20    | `ApolloProvider` | `@/lib/apollo` |

### Files [#files]

<details>
  <summary>
    6 files copied to the project root
  </summary>

  * `src/app/examples/query.tsx`
  * `src/hooks/__tests__/use-example-query.test.tsx`
  * `src/hooks/use-example-query.ts`
  * `src/hooks/use-forecast.ts`
  * `src/lib/apollo.tsx`
  * `src/screens/examples/query-example-screen.tsx`
</details>


# Data (/docs/features/data)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/data/README.md - do not edit. */}

Hey - here's how data works in ReadyNative. This category picks how your app talks to a backend:
the client, the cache, retries and refetch-on-foreground, all behind a provider that setup
registers for you.

Whichever option you pick, the shape is the same: a provider in `src/lib/` at order 20, one hook
per query under `src/hooks/` (with `--with-examples`, the `/examples/query` route to copy from), and a single
`EXPO_PUBLIC_*` base URL in `.env`. The REST options share `src/lib/api/client.ts` (`fetchJson`)
byte for byte, so moving between them doesn't churn your API code. Swap with
`bun run setup --data <option>`.

* **react-query** - the default. Reach for it when you want mutations, invalidation and real
  cache control over a REST API.
* **swr** - the same job with a much smaller surface: a string key is a request. Good when you
  mostly read.
* **apollo** - pick it when your backend speaks GraphQL.
* **none** - no client at all; call `fetch` yourself or bring your own.

## Options [#options]

One option per category - `--data <option>` picks it:

<Cmd>
  bun run setup --data react-query
</Cmd>

| Option                         | Label                    | Expo Go | Hint                                             |
| ------------------------------ | ------------------------ | ------- | ------------------------------------------------ |
| [`react-query`](./react-query) | TanStack Query (default) | yes     | server state + cache · Expo Go OK                |
| [`apollo`](./apollo)           | Apollo Client            | yes     | GraphQL client + normalized cache · Expo Go OK   |
| [`swr`](./swr)                 | SWR                      | yes     | stale-while-revalidate hooks · Expo Go OK        |
| [`none`](./none)               | No data layer            | yes     | plain fetch; add TanStack Query/Apollo/SWR later |


# No data layer (/docs/features/data/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/data/none - do not edit. */}

<OptionBanner cat="data" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Nothing is installed - you call `fetch` yourself. I'd keep this when the app has no backend yet, or when you want to bring your own client; everything else in the template works the same, and with `--with-examples`, `/examples/query` shows the core "Module not installed" screen.

## Setup [#setup]

```bash
bun run setup --data none
```

That's it - there's nothing to configure.

## Usage [#usage]

```ts
const res = await fetch("https://api.example.com/me");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const me = (await res.json()) as Me;
```

## Gotchas [#gotchas]

* Add a real data layer whenever you want caching and refetch-on-foreground: `bun run setup --data react-query` (REST), `--data swr` (REST, smaller) or `--data apollo` (GraphQL). Each one brings its own provider and example route.

## Reference [#reference]

Everything below is generated from `modules/data/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --data none
</Cmd>

Module id: `data/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/hooks/use-forecast.ts`
</details>


# TanStack Query (/docs/features/data/react-query)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/data/react-query - do not edit. */}

<OptionBanner cat="data" option="react-query" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

TanStack Query is the default data layer: a cache, retries and refetch-on-foreground for REST-shaped APIs, wired up in `src/lib/query.tsx`. I'd pick it over `swr` when you want mutations, query invalidation and devtool-grade cache control, and over `apollo` whenever your backend isn't GraphQL. It comes with `src/lib/api/client.ts` - a small `fetchJson` wrapper that resolves relative paths against `EXPO_PUBLIC_API_URL` - so your hooks stay free of URL plumbing.

## Setup [#setup]

```bash
bun run setup --data react-query
```

1. Put your API base URL in `.env` as `EXPO_PUBLIC_API_URL`, for example `https://jsonplaceholder.typicode.com`. It's optional - the example query stays disabled until you set it.

Setup adds `src/lib/query.tsx` (the `queryClient` with retry 1, `staleTime` 30s, `gcTime` 5min, and `QueryProvider` at order 20, refetching on `AppState` foreground), `src/lib/api/client.ts` and a test for the fetch client. With `--with-examples` you also keep the example hook `src/hooks/use-example-query.ts` and the `/examples/query` route with its screen.

| Key                   | Required | What it is                                               |
| --------------------- | -------- | -------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL` | no       | Base URL that relative `fetchJson` paths resolve against |

## Usage [#usage]

Write a hook per query and let `fetchJson` handle the URL and errors:

```ts
import { useQuery } from "@tanstack/react-query";
import { fetchJson } from "@/lib/api/client";

export function useMe() {
  return useQuery({ queryKey: ["me"], queryFn: () => fetchJson<Me>("/me") });
}
```

`fetchJson` takes a JSON body through `init.json`, times out, and throws `ApiError` on a non-2xx response - so mutations read the same way:

```ts
const save = useMutation({
  mutationFn: (input: Draft) => fetchJson<Note>("/notes", { method: "POST", json: input }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["notes"] }),
});
```

With `--with-examples`, `src/hooks/use-example-query.ts` is the shape to copy: it gates itself with `enabled: Boolean(env.API_URL)` so a fresh template makes no network calls.

On every sign-out and account deletion `wipeLocalData()` runs the `onWipeLocalData` hooks, and `src/lib/query.tsx` registers `queryClient.clear()` there, so the next user never sees the previous user's cached responses.

## Gotchas [#gotchas]

* Expo Go works - it's pure JS.
* No NetInfo is bundled, so `onlineManager` keeps the library default. Add `@react-native-community/netinfo` and call `onlineManager.setEventListener` in `src/lib/query.tsx` if you want offline-aware retries.
* Swapping stacks: `bun run setup --data none` (or `--data swr` / `--data apollo`) removes the files, dependency, provider and env key. With the examples, `/examples/query` then falls back to the core "Module not installed" screen. `src/lib/api/client.ts` is byte-identical in the `swr` module, so moving between the two doesn't churn it.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --data none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/query.tsx`, `src/hooks/use-example-query.ts`, `src/lib/api/__tests__/client.test.ts`, `src/lib/api/client.ts`, `src/lib/query.tsx`, `src/screens/examples/query-example-screen.tsx`.
2. **Replace, don't delete** `src/hooks/use-forecast.ts`: core code imports it, so swap in the no-op version from `modules/data/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @tanstack/react-query`.
4. **Unwrap the provider**: delete `<QueryProvider>` and its import from `src/providers.tsx`.
5. **Remove the env keys** `EXPO_PUBLIC_API_URL` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_API_URL` from `src/lib/env.ts`.
6. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/data/react-query/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --data react-query
</Cmd>

Module id: `data/react-query` (the default for this category).

### Dependencies [#dependencies]

| Package                 | Version    | Kind       |
| ----------------------- | ---------- | ---------- |
| `@tanstack/react-query` | `^5.103.2` | dependency |

### Environment keys [#environment-keys]

| Key                   | Required | Server-only | Example                                | Docs |
| --------------------- | -------- | ----------- | -------------------------------------- | ---- |
| `EXPO_PUBLIC_API_URL` | no       | no          | `https://jsonplaceholder.typicode.com` | -    |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider        | From          |
| ----- | --------------- | ------------- |
| 20    | `QueryProvider` | `@/lib/query` |

### Files [#files]

<details>
  <summary>
    7 files copied to the project root
  </summary>

  * `src/app/examples/query.tsx`
  * `src/hooks/use-example-query.ts`
  * `src/hooks/use-forecast.ts`
  * `src/lib/api/__tests__/client.test.ts`
  * `src/lib/api/client.ts`
  * `src/lib/query.tsx`
  * `src/screens/examples/query-example-screen.tsx`
</details>


# SWR (/docs/features/data/swr)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/data/swr - do not edit. */}

<OptionBanner cat="data" option="swr" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

SWR is the small data layer: a stale-while-revalidate cache with a global fetcher, configured in `src/lib/swr.tsx`. I'd pick it over `react-query` when you mostly read data and want the smallest possible API surface - a string key is all a hook needs - and over `apollo` whenever your backend isn't GraphQL. It ships the same `src/lib/api/client.ts` (`fetchJson`) as the TanStack Query module, so switching between the two doesn't churn your API code.

## Setup [#setup]

```bash
bun run setup --data swr
```

1. Put your API base URL in `.env` as `EXPO_PUBLIC_API_URL`, for example `https://jsonplaceholder.typicode.com`. It's optional - the example hook stays paused until you set it.

Setup adds `src/lib/swr.tsx` (`SwrProvider`, order 20: `SWRConfig` with `fetchJson` as the global fetcher, a per-session `Map` cache, revalidate-on-foreground wired to `AppState` through `isVisible` / `initFocus`, one retry, 2s dedupe), `src/lib/api/client.ts` and two tests, plus `src/hooks/use-example-query.ts` and the `/examples/query` route and screen with `--with-examples`.

| Key                   | Required | What it is                                               |
| --------------------- | -------- | -------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL` | no       | Base URL that relative `fetchJson` paths resolve against |

## Usage [#usage]

With the global fetcher, a string key is a path relative to `EXPO_PUBLIC_API_URL`:

```ts
const { data, error, isLoading, mutate } = useSWR<Me>("/me");
```

Pass your own fetcher when you want the types inline, and pass `null` as the key to pause a request:

```ts
const q = useSWR(userId ? `/users/${userId}` : null, (path) => fetchJson<User>(path));
```

Mutations come from `swr/mutation`:

```ts
const { trigger } = useSWRMutation("/notes", (key, { arg }: { arg: Draft }) =>
  fetchJson<Note>(key, { method: "POST", json: arg })
);
```

## Gotchas [#gotchas]

* Expo Go works - it's pure JS.
* On every sign-out and account deletion `wipeLocalData()` runs the `onWipeLocalData` hooks, and `SwrProvider` registers `mutate(() => true, undefined, { revalidate: false })` there (the `mutate` bound to its cache), so the next user never sees the previous user's cached responses. If you persist the cache, clear the persisted copy in the same hook.
* The cache is in memory (`createSwrCache`). To keep it across launches, back the `provider` with `@/lib/storage`: hydrate a `Map` on start and write it back when `AppState` goes to `background`. SWR's "Cache provider" docs cover the shape.
* `isOnline` / `initReconnect` are the library defaults, which means "always online". Add `@react-native-community/netinfo` and set both in `swrConfig` for offline-aware revalidation.
* Swapping stacks: `bun run setup --data none` (or `--data react-query` / `--data apollo`) removes the files, dependency, provider and env key, and with the examples, `/examples/query` falls back to the core "Module not installed" screen.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --data none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/query.tsx`, `src/hooks/__tests__/use-example-query.test.tsx`, `src/hooks/use-example-query.ts`, `src/lib/api/__tests__/client.test.ts`, `src/lib/api/client.ts`, `src/lib/swr.tsx`, `src/screens/examples/query-example-screen.tsx`.
2. **Replace, don't delete** `src/hooks/use-forecast.ts`: core code imports it, so swap in the no-op version from `modules/data/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove swr`.
4. **Unwrap the provider**: delete `<SwrProvider>` and its import from `src/providers.tsx`.
5. **Remove the env keys** `EXPO_PUBLIC_API_URL` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_API_URL` from `src/lib/env.ts`.
6. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/data/swr/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --data swr
</Cmd>

Module id: `data/swr`.

### Dependencies [#dependencies]

| Package | Version  | Kind       |
| ------- | -------- | ---------- |
| `swr`   | `^2.3.0` | dependency |

### Environment keys [#environment-keys]

| Key                   | Required | Server-only | Example                                | Docs |
| --------------------- | -------- | ----------- | -------------------------------------- | ---- |
| `EXPO_PUBLIC_API_URL` | no       | no          | `https://jsonplaceholder.typicode.com` | -    |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider      | From        |
| ----- | ------------- | ----------- |
| 20    | `SwrProvider` | `@/lib/swr` |

### Files [#files]

<details>
  <summary>
    8 files copied to the project root
  </summary>

  * `src/app/examples/query.tsx`
  * `src/hooks/__tests__/use-example-query.test.tsx`
  * `src/hooks/use-example-query.ts`
  * `src/hooks/use-forecast.ts`
  * `src/lib/api/__tests__/client.test.ts`
  * `src/lib/api/client.ts`
  * `src/lib/swr.tsx`
  * `src/screens/examples/query-example-screen.tsx`
</details>


# Forms (/docs/features/forms)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/forms/README.md - do not edit. */}

Hey - here's how forms work in ReadyNative. This category decides whether you get a form library
on top of the kit's `Input` (`@/components/ui`), which already renders a label, a value and an error message.

Either way the inputs are the same kit primitives and validation messages land in the same
`error` prop, so a form written today keeps looking right if you switch stacks later. Swap with
`bun run setup --forms <option>`.

* **react-hook-form** - the default. Pick it as soon as a form has more than two fields or any
  validation worth naming: you get a zod schema per form and a `Field` component that binds the
  kit's `Input` through `Controller`.
* **none** - controlled `Input`s with `useState`. Fine for a search box or a rename
  dialog.

## Options [#options]

One option per category - `--forms <option>` picks it:

<Cmd>
  bun run setup --forms react-hook-form
</Cmd>

| Option                                 | Label                     | Expo Go | Hint                                                  |
| -------------------------------------- | ------------------------- | ------- | ----------------------------------------------------- |
| [`react-hook-form`](./react-hook-form) | React Hook Form (default) | yes     | Form + Field on @/ui Input, zod resolver · Expo Go OK |
| [`none`](./none)                       | No forms library          | yes     | controlled @/ui Inputs with useState                  |


# No forms library (/docs/features/forms/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/forms/none - do not edit. */}

<OptionBanner cat="forms" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Nothing is installed - you write controlled `Input`s from `@/components/ui` with `useState` and validate by hand. I'd keep this while your forms are one or two fields (a search box, a rename dialog); it's one less dependency and the kit's `Input` already renders labels and errors. With `--with-examples`, `/examples/form` shows the core "Module not installed" screen.

## Setup [#setup]

```bash
bun run setup --forms none
```

That's it - there's nothing to configure.

## Usage [#usage]

```tsx
import { useState } from "react";
import { Button, Input } from "@/components/ui";

const [email, setEmail] = useState("");
const error = email.includes("@") ? undefined : "Enter a valid email";

<Input label="Email" value={email} onChangeText={setEmail} error={error} />;
<Button onPress={submit}>Save</Button>;
```

## Gotchas [#gotchas]

* Once a form grows past a couple of fields, or you want a schema, run `bun run setup --forms react-hook-form`. It adds a `Field` component that binds the same `Input` through `Controller`.

## Reference [#reference]

Everything below is generated from `modules/forms/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --forms none
</Cmd>

Module id: `forms/none`.


# React Hook Form (/docs/features/forms/react-hook-form)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/forms/react-hook-form - do not edit. */}

<OptionBanner cat="forms" option="react-hook-form" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

React Hook Form plus a zod resolver, wrapped in two small components under `src/components/form/` so your screens stay on `@/components/ui`. I'd pick it over `forms/none` as soon as a form has more than two fields or any validation worth naming - you get uncontrolled inputs, one schema per form and error messages wired into the kit's `Input` for free. `Field` is the contract here: it binds the kit's `Input` through `Controller` and shows the validation message as its `error` prop, so you never style an error state by hand.

## Setup [#setup]

```bash
bun run setup --forms react-hook-form
```

That's it - setup adds `src/components/form/form.tsx` (`<Form form={…}>`, a `FormProvider` wrapper), `src/components/form/field.tsx`, the barrel `index.ts`, and a test; `@hookform/resolvers/zod` is zod 4 compatible. With `--with-examples` you also get the `/examples/form` route with a zod schema.

## Usage [#usage]

One schema, one `useForm`, one `<Form>`:

```tsx
import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import { Field, Form } from "@/components/form";
import { Button } from "@/components/ui";

const schema = z.object({ email: z.email(), name: z.string().min(1) });
type Values = z.infer<typeof schema>;

const form = useForm<Values>({ resolver: zodResolver(schema), defaultValues });

<Form form={form}>
  <Field<Values> name="email" label="Email" keyboardType="email-address" />
  <Field<Values> name="name" label="Name" />
  <Button onPress={() => void form.handleSubmit(onValid)()}>Save</Button>
</Form>;
```

`Field` accepts every `InputProps` except `value`, `onChangeText` and `error` - those are what it wires up for you.

## Gotchas [#gotchas]

* Expo Go works - it's pure JS.
* Set up with `--with-examples`? Copy `src/screens/examples/form-example-screen.tsx` when you start a real form; it's the full loop from schema to submit.
* Swapping stacks: `bun run setup --forms none` deletes `src/components/form`, the example and both dependencies. Screens that used `Field` need rewriting as controlled `Input`s.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --forms none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/form.tsx`, `src/components/form/__tests__/field.test.tsx`, `src/components/form/field.tsx`, `src/components/form/form.tsx`, `src/components/form/index.ts`, `src/screens/examples/form-example-screen.tsx`.
2. **Uninstall the dependencies**: `bun remove @hookform/resolvers react-hook-form`.
3. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/forms/react-hook-form/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --forms react-hook-form
</Cmd>

Module id: `forms/react-hook-form` (the default for this category).

### Dependencies [#dependencies]

| Package               | Version   | Kind       |
| --------------------- | --------- | ---------- |
| `@hookform/resolvers` | `^5.9.1`  | dependency |
| `react-hook-form`     | `^7.88.0` | dependency |

### Files [#files]

<details>
  <summary>
    6 files copied to the project root
  </summary>

  * `src/app/examples/form.tsx`
  * `src/components/form/__tests__/field.test.tsx`
  * `src/components/form/field.tsx`
  * `src/components/form/form.tsx`
  * `src/components/form/index.ts`
  * `src/screens/examples/form-example-screen.tsx`
</details>


# i18next (/docs/features/i18n/i18next)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/i18n/i18next - do not edit. */}

<OptionBanner cat="i18n" option="i18next" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

i18next plus react-i18next replace the core i18n shim in `src/lib/i18n.ts`, keeping exactly the same surface your screens already use: `i18n.t(key, vars)` and `useT()`. I'd pick it when you want the ecosystem - plurals, formatters, ICU add-ons, and translators who already know the format. Pick `lingui` if you'd rather have a CLI-driven catalog workflow, and `none` while you're still English-only. Keys are the English source strings, so a screen reads identically with or without this module.

## Setup [#setup]

```bash
bun run setup --i18n i18next
```

Six languages ship - English, Spanish, Russian, Chinese (Simplified), Portuguese and Arabic (`src/locales/{en,es,ru,zh,pt,ar}.json`); the device language wins, and Settings has a language picker that renders from `LANGUAGES`. To add a locale:

1. Create `src/locales/<code>.json` next to the shipped ones (a test checks every locale has the same keys as `en.json`).
2. Register it: add the code to `LANGUAGES`, a native name to `LANGUAGE_LABELS` and an entry in `resources` in `src/lib/i18n.ts` - and to `RTL_LANGUAGES` if it's written right-to-left (Hebrew, Persian, Urdu). `LANGUAGES` is the single source of truth - the Settings picker (and `/examples/i18n`, with `--with-examples`) render from it.

`bun run gen screen --tab` appends new tab titles to every locale file (English value, translate later). Locale files are yours: `setup`/`clean` never remove them.

Setup also adds `expo-localization` and its config plugin for the device language, persists the user's override under `readynative:language` through your storage adapter, registers `I18nProvider` (order 60), and adds a test (plus the `/examples/i18n` route with `--with-examples`).

## Usage [#usage]

```tsx
import { useT } from "@/lib/i18n";
import { Text } from "@/components/ui";

const t = useT();

<Text>{t("Version {{version}}", { version })}</Text>;
```

To add a key, write the English sentence in code and add it to every `src/locales/*.json`. Missing keys fall back to English, then to the key itself.

To switch language at runtime, use `setLanguage(code)` and read the current one with `useLanguage()`; `deviceLanguage()` gives you what the OS reports.

## Right-to-left [#right-to-left]

Arabic is in `RTL_LANGUAGES`. `setLanguage("ar")` calls `I18nManager.forceRTL(true)` and restarts the app with `reloadAppAsync()`, because React Native applies a new layout direction only on launch; switching back to a left-to-right language does the reverse. Rows, stacks, tab bars and back buttons mirror on their own. On web it flips `<html dir>` in place, with no restart. `isRTL(language)` tells you the direction of any language.

* Expo Go resets the direction whenever it opens a project, so the text turns Arabic but the layout stays left-to-right there - check RTL in a dev build.
* The `expo-localization` config plugin keeps `supportsRTL` on (the default). Set `["expo-localization", { supportsRTL: false }]` in your app config if you never ship an RTL language.
* Write layouts with `start`/`end` in mind: `marginLeft`/`paddingRight` mirror automatically, absolute `left`/`right` positions and direction-bearing icons (arrows, chevrons) need a look.

## Gotchas [#gotchas]

* Expo Go works - it's pure JS plus `expo-localization`.
* `keySeparator` and `nsSeparator` are off, so sentences containing dots or colons are valid keys.
* On an async storage adapter (`async-storage`), the stored language is only known after `initI18n()` resolves - gate first paint on the splash screen if a language flash would show.
* Swapping stacks: `bun run setup --i18n none` restores the shim re-export, removes the locales, the example and the three dependencies. Screens keep working - `t(key)` returns the English key.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --i18n none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/i18n.tsx`, `src/lib/__tests__/i18n.test.tsx`, `src/locales/ar.json`, `src/locales/en.json`, `src/locales/es.json`, `src/locales/pt.json`, `src/locales/ru.json`, `src/locales/zh.json`, `src/screens/examples/i18n-example-screen.tsx`.
2. **Replace, don't delete** `src/lib/i18n.ts`: core code imports it, so swap in the no-op version from `modules/i18n/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove expo-localization i18next react-i18next`. Keep any of `expo-localization` (also used by `analytics/posthog`, `consent/consent`) that another module you picked still needs.
4. **Drop the config plugin** `expo-localization` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<I18nProvider>` and its import from `src/providers.tsx`.
6. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/i18n/i18next/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --i18n i18next
</Cmd>

Module id: `i18n/i18next` (the default for this category).

### Dependencies [#dependencies]

| Package             | Version    | Kind                        |
| ------------------- | ---------- | --------------------------- |
| `expo-localization` | `~57.0.2`  | dependency (`expo install`) |
| `i18next`           | `^26.4.2`  | dependency                  |
| `react-i18next`     | `^17.0.15` | dependency                  |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-localization`

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider       | From         |
| ----- | -------------- | ------------ |
| 60    | `I18nProvider` | `@/lib/i18n` |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Files [#files]

<details>
  <summary>
    10 files copied to the project root
  </summary>

  * `src/app/examples/i18n.tsx`
  * `src/lib/__tests__/i18n.test.tsx`
  * `src/lib/i18n.ts`
  * `src/locales/ar.json`
  * `src/locales/en.json`
  * `src/locales/es.json`
  * `src/locales/pt.json`
  * `src/locales/ru.json`
  * `src/locales/zh.json`
  * `src/screens/examples/i18n-example-screen.tsx`
</details>


# i18n (/docs/features/i18n)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/i18n/README.md - do not edit. */}

Hey - here's how i18n works in ReadyNative. This category decides how your copy gets translated -
and, importantly, it doesn't decide how your screens are written.

The contract is `src/lib/i18n.ts`: `i18n.t(key, vars)` and `useT()`, where keys are the English
source strings and placeholders are `{{name}}`. That surface exists with or without a library
(core ships a shim), so a screen reads identically under every option and adding translations
later is a `setup` call rather than a refactor. The real modules add `src/locales/*.json`, the
device language through `expo-localization`, a language override persisted under
`readynative:language`, an `I18nProvider` at order 60 and, with `--with-examples`, the `/examples/i18n` picker. Swap with
`bun run setup --i18n <option>`.

* **i18next** - the default. Pick it for the bigger ecosystem: plurals, formatters, translators
  who already know the format.
* **lingui** - pick it for ICU messages and a catalog CLI (`bun run i18n:extract`).
* **none** - the shim. English only, zero dependencies.

## Options [#options]

One option per category - `--i18n <option>` picks it:

<Cmd>
  bun run setup --i18n i18next
</Cmd>

| Option                 | Label             | Expo Go | Hint                                                                                          |
| ---------------------- | ----------------- | ------- | --------------------------------------------------------------------------------------------- |
| [`i18next`](./i18next) | i18next (default) | yes     | react-i18next + expo-localization, 6 languages bundled incl. Arabic (RTL) · Expo Go OK        |
| [`lingui`](./lingui)   | Lingui            | yes     | @lingui/core + @lingui/react runtime API, 6 languages bundled incl. Arabic (RTL) · Expo Go OK |
| [`none`](./none)       | No i18n           | yes     | i18n.t/useT return the English key                                                            |


# Lingui (/docs/features/i18n/lingui)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/i18n/lingui - do not edit. */}

<OptionBanner cat="i18n" option="lingui" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Lingui's runtime API (`@lingui/core` `setupI18n` plus `@lingui/react`) replaces the core i18n shim in `src/lib/i18n.ts`, with the same surface as everywhere else: `i18n.t(key, vars)` and `useT()`. I'd pick it when you want ICU message syntax and a catalog CLI (`bun run i18n:extract`); pick `i18next` for the bigger plugin ecosystem, and `none` while you're still English-only. Screens don't change shape: they keep the shim's `{{name}}` placeholders, and `toIcu()` converts them to `{name}` at the `t` boundary.

## Setup [#setup]

```bash
bun run setup --i18n lingui
```

Six languages ship - English, Spanish, Russian, Chinese (Simplified), Portuguese and Arabic (`src/locales/{en,es,ru,zh,pt,ar}.json`, Lingui "minimal" catalogs: id → string, ICU `{var}` placeholders); the device language wins, and Settings has a language picker that renders from `LANGUAGES`. To add a locale:

1. Create `src/locales/<code>.json` next to the shipped ones (a test checks every locale has the same keys as `en.json`).
2. Register it: add the code to `LANGUAGES` (and `RTL_LANGUAGES` for a right-to-left script), a native name to `LANGUAGE_LABELS` and `messages` in `src/lib/i18n.ts`, and to `locales` in `lingui.config.ts`. `LANGUAGES` is the single source of truth - the Settings picker (and `/examples/i18n`, with `--with-examples`) render from it.
3. Normalise catalogs whenever you like: `bun run i18n:extract`.

`bun run gen screen --tab` appends new tab titles to every locale file (English value, translate later). Locale files are yours: `setup`/`clean` never remove them.

Setup also adds `expo-localization` and its config plugin, persists the language override under `readynative:language` through your storage adapter, registers `I18nProvider` (order 60), and adds a test (plus the `/examples/i18n` route with `--with-examples`). The instance is exported as `lingui` if you want `Trans` or `useLingui()`.

## Usage [#usage]

```tsx
import { useT } from "@/lib/i18n";
import { Text } from "@/components/ui";

const t = useT();

<Text>{t("Version {{version}}", { version })}</Text>;
```

Add a key by writing the English sentence in code and adding it to every `src/locales/*.json` with ICU `{var}` placeholders. A missing id renders the key (English) with interpolation.

`setLanguage(code)` switches at runtime, `useLanguage()` reads the current one, `deviceLanguage()` reports the OS language. Both hooks subscribe to the instance directly, so they work outside `I18nProvider` too - tests render screens bare.

## Right-to-left [#right-to-left]

Arabic is in `RTL_LANGUAGES`. `setLanguage("ar")` calls `I18nManager.forceRTL(true)` and restarts the app with `reloadAppAsync()`, because React Native applies a new layout direction only on launch; switching back to a left-to-right language does the reverse. Rows, stacks, tab bars and back buttons mirror on their own. On web it flips `<html dir>` in place, with no restart. `isRTL(language)` tells you the direction of any language.

* Expo Go resets the direction whenever it opens a project, so the text turns Arabic but the layout stays left-to-right there - check RTL in a dev build.
* The `expo-localization` config plugin keeps `supportsRTL` on (the default). Set `["expo-localization", { supportsRTL: false }]` in your app config if you never ship an RTL language.
* Write layouts with `start`/`end` in mind: `marginLeft`/`paddingRight` mirror automatically, absolute `left`/`right` positions and direction-bearing icons (arrows, chevrons) need a look.

## Gotchas [#gotchas]

* Expo Go works - it's pure JS plus `expo-localization`.
* **No macros.** `babel.config.js` belongs to the UI module, so `@lingui/babel-plugin-lingui-macro` isn't installed. Catalogs are raw JSON compiled at runtime through `setMessagesCompiler(compileMessage)`. Use `i18n.t` / `useT()` / `<Trans id="…" />`; the `t` and `Trans` macros will not work.
* `bun run i18n:extract` runs `npx lingui extract`, but it only sees literal `i18n.t("…")` / `i18n._("…")` calls - not `t()` from `useT()` - and writes ids verbatim (`{{var}}`). Treat it as a catalog normaliser; it never deletes ids. `__tests__` and `shims` are excluded.
* Swapping stacks: `bun run setup --i18n none` restores the shim re-export and removes the locales, `lingui.config.ts`, the example, the `i18n:extract` script and the five packages. Screens keep working - `t(key)` returns the English key.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --i18n none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `lingui.config.ts`, `src/app/examples/i18n.tsx`, `src/lib/__tests__/i18n.test.tsx`, `src/locales/ar.json`, `src/locales/en.json`, `src/locales/es.json`, `src/locales/pt.json`, `src/locales/ru.json`, `src/locales/zh.json`, `src/screens/examples/i18n-example-screen.tsx`.
2. **Replace, don't delete** `src/lib/i18n.ts`: core code imports it, so swap in the no-op version from `modules/i18n/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove @lingui/core @lingui/message-utils @lingui/react expo-localization @lingui/cli @lingui/format-json`. Keep any of `expo-localization` (also used by `analytics/posthog`, `consent/consent`) that another module you picked still needs.
4. **Drop the config plugin** `expo-localization` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<I18nProvider>` and its import from `src/providers.tsx`.
6. **Delete the script** `i18n:extract` from `package.json`.
7. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/i18n/lingui/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --i18n lingui
</Cmd>

Module id: `i18n/lingui`.

### Dependencies [#dependencies]

| Package                 | Version   | Kind                        |
| ----------------------- | --------- | --------------------------- |
| `@lingui/core`          | `^5.9.5`  | dependency                  |
| `@lingui/message-utils` | `^5.9.5`  | dependency                  |
| `@lingui/react`         | `^5.9.5`  | dependency                  |
| `expo-localization`     | `~57.0.2` | dependency (`expo install`) |
| `@lingui/cli`           | `^5.9.5`  | devDependency               |
| `@lingui/format-json`   | `^5.9.5`  | devDependency               |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-localization`

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider       | From         |
| ----- | -------------- | ------------ |
| 60    | `I18nProvider` | `@/lib/i18n` |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### After setup [#after-setup]

1. Lingui runs its runtime API only (no babel macro: babel.config.js belongs to the UI stack). Edit src/locales/\*.json by hand; `bun run i18n:extract` cannot see t() calls.

### Files [#files]

<details>
  <summary>
    11 files copied to the project root
  </summary>

  * `lingui.config.ts`
  * `src/app/examples/i18n.tsx`
  * `src/lib/__tests__/i18n.test.tsx`
  * `src/lib/i18n.ts`
  * `src/locales/ar.json`
  * `src/locales/en.json`
  * `src/locales/es.json`
  * `src/locales/pt.json`
  * `src/locales/ru.json`
  * `src/locales/zh.json`
  * `src/screens/examples/i18n-example-screen.tsx`
</details>


# No i18n (/docs/features/i18n/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/i18n/none - do not edit. */}

<OptionBanner cat="i18n" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

`src/lib/i18n.ts` re-exports the core shim (`src/lib/shims/i18n.ts`): `i18n.t(key, vars)` and `useT()` return the English key with `{{var}}` interpolation. I'd keep this while the app ships in one language - screens are written exactly as they would be with i18next or Lingui, so adding translations later is a `setup` call, not a refactor. With `--with-examples`, `/examples/i18n` shows the core "Module not installed" screen.

## Setup [#setup]

```bash
bun run setup --i18n none
```

That's it - there's nothing to configure.

## Usage [#usage]

Write your English copy as the key and it renders as-is:

```tsx
import { useT } from "@/lib/i18n";

const t = useT();

<Text>{t("Version {{version}}", { version })}</Text>;
```

## Gotchas [#gotchas]

* The shim never re-renders on a language change, because there is no language to change.
* Ready to translate? `bun run setup --i18n i18next` (or `--i18n lingui`) keeps every call site and adds catalogs, a language picker and device-language detection.

## Reference [#reference]

Everything below is generated from `modules/i18n/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --i18n none
</Cmd>

Module id: `i18n/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/i18n.ts`
</details>


# Features (/docs/features)



{/* Generated by apps/docs/scripts/gen-modules.ts - do not edit. */}

Every optional thing lives in `modules/<category>/<option>/` with a `module.json`, a `files/` mirror of the repo root and a `docs.md`. `bun run setup` copies the selected options in, generates providers / env and deletes `modules/` (unless `--keep-modules`). The first option of each category is its default.

| Category                         | Options (default first)                                                                                                                                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [UI](./ui)                       | [`nativewind4`](./ui/nativewind4) · [`nativewind5`](./ui/nativewind5) · [`tamagui`](./ui/tamagui) · [`unistyles`](./ui/unistyles) · [`stylesheet`](./ui/stylesheet) |
| [Data](./data)                   | [`react-query`](./data/react-query) · [`apollo`](./data/apollo) · [`swr`](./data/swr) · [`none`](./data/none)                                                       |
| [State](./state)                 | [`zustand`](./state/zustand) · [`jotai`](./state/jotai) · [`none`](./state/none)                                                                                    |
| [Storage](./storage)             | [`kv-store`](./storage/kv-store) · [`mmkv`](./storage/mmkv) · [`async-storage`](./storage/async-storage)                                                            |
| [Forms](./forms)                 | [`react-hook-form`](./forms/react-hook-form) · [`none`](./forms/none)                                                                                               |
| [i18n](./i18n)                   | [`i18next`](./i18n/i18next) · [`lingui`](./i18n/lingui) · [`none`](./i18n/none)                                                                                     |
| [Auth](./auth)                   | [`supabase`](./auth/supabase) · [`clerk`](./auth/clerk) · [`better-auth`](./auth/better-auth) · [`none`](./auth/none)                                               |
| [Payments](./payments)           | [`revenuecat`](./payments/revenuecat) · [`adapty`](./payments/adapty) · [`stripe`](./payments/stripe) · [`none`](./payments/none)                                   |
| [Analytics](./analytics)         | [`posthog`](./analytics/posthog) · [`amplitude`](./analytics/amplitude) · [`none`](./analytics/none)                                                                |
| [Crash reporting](./crash)       | [`sentry`](./crash/sentry) · [`none`](./crash/none)                                                                                                                 |
| [Push notifications](./push)     | [`expo-notifications`](./push/expo-notifications) · [`none`](./push/none)                                                                                           |
| [Backend](./backend)             | [`api-routes`](./backend/api-routes) · [`none`](./backend/none)                                                                                                     |
| [Onboarding](./onboarding)       | [`on`](./onboarding/on) · [`off`](./onboarding/off)                                                                                                                 |
| [Location](./location)           | [`expo-location`](./location/expo-location) · [`none`](./location/none)                                                                                             |
| [Home-screen widgets](./widgets) | [`expo-widgets`](./widgets/expo-widgets) · [`none`](./widgets/none)                                                                                                 |
| [Privacy consent](./consent)     | [`consent`](./consent/consent) · [`none`](./consent/none)                                                                                                           |
| [Testing](./testing)             | [`jest`](./testing/jest) · [`none`](./testing/none)                                                                                                                 |

See [Stack comparison](https://readynative.app/docs/choose-your-stack) for every option side by side and the
[module spec](https://readynative.app/docs/module-spec) for the `module.json` contract.


# Expo Location (/docs/features/location/expo-location)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/location/expo-location - do not edit. */}

<OptionBanner cat="location" option="expo-location" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This gives you the device position through [expo-location](https://docs.expo.dev/versions/latest/sdk/location/): `src/lib/location.ts` implements the shim, so `location.getCurrentPosition()` asks for foreground permission when it is still undetermined, returns a recent cached fix when there is one (up to 10 minutes old) and otherwise waits for a balanced-accuracy fix. `location.reverseGeocode(coords)` names the place ("Almaty") on iOS and Android. Every call resolves - `null` on denial, no fix or web geocoding - so screens never need a `try`. The weather demo's "My location" card uses it.

## Setup [#setup]

```bash
bun run setup --location expo-location
```

1. Rewrite the purpose string. The module adds `["expo-location", { locationWhenInUsePermission: "…" }]` to the app config; iOS shows that sentence in the permission dialog, and App Review rejects vague ones (guideline 5.1.1). Say what your app does with the position.
2. Nothing else: there are no keys, and Expo Go already includes expo-location. A changed purpose string needs a new native build (`npx expo run:ios`, or `eas build`).
3. Run `bun run doctor` - every row for this module should be green.

The module declares approximate location in the privacy manifest and the Play Data safety draft, because most apps send coordinates to a server (the weather demo sends them to Open-Meteo). If yours never leaves the device, you can drop that entry.

## Usage [#usage]

```tsx
import { location } from "@/lib/location";

const coords = await location.getCurrentPosition(); // { latitude, longitude } | null
if (coords) {
  const city = await location.reverseGeocode(coords); // "Almaty" | null
}
```

Check or ask for permission yourself, for example to explain it on your own screen first:

```ts
const permission = await location.getPermission(); // "undetermined" | "denied" | "granted" | "unsupported"
if (permission === "undetermined") await location.requestPermission();
```

`location.supported` is `true` here and `false` with `--location none`: use it to hide a "use my location" button rather than showing one that does nothing.

## Gotchas [#gotchas]

* iOS asks once. After a "Don't allow", `requestPermission()` resolves `"denied"` without a dialog - send people to Settings with `Linking.openSettings()`.
* Simulators have a location, but you choose it: iOS Simulator → Features → Location, Android emulator → Extended controls → Location.
* Web gets coordinates from the browser (HTTPS only) but no place names: `reverseGeocode` resolves `null` there.
* Background location is not wired. It needs `isIosBackgroundLocationEnabled`, the "Always" permission and a much harder App Review conversation - add it only when a feature needs it.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --location none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there: `src/lib/__tests__/location.test.ts`.
2. **Replace, don't delete** `src/lib/location.ts`: core code imports it, so swap in the no-op version from `modules/location/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove expo-location`.
4. **Drop the config plugin** `expo-location` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
6. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/location/expo-location/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --location expo-location
</Cmd>

Module id: `location/expo-location` (the default for this category).

### Dependencies [#dependencies]

| Package         | Version    | Kind                        |
| --------------- | ---------- | --------------------------- |
| `expo-location` | `~57.0.20` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-location` (with options)

### Privacy [#privacy]

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type             | Linked to user | Tracking | Purposes         |
| ---------------- | -------------- | -------- | ---------------- |
| `CoarseLocation` | no             | no       | AppFunctionality |

### After setup [#after-setup]

1. Rewrite the location purpose string for your app: app.config patch → `expo-location` plugin → `locationWhenInUsePermission` (modules/location/expo-location/module.json, or override it in app.config.ts). App Review rejects vague purpose strings (guideline 5.1.1). A new string needs a new native build.

### Files [#files]

<details>
  <summary>
    2 files copied to the project root
  </summary>

  * `src/lib/__tests__/location.test.ts`
  * `src/lib/location.ts`
</details>


# Location (/docs/features/location)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/location/README.md - do not edit. */}

Hey - here's how location works in ReadyNative.

This category owns the device's position: asking for permission, reading a fix, and turning
coordinates into a place name. `@/lib/location` always exists, whichever option you pick -
`location.getCurrentPosition()` resolves `{ latitude, longitude }` or `null`, and never throws,
so a screen handles "denied", "no GPS" and "no module" with the same branch.

Pick **Expo Location** when a screen is better with the user's position: local weather, a
nearby list, a pre-filled address. It works in Expo Go, asks for foreground ("while using the
app") permission only, and ships a purpose string you rewrite for your app. Pick **none** when
you never need it: no permission prompt, no purpose string for App Review to question, and
`location.supported` is `false` so screens hide their "use my location" button.

Both options are in Starter and Pro.

## Options [#options]

One option per category - `--location <option>` picks it:

<Cmd>
  bun run setup --location expo-location
</Cmd>

| Option                             | Label                   | Expo Go | Hint                                                                            |
| ---------------------------------- | ----------------------- | ------- | ------------------------------------------------------------------------------- |
| [`expo-location`](./expo-location) | Expo Location (default) | yes     | foreground position + reverse geocoding, permission states handled · Expo Go OK |
| [`none`](./none)                   | No location             | yes     | no permission prompt, no expo-location                                          |


# No location (/docs/features/location/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/location/none - do not edit. */}

<OptionBanner cat="location" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-op location option: no expo-location, no permission dialog and no purpose string in your app. It owns `src/lib/location.ts` as a re-export of the core shim, so `@/lib/location` keeps the same API - `location.supported` is `false`, `getCurrentPosition()` resolves `null` and the permission calls resolve `"unsupported"`.

## Setup [#setup]

```bash
bun run setup --location none
```

There's nothing to configure. Switch with `bun run setup --location expo-location` when a screen needs the user's position.

## Usage [#usage]

```tsx
import { location } from "@/lib/location";

if (location.supported) {
  // render a "use my location" button
}
const coords = await location.getCurrentPosition(); // always null
```

## Gotchas [#gotchas]

* Screens written against the shim already handle `null`, so switching options later changes no screen code.
* Nothing here needs a dev build; Expo Go is fine.

## Reference [#reference]

Everything below is generated from `modules/location/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --location none
</Cmd>

Module id: `location/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/location.ts`
</details>


# Onboarding (/docs/features/onboarding)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/onboarding/README.md - do not edit. */}

Hey - here's how onboarding works in ReadyNative. This category is a yes/no: does a first-run flow
appear before the app's tabs?

What stays the same either way: the onboarding store (`src/stores/onboarding.ts`, key
`readynative:onboarding`) and the Settings "Reset onboarding" button are core, and the root layout
always calls `useOnboardingRedirect()` - the `off` option just makes that hook a no-op. So the
core tree is identical under both options and turning the flow on later changes nothing outside
the module. Swap with `bun run setup --onboarding <option>`.

* **on** - the default. Pick it when new users need context first: three slides built from
  `@/components/ui`, edited in one `SLIDES` array, finishing at `router.replace("/")`.
* **off** - pick it when your first screen explains itself.

## Options [#options]

One option per category - `--onboarding <option>` picks it:

<Cmd>
  bun run setup --onboarding on
</Cmd>

| Option         | Label                     | Expo Go | Hint                                                   |
| -------------- | ------------------------- | ------- | ------------------------------------------------------ |
| [`on`](./on)   | Onboarding flow (default) | yes     | 3-slide intro at /onboarding, redirect until completed |
| [`off`](./off) | No onboarding             | yes     | app opens straight into the tabs                       |


# No onboarding (/docs/features/onboarding/off)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/onboarding/off - do not edit. */}

<OptionBanner cat="onboarding" option="off" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

No onboarding route: the app opens straight on its first tab. I'd keep this when the first screen explains itself, or while you're still deciding what to say. Setup still installs a no-op `useOnboardingRedirect()` in `src/hooks/use-onboarding-redirect.ts`, so the core root layout is byte-identical under both options and turning onboarding on later changes nothing outside the module.

## Setup [#setup]

```bash
bun run setup --onboarding off
```

That's it - there's nothing to configure.

## Usage [#usage]

Nothing to call. The built-in onboarding store (`src/stores/onboarding.ts`) is core, so it stays - it doesn't affect navigation. The hook file also exports `onboardingEnabled = false`, and Settings hides "Reset onboarding" when it's false.

## Gotchas [#gotchas]

* Want the flow? `bun run setup --onboarding on` adds the `/onboarding` route group, a three-slide screen you edit in one array, and the real redirect hook.

## Reference [#reference]

Everything below is generated from `modules/onboarding/off/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --onboarding off
</Cmd>

Module id: `onboarding/off`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/hooks/use-onboarding-redirect.ts`
</details>


# Onboarding flow (/docs/features/onboarding/on)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/onboarding/on - do not edit. */}

<OptionBanner cat="onboarding" option="on" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

A three-slide onboarding flow at `/onboarding` that shows once, before the app's tabs. I'd turn this on when new users need context - a value pitch, a permission explainer, a sign-in nudge - and leave it `off` when your first screen is self-explanatory. The route group has no header and no back gesture, the slides are built from `@/components/ui` primitives (no ScrollView paging), and finishing calls `completeOnboarding()` and `router.replace("/")`.

## Setup [#setup]

```bash
bun run setup --onboarding on
```

That's it - setup adds the route group (`src/app/onboarding/_layout.tsx`, `src/app/onboarding/index.tsx`), the screen `src/screens/onboarding/onboarding-screen.tsx`, and `src/hooks/use-onboarding-redirect.ts`, which the core root layout already calls.

## Usage [#usage]

Edit the `SLIDES` array in `src/screens/onboarding/onboarding-screen.tsx` - each slide is a title, a description and an icon, rendered with Next / Back / Skip controls.

The state lives in core at `src/stores/onboarding.ts` under the key `readynative:onboarding`. `useOnboardingRedirect()` hydrates that store and redirects to `/onboarding` once navigation is ready and `completed` is still false.

To test the flow again, use Settings → "Reset onboarding" (shown because the hook file exports `onboardingEnabled = true`); it flips `completed` back and the hook sends you to `/onboarding`.

## Gotchas [#gotchas]

* Expo Go works - there's nothing native here.
* The redirect waits for navigation to be ready, so the first frame can be your root route before it replaces - keep the splash screen up if that flicker bothers you.
* Swapping stacks: `bun run setup --onboarding off` swaps the hook for a no-op and deletes the route and screen. The store and the Settings reset button stay (they're core).

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --onboarding off --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there: `.maestro/flows/onboarding.yaml`, `src/app/onboarding/_layout.tsx`, `src/app/onboarding/index.tsx`, `src/screens/onboarding/onboarding-screen.tsx`.
2. **Replace, don't delete** `src/hooks/use-onboarding-redirect.ts`: core code imports it, so swap in the no-op version from `modules/onboarding/off/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/onboarding/on/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --onboarding on
</Cmd>

Module id: `onboarding/on` (the default for this category).

### Files [#files]

<details>
  <summary>
    5 files copied to the project root
  </summary>

  * `.maestro/flows/onboarding.yaml`
  * `src/app/onboarding/_layout.tsx`
  * `src/app/onboarding/index.tsx`
  * `src/hooks/use-onboarding-redirect.ts`
  * `src/screens/onboarding/onboarding-screen.tsx`
</details>


# Adapty (/docs/features/payments/adapty)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/payments/adapty - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="payments" option="adapty" />

<Callout type="warn" title="Expo Go: no - dev build required">
  Ships native code. Make a dev build with `bunx expo run:ios` / `bunx expo run:android` (or `bunx eas-cli build --profile development`).
</Callout>

This gives you in-app subscriptions through Adapty: `src/lib/payments.ts` implements the shim on `react-native-adapty` (its `active` list holds access-level ids such as `premium`), a `PaymentsProvider` (order 70) activates the SDK once and listens on `onLatestProfileLoad`, and `/paywall` ships as a modal with your feature bullets, the placement's products with localized price and period, Buy, Restore, and Terms/Privacy links from `readynative.config.ts` `urls`. If you set up with `--with-examples` there's an example at `/examples/paywall` and a jest mock for the SDK. `@/lib/payments` keeps the same API whichever option you pick - pick Adapty when you want its no-code Paywall Builder and A/B tests on placements.

## Setup [#setup]

```bash
bun run setup --payments adapty
```

1. Create an app at [app.adapty.io](https://app.adapty.io) and add the iOS bundle id (from `readynative.config.ts` `app.ios.bundleId`, plus `.dev` for the dev variant) and the Android package under \[App settings].
2. Open \[App settings] → \[General] and copy the Public SDK key (`public_live_…`) into `.env` as `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`. It's public and serves both platforms. Without it the module no-ops: `useEntitlements()` returns `{ active: [], loading: false }` and `/paywall` shows "Configure Adapty".
3. Create the subscriptions in \[App Store Connect] → \[Subscriptions] and \[Play Console] → \[Monetize] → \[Subscriptions], then add them in Adapty under \[Products].
4. Open \[Access levels] and use `premium` (Adapty's built-in default, and what the examples check for), then attach your products to it.
5. Open \[Paywalls], build one with the Paywall Builder, and attach your monthly product to it.
6. Open \[Placements] and attach that paywall to a placement. The default placement id is `default`; if you use another one, put it in `.env` as `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID`.
7. Add a sandbox tester in \[App Store Connect] → \[Users and Access] → \[Sandbox] → \[Testers], and a license tester in \[Play Console] → \[Setup] → \[License testing]. Purchases only work on a real device signed into one of those accounts.
8. Make a dev build - `npx expo run:ios`, `npx expo run:android`, or `eas build --profile development`. The module also patches the app config with `["expo-build-properties", { ios: { useFrameworks: "dynamic" } }]`, which the SDK's Swift Package dependencies require.

<Callout type="info" title="Going to production?">
  Make sure every product id exists and is approved in App Store Connect and Play Console - a product that only lives in Adapty never shows a price. Check that the paywall you want live is the one attached to the placement `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID` reads, because that's the only one the app asks for.
</Callout>

9. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                               | Where to get it                                                                     |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`   | Adapty → App settings → General → Public SDK key (`public_live_…`)                  |
| `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID` | Adapty → Placements → the placement your paywall is attached to (default `default`) |

Dashboards: [App settings](https://app.adapty.io/settings/general) · [Products](https://app.adapty.io/products) · [Paywalls](https://app.adapty.io/paywalls) · [Placements](https://app.adapty.io/placements) · [App Store Connect sandbox testers](https://appstoreconnect.apple.com/access/users/sandbox) · [Play Console license testers](https://play.google.com/console). Deps: `react-native-adapty` ^4.1.0 (RN ≥ 0.75, one package for the SDK and the Paywall Builder UI) and `expo-build-properties`.

## Usage [#usage]

Gate a feature on an access level:

```ts
import { payments } from "@/lib/payments";

const { active, loading } = payments.useEntitlements(); // active: ["premium"]
if (!loading && !active.includes("premium")) await payments.presentPaywall?.();
```

Sell from your own screen:

```ts
import { getPaywallFlow, getPaywallProducts, purchaseProduct } from "@/lib/payments";

const flow = await getPaywallFlow();
const products = await getPaywallProducts(flow);
const bought = await purchaseProduct(products[0]); // false when the user cancels or the purchase is pending
```

Restore, which the stores require you to offer:

```ts
import { payments } from "@/lib/payments";

await payments.restorePurchases();
```

`presentPaywall()` shows the no-code paywall when the flow has a view configuration; a remote-config-only paywall opens `/paywall`, which lists the placement's products instead.

## Gotchas [#gotchas]

* Expo Go can't run this module - native StoreKit and Play Billing need a dev build. In Expo Go the SDK falls back to its mock mode: no real products, no purchases.
* `expo-build-properties` `ios.useFrameworks: "dynamic"` applies to the whole iOS project. If another native library refuses dynamic frameworks, follow its docs (usually a `use_frameworks! :linkage => :dynamic` exception) - Adapty SDK 4.x needs the setting.
* `react-native-adapty` has no JS implementation of the bridge under jest. The root `__mocks__` file is picked up automatically - don't add `jest.mock()` for it.
* `adapty.activate()` throws when called twice, so the provider passes `__ignoreActivationOnFastRefresh` in dev.
* `adapty.activate()` also passes `ipAddressCollectionDisabled: !features.tracking`, `ios: { idfaCollectionDisabled: !features.tracking }` and `android: { adIdCollectionDisabled: !features.tracking }`, so Adapty collects no IDFA, GAID or IP address unless `features.tracking` is on in `readynative.config.ts`.
* `presentPaywall()` resolves once the view is presented, not when it closes; entitlements arrive through `onLatestProfileLoad` or the view's `onPurchaseCompleted` handler.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Set up the dashboard as above: app, bundle id and package, products, the `premium` access level, and a paywall with a monthly product attached to the placement.
2. Put `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY` in `.env` and run `npx expo run:ios` on a real device signed into a sandbox Apple ID (Settings → App Store → Sandbox Account).
3. Open Examples → "Paywall & entitlements" and expect "none active".
4. Tap "Open paywall": the Paywall Builder paywall appears (or `/paywall` when the paywall has no builder view) with the product and a localized price. Buy → sandbox sheet → confirm → the sheet closes with a toast "Purchase complete" and access levels show `premium`.
5. Delete and reinstall the app, then tap "Restore purchases": access levels show `premium` again.
6. Repeat on Android with a license-tester Google account.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --payments none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `__mocks__/react-native-adapty.ts`, `src/app/examples/paywall.tsx`, `src/app/paywall/_layout.tsx`, `src/app/paywall/index.tsx`, `src/lib/__tests__/payments-adapty.test.ts`, `src/screens/examples/paywall-example-screen.tsx`, `src/screens/paywall/paywall-screen.tsx`.
2. **Replace, don't delete** `src/lib/payments.ts`: core code imports it, so swap in the no-op version from `modules/payments/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove expo-build-properties react-native-adapty`.
4. **Drop the config plugin** `expo-build-properties` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<PaymentsProvider>` and its import from `src/providers.tsx`.
6. **Remove the env keys** `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`, `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`, `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID` from `src/lib/env.ts`.
7. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
8. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/payments/adapty/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --payments adapty
</Cmd>

Module id: `payments/adapty`.

### Dependencies [#dependencies]

| Package                 | Version    | Kind       |
| ----------------------- | ---------- | ---------- |
| `expo-build-properties` | `~57.0.17` | dependency |
| `react-native-adapty`   | `^4.1.0`   | dependency |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-build-properties` (with options)

### Environment keys [#environment-keys]

| Key                               | Required | Server-only | Example                                         | Docs                                                |
| --------------------------------- | -------- | ----------- | ----------------------------------------------- | --------------------------------------------------- |
| `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`   | yes      | no          | `public_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx` | [dashboard](https://app.adapty.io/settings/general) |
| `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID` | no       | no          | `default`                                       | [dashboard](https://app.adapty.io/placements)       |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects *Purchase history*, &#x2A;Profile id (anonymous by default)*, *Device info*; shared with Adapty (processor). Source of truth: [vendor disclosure](https://adapty.io/privacy/).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type              | Linked to user | Tracking | Purposes         |
| ----------------- | -------------- | -------- | ---------------- |
| `PurchaseHistory` | yes            | no       | AppFunctionality |
| `UserID`          | yes            | no       | AppFunctionality |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider           | From             |
| ----- | ------------------ | ---------------- |
| 70    | `PaymentsProvider` | `@/lib/payments` |

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_ADAPTY_PUBLIC_KEY`, `EXPO_PUBLIC_ADAPTY_PLACEMENT_ID`
* dev build toolchain (Xcode / Android SDK)

### After setup [#after-setup]

1. Adapty: create an app at [https://app.adapty.io](https://app.adapty.io), add the App Store bundle id and Play package name from readynative.config.ts (App settings → iOS SDK / Android SDK).
2. Adapty: copy the Public SDK key (App settings → General) into .env as EXPO\_PUBLIC\_ADAPTY\_PUBLIC\_KEY (one key serves both platforms).
3. Adapty: create Products (App Store Connect / Play Console product ids), keep the default access level `premium` (or rename it in src/lib/payments.ts), build a Paywall and attach it to a Placement; put the placement id into .env as EXPO\_PUBLIC\_ADAPTY\_PLACEMENT\_ID (defaults to `default`).
4. react-native-adapty is a native module and needs `expo-build-properties` with `ios.useFrameworks: "dynamic"` (added to app config by this module): make a dev build with `npx expo run:ios` / `npx expo run:android` (or `eas build --profile development`). Expo Go only runs the SDK's mock mode.

### Files [#files]

<details>
  <summary>
    8 files copied to the project root
  </summary>

  * `__mocks__/react-native-adapty.ts`
  * `src/app/examples/paywall.tsx`
  * `src/app/paywall/_layout.tsx`
  * `src/app/paywall/index.tsx`
  * `src/lib/__tests__/payments-adapty.test.ts`
  * `src/lib/payments.ts`
  * `src/screens/examples/paywall-example-screen.tsx`
  * `src/screens/paywall/paywall-screen.tsx`
</details>


# Payments (/docs/features/payments)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/payments/README.md - do not edit. */}

<Badge>
  Pro
</Badge>

Hey - here's how payments work in ReadyNative.

This category owns selling: the `/paywall` modal, the entitlement check you gate features on, and the Restore action the stores require you to offer.

`@/lib/payments` always exists, whichever option you pick: `payments.useEntitlements()`, `payments.presentPaywall?.()` and `payments.restorePurchases()` read the same in every one of them, and `payments/none` is a no-op that reports no entitlements. Screens you write against the shim keep working when you switch options.

Pick **RevenueCat** for the default path to store subscriptions - it handles StoreKit and Play Billing, and its remote paywalls can be edited without shipping an update. Pick **Adapty** if the no-code Paywall Builder and A/B tests on placements are what you want to iterate on; it's the same store billing underneath. Pick **Stripe** if you're selling to the web too, or if what you sell isn't digital goods that Apple and Google require in-app purchase for - it runs on hosted Checkout in the system browser, needs `backend/api-routes`, and is the one option that works in Expo Go.

This category is part of ReadyNative Pro.

## Options [#options]

One option per category - `--payments <option>` picks it:

<Cmd>
  bun run setup --payments revenuecat
</Cmd>

| Option                       | Label                | Expo Go                 | Hint                                                                     |
| ---------------------------- | -------------------- | ----------------------- | ------------------------------------------------------------------------ |
| [`revenuecat`](./revenuecat) | RevenueCat (default) | no - dev build required | in-app subscriptions + paywall · dev build required (no Expo Go)         |
| [`adapty`](./adapty)         | Adapty               | no - dev build required | in-app subscriptions + Paywall Builder · dev build required (no Expo Go) |
| [`stripe`](./stripe)         | Stripe Checkout      | yes                     | web checkout via API routes (no native SDK) · Expo Go OK                 |
| [`none`](./none)             | No payments          | yes                     | payments.useEntitlements() shim returns none                             |


# No payments (/docs/features/payments/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/payments/none - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="payments" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-op payments option: no paywall, no store products, no billing SDK. It owns `src/lib/payments.ts` as a re-export of the core shim, so `@/lib/payments` keeps the same API whichever option you pick - `payments.useEntitlements()` reports no entitlements, `restorePurchases()` resolves, and `presentPaywall` is `undefined`. Pick this while the app is free, or until you know which billing service you want.

## Setup [#setup]

```bash
bun run setup --payments none
```

There's nothing to configure and no keys to paste. Nothing native is installed either, so the app still runs in Expo Go.

When you're ready to charge, switch with `bun run setup --payments revenuecat`, `--payments adapty` or `--payments stripe`.

## Usage [#usage]

The calls exist and are safe to write today, so screens don't need rewriting when you switch:

```ts
import { payments } from "@/lib/payments";

const { active, loading } = payments.useEntitlements(); // always { active: [], loading: false }
await payments.presentPaywall?.(); // presentPaywall is undefined here, so this is a no-op
await payments.restorePurchases(); // resolves, does nothing
```

## Gotchas [#gotchas]

* Keep the `?.` on `presentPaywall`. It's optional in the contract precisely because this option doesn't provide one.
* Any feature gated on an entitlement stays locked while this option is selected, since `active` is always empty.

## Reference [#reference]

Everything below is generated from `modules/payments/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --payments none
</Cmd>

Module id: `payments/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/payments.ts`
</details>


# RevenueCat (/docs/features/payments/revenuecat)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/payments/revenuecat - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="payments" option="revenuecat" />

<Callout type="warn" title="Expo Go: no - dev build required">
  Ships native code. Make a dev build with `bunx expo run:ios` / `bunx expo run:android` (or `bunx eas-cli build --profile development`).
</Callout>

This gives you in-app subscriptions on both stores through RevenueCat: `src/lib/payments.ts` implements the shim on `react-native-purchases`, a `PaymentsProvider` (order 70) keeps the RevenueCat app user id on the signed-in user and listens for customer-info changes, and `/paywall` ships as a modal with your feature bullets, the current offering's packages and prices, Buy, the store's renewal terms, "Compare all plans", Restore, and Terms/Privacy links from `readynative.config.ts` `urls`. If you set up with `--with-examples` there's an example at `/examples/paywall` and jest mocks for both native packages. `@/lib/payments` keeps the same API whichever option you pick - pick RevenueCat when you want StoreKit and Play Billing handled for you, plus remote paywalls you can edit without shipping an update.

## Setup [#setup]

```bash
bun run setup --payments revenuecat
```

1. Create a project at [app.revenuecat.com](https://app.revenuecat.com), then add an App Store app and a Play Store app under \[Project settings] → \[Apps]. Use the bundle id from `readynative.config.ts` `app.ios.bundleId` (plus `.dev` for the dev variant) and the matching Android package.
2. Open \[Project settings] → \[API keys]. Copy the App Store key (`appl_…`) into `.env` as `EXPO_PUBLIC_REVENUECAT_IOS_KEY` and the Play Store key (`goog_…`) as `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY`. Both are public SDK keys. Without the key for the platform you're running, the module no-ops: `useEntitlements()` returns `{ active: [], loading: false }` and `/paywall` shows "Configure RevenueCat".
3. Create the products in \[App Store Connect] → \[Subscriptions] and \[Play Console] → \[Monetize] → \[Subscriptions], then add them in RevenueCat under \[Products].
4. Open \[Entitlements] and create one with the identifier `pro` (`PRO_ENTITLEMENT` in `src/lib/payments.ts` - change the constant if you pick another id), then attach your products to it.
5. Open \[Offerings], create an offering with a monthly package, and mark it **current**. The bundled paywall lists `offerings.current.availablePackages`.
6. Optional: design a paywall under \[Paywalls] in the RevenueCat dashboard and attach it to the current offering. `payments.presentPaywall()` shows it when it exists and falls back to the bundled `/paywall` route when it doesn't. The template RevenueCat pre-fills (a sample app such as "CatPrrro") is placeholder copy - replace the name, images and text before shipping, or your users will see it.
7. Add a sandbox tester in \[App Store Connect] → \[Users and Access] → \[Sandbox] → \[Testers], and a license tester in \[Play Console] → \[Setup] → \[License testing]. Purchases only work on a real device signed into one of those accounts.
8. Make a dev build - `npx expo run:ios`, `npx expo run:android`, or `eas build --profile development`. This module uses native StoreKit and Play Billing, so Expo Go can't run it.

<Callout type="info" title="Going to production?">
  Point the app at your production bundle id and package name in RevenueCat, and make sure every product id exists and is approved in App Store Connect and Play Console - a product that's only in RevenueCat never shows a price. Check that the offering you want live is the one marked **current**, since that's what the paywall reads.
</Callout>

9. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                                  | Where to get it                                                      |
| ------------------------------------ | -------------------------------------------------------------------- |
| `EXPO_PUBLIC_REVENUECAT_IOS_KEY`     | RevenueCat → Project settings → API keys → App Store app (`appl_…`)  |
| `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY` | RevenueCat → Project settings → API keys → Play Store app (`goog_…`) |

Dashboards: [API keys](https://app.revenuecat.com/settings/api-keys) · Products, Entitlements and Offerings in the project sidebar · [Paywalls](https://app.revenuecat.com/paywalls) · [App Store Connect sandbox testers](https://appstoreconnect.apple.com/access/users/sandbox) · [Play Console license testers](https://play.google.com/console). Deps: `react-native-purchases` ^10.9.1 and `react-native-purchases-ui` ^10.9.1 (RN ≥ 0.73, no config plugin).

## Usage [#usage]

Gate a feature on an entitlement:

```ts
import { payments } from "@/lib/payments";

const { active, loading } = payments.useEntitlements(); // active: ["pro"]
if (!loading && !active.includes("pro")) await payments.presentPaywall?.();
```

Sell from your own screen:

```ts
import { getCurrentPackages, purchasePackage } from "@/lib/payments";

const packages = await getCurrentPackages();
const bought = await purchasePackage(packages[0]); // false when the user cancels
```

Restore, which the stores require you to offer:

```ts
import { payments } from "@/lib/payments";

await payments.restorePurchases();
```

Let subscribers manage or cancel, e.g. from a "Pro" row in your settings screen (the bundled `/paywall` shows the button in its "You are Pro" state):

```ts
import { manageSubscription, payments, PRO_ENTITLEMENT } from "@/lib/payments";

const { active } = payments.useEntitlements();
if (active.includes(PRO_ENTITLEMENT)) await manageSubscription(); // Apple's / Google's page
```

Show the dashboard paywall even to Pro users (a "Compare all plans" link, a debug menu):

```ts
import { presentNativePaywall } from "@/lib/payments";

const result = await presentNativePaywall({ force: true }); // "purchased" | "restored" | "cancelled" | "error" | "unavailable"
```

`"error"` means the paywall was shown and a purchase or restore inside it failed - the paywall already told the user, so don't show anything else. Only `"unavailable"` (nothing was shown: no paywall designed, offline, no key) warrants a fallback.

Entitlement ids are whatever you named them in RevenueCat. `PRO_ENTITLEMENT` (`"pro"`) is the one `presentPaywall()` checks: users who already have it skip the native paywall and land on `/paywall`'s "You are Pro" state.

With an auth module, `PaymentsProvider` reads `auth.useSession()` and calls `Purchases.logIn(user.id)` on sign-in and `Purchases.logOut()` on sign-out, so purchases follow the account across devices (and can match a server-side rail such as Stripe). Without one the app user stays anonymous. Entitlements read `loading` while a switch is in flight and never show the previous account's. Switches run one at a time and always end on the latest session user; a failed `logIn` / `logOut` is retried when the app returns to the foreground, and customer-info updates are ignored until it succeeds.

## Gotchas [#gotchas]

* Expo Go can't run this module - native StoreKit and Play Billing need a dev build.
* `required` is `false` in the module's `env[]` on purpose: `src/lib/env.ts` would throw at startup for a missing required key. `bun run doctor` still reports the keys.
* `react-native-purchases` 10.x has no JS implementation under jest. The root `__mocks__` files are picked up automatically - don't add `jest.mock()` for them.
* `presentPaywall()` returns when the sheet closes; entitlements arrive a moment later through the customer-info listener.
* Every function in `@/lib/payments` configures the SDK on first use. Screens' effects run before `PaymentsProvider`'s, so a cold start deep-linked to `/paywall` would otherwise crash with "There is no singleton instance".
* Which purchase sheet you see depends on the key. A Test Store key (`test_…`) shows RevenueCat's own "Test Store Purchase" dialog - no App Store Connect setup needed, handy in the simulator. The App Store key (`appl_…`), with the products created in App Store Connect and a sandbox Apple ID on the device, shows Apple's real sheet. Ship with `appl_` / `goog_` keys only. A `test_` key in a **Release** build (TestFlight, store, or `expo run:ios --configuration Release`) makes the SDK show a "Wrong API Key" alert and close the app on launch - keep Test Store keys to development builds.
* The native paywall shows whatever is designed in \[Paywalls]. Until you design one it's RevenueCat's sample template, so check it before release - "Compare all plans" opens it on purpose.
* App Review 3.1.2 wants the renewal terms next to the price: `/paywall` prints them under the packages (Apple ID + 24-hour cancellation on iOS, Google Play wording on Android). Keep them if you build your own paywall, and keep a way to manage the subscription (`manageSubscription()`).
* The store sheet is in-app purchase, not Apple Pay: it charges the Apple ID's payment method (which may be an Apple Pay card). Apple Pay proper is only allowed for physical goods and services.
* RevenueCat starts with an anonymous app user id; `PaymentsProvider` switches it to the signed-in user's id. What happens to a purchase made anonymously before sign-in is RevenueCat's call - see [Identifying customers](https://www.revenuecat.com/docs/customers/identifying-customers) and the project's restore behavior setting.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. Set up the dashboard as above: project, iOS app, products, the `pro` entitlement, and an offering with a monthly package marked current.
2. Put both keys in `.env` and run `npx expo run:ios` on a real device signed into a sandbox Apple ID (Settings → App Store → Sandbox Account).
3. Open Examples → "Paywall & entitlements" and expect "none active".
4. Tap "Open paywall": the RevenueCat paywall appears (or `/paywall` when none is configured) with the package and a localized price. Buy → sandbox sheet → confirm → toast "Purchase complete" and entitlements show `pro`.
5. Tap "Open paywall" again: no native paywall this time, `/paywall` shows "You are Pro". "Manage subscription" opens the store's subscriptions page.
6. Delete and reinstall the app, then tap "Restore purchases": entitlements show `pro` again.
7. Repeat on Android with a license-tester Google account and `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY` set.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --payments none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `__mocks__/react-native-purchases-ui.ts`, `__mocks__/react-native-purchases.ts`, `src/app/examples/paywall.tsx`, `src/app/paywall/_layout.tsx`, `src/app/paywall/index.tsx`, `src/lib/__tests__/payments-revenuecat.test.ts`, `src/screens/examples/paywall-example-screen.tsx`, `src/screens/paywall/paywall-screen.tsx`.
2. **Replace, don't delete** `src/lib/payments.ts`: core code imports it, so swap in the no-op version from `modules/payments/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove react-native-purchases react-native-purchases-ui`.
4. **Unwrap the provider**: delete `<PaymentsProvider>` and its import from `src/providers.tsx`.
5. **Remove the env keys** `EXPO_PUBLIC_REVENUECAT_IOS_KEY`, `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_REVENUECAT_IOS_KEY`, `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY` from `src/lib/env.ts`.
6. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
7. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/payments/revenuecat/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --payments revenuecat
</Cmd>

Module id: `payments/revenuecat` (the default for this category).

### Dependencies [#dependencies]

| Package                     | Version    | Kind       |
| --------------------------- | ---------- | ---------- |
| `react-native-purchases`    | `^10.10.1` | dependency |
| `react-native-purchases-ui` | `^10.10.1` | dependency |

### Environment keys [#environment-keys]

| Key                                  | Required | Server-only | Example                           | Docs                                                      |
| ------------------------------------ | -------- | ----------- | --------------------------------- | --------------------------------------------------------- |
| `EXPO_PUBLIC_REVENUECAT_IOS_KEY`     | yes      | no          | `appl_xxxxxxxxxxxxxxxxxxxxxxxxxx` | [dashboard](https://app.revenuecat.com/settings/api-keys) |
| `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY` | yes      | no          | `goog_xxxxxxxxxxxxxxxxxxxxxxxxxx` | [dashboard](https://app.revenuecat.com/settings/api-keys) |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects *Purchase history*, &#x2A;App user id (anonymous by default)*, *Device info*; shared with RevenueCat (processor). Source of truth: [vendor disclosure](https://www.revenuecat.com/docs/platform-resources/google-play-data-safety).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type              | Linked to user | Tracking | Purposes         |
| ----------------- | -------------- | -------- | ---------------- |
| `PurchaseHistory` | yes            | no       | AppFunctionality |
| `UserID`          | yes            | no       | AppFunctionality |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider           | From             |
| ----- | ------------------ | ---------------- |
| 70    | `PaymentsProvider` | `@/lib/payments` |

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_REVENUECAT_IOS_KEY`, `EXPO_PUBLIC_REVENUECAT_ANDROID_KEY`
* dev build toolchain (Xcode / Android SDK)

### After setup [#after-setup]

1. RevenueCat: create a project at [https://app.revenuecat.com](https://app.revenuecat.com), add an App Store app (bundle id from readynative.config.ts) and a Play Store app (package name).
2. RevenueCat: copy the public SDK keys (Project settings → API keys) into .env as EXPO\_PUBLIC\_REVENUECAT\_IOS\_KEY / EXPO\_PUBLIC\_REVENUECAT\_ANDROID\_KEY.
3. RevenueCat: create Products (App Store Connect / Play Console product ids), an Entitlement (e.g. `pro`) and an Offering marked as current; `/paywall` lists the current offering's packages.
4. react-native-purchases is a native module: make a dev build with `npx expo run:ios` / `npx expo run:android` (or `eas build --profile development`). Expo Go will not load it.

### Files [#files]

<details>
  <summary>
    9 files copied to the project root
  </summary>

  * `__mocks__/react-native-purchases-ui.ts`
  * `__mocks__/react-native-purchases.ts`
  * `src/app/examples/paywall.tsx`
  * `src/app/paywall/_layout.tsx`
  * `src/app/paywall/index.tsx`
  * `src/lib/__tests__/payments-revenuecat.test.ts`
  * `src/lib/payments.ts`
  * `src/screens/examples/paywall-example-screen.tsx`
  * `src/screens/paywall/paywall-screen.tsx`
</details>


# Stripe Checkout (/docs/features/payments/stripe)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/payments/stripe - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="payments" option="stripe" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This sells subscriptions through Stripe's hosted Checkout in the system browser, so there's no native payments SDK at all (`@stripe/stripe-react-native` is deliberately not used). `src/lib/payments.ts` implements the shim - entitlements come from `GET /api/stripe/entitlements` for whoever the request's session proves - and the server side lives in your tree: `src/app/api/stripe/{checkout,entitlements,webhook,return}+api.ts` with the shared logic in `src/server/stripe.ts`. You also get `/paywall` as a modal, tests for both halves, and `/examples/paywall` with `--with-examples`. `@/lib/payments` keeps the same API whichever option you pick - pick Stripe when you're selling to the web as well, or when the 30% store cut isn't something you have to pay.

## Setup [#setup]

```bash
bun run setup --payments stripe --backend api-routes
```

1. Serve the API routes. This module requires `backend/api-routes` (it sets `web.output: "server"`), so setup refuses `--payments stripe` with any other backend. Without `EXPO_PUBLIC_API_URL` pointing at that server the paywall shows "Configure Stripe". Put the origin in `.env` as `EXPO_PUBLIC_API_URL`: your EAS Hosting URL, or `http://<lan-ip>:8081` while `npx expo start` runs. In a dev build you can leave it unset - `src/lib/env.ts` falls back to the Metro dev server that shipped the bundle (http on a LAN host, https on a tunnel host).
2. In Stripe, open \[Developers] → \[API keys] in **test mode**. Copy the secret key into `.env` as `STRIPE_SECRET_KEY` (never with an `EXPO_PUBLIC_` prefix) and the publishable key as `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY` - hosted Checkout doesn't use the publishable key, but it's there for a Payment Sheet upgrade later.
3. Open \[Products], create a product with a recurring price, and copy the price id (`price_…`) into `.env` as `STRIPE_PRICE_ID`.
4. Open \[Developers] → \[Webhooks], add an endpoint at `<EXPO_PUBLIC_API_URL>/api/stripe/webhook`, and copy its signing secret (`whsec_…`) into `.env` as `STRIPE_WEBHOOK_SECRET`. Locally, run `stripe listen --forward-to localhost:8081/api/stripe/webhook` and use the secret it prints.
5. Optional: set `STRIPE_ENTITLEMENT` in `.env` to the entitlement id an active subscription grants. It defaults to `pro`.
6. Fill in the server keys in `.env`. They're marked `server: true` in the module, so `.env.example` lists them under a separate "server" section and `src/lib/env.ts` never includes them - they're read through `process.env` in the `+api.ts` files only. `bun run doctor` checks all five.
7. Pick an auth module. The `checkout` and `entitlements` routes work out who is paying on the server, from the session - see "Who the routes charge" below. With `auth/clerk`, also set `CLERK_SECRET_KEY` (server) so the routes can verify Clerk's session token.

<Callout type="info" title="Going to production?">
  Switch Stripe out of test mode and redo steps 2-4 with live values: a live `sk_…`, a live `price_…`, and a webhook endpoint pointing at your deployed origin with its own `whsec_…`. Set `EXPO_PUBLIC_API_URL` to that https origin, and store the server keys in EAS (`eas env:set --environment production --visibility sensitive`; `secret` variables don't deploy to EAS Hosting), not in `.env`. Leave `STRIPE_ALLOW_ANONYMOUS` unset.
</Callout>

8. Run `bun run doctor` - every row for this module should be green.

The keys, in one place:

| Key                                     | Where                                                                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL`                   | Origin that serves `src/app/api/**` (EAS Hosting URL, or `http://<lan-ip>:8081` in dev)                                            |
| `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY`    | [Developers → API keys](https://dashboard.stripe.com/apikeys) (`pk_…`; unused by hosted Checkout, kept for Payment Sheet upgrades) |
| `STRIPE_SECRET_KEY` (server)            | same page, `sk_…` - never `EXPO_PUBLIC_`                                                                                           |
| `STRIPE_PRICE_ID` (server)              | [Products](https://dashboard.stripe.com/products) → price `price_…` (recurring)                                                    |
| `STRIPE_WEBHOOK_SECRET` (server)        | [Webhooks](https://dashboard.stripe.com/webhooks) → endpoint `<API_URL>/api/stripe/webhook` → signing secret `whsec_…`             |
| `STRIPE_ENTITLEMENT` (server, opt.)     | Entitlement id an active subscription grants; default `pro`                                                                        |
| `STRIPE_ALLOW_ANONYMOUS` (server, opt.) | `true` trusts the client's `customer` id, only with `auth/none` - demos only, see "Who the routes charge"                          |

Deps: `stripe` ^22.6.2, server-side and pure JS. Expo Go works, since Checkout runs in the system browser.

How the round trip goes: Subscribe → `POST /api/stripe/checkout { returnUrl }` with the session headers → a Checkout session for the verified user (`mode: subscription`, `subscription_data.metadata.app_user_id`) → the browser → Stripe redirects to `/api/stripe/return?checkout=success&to=<returnUrl>` → that page bounces to the app scheme → the auth session closes → entitlements are refetched. Entitlements are a subscription search on `metadata['app_user_id']` with status `active` or `trialing`, mapped to `[STRIPE_ENTITLEMENT]`, so no database is required. Persist them in `handleStripeEvent` if you add one.

### Who the routes charge [#who-the-routes-charge]

The app never tells the server who it is paying for. Every request from `src/lib/payments.ts` carries `auth.getAuthHeaders()`, and `resolveCaller()` in `src/server/stripe.ts` turns those back into a user through the auth module's `src/server/session.ts` (`serverAuth.getRequestUser(request)`):

| Auth module        | Header the app sends                       | How the server checks it                                                           |
| ------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------- |
| `auth/better-auth` | `cookie` (session cookie from SecureStore) | `auth.api.getSession({ headers })` against Better Auth's session table             |
| `auth/supabase`    | `authorization: Bearer <access token>`     | `supabase.auth.getUser(jwt)` with the project's URL + anon key                     |
| `auth/clerk`       | `authorization: Bearer <session token>`    | `verifyToken()` from `@clerk/backend` with `CLERK_SECRET_KEY` (or `CLERK_JWT_KEY`) |
| `auth/none`        | nothing                                    | nobody can be verified                                                             |

* No verified user → `401 Sign in required`, whatever `customer` the request claims. A signed-in user's own id always wins over the `customer` field.
* The server can't verify at all (for example Clerk without `CLERK_SECRET_KEY`) → `503`, so a misconfiguration doesn't look like a signed-out user.
* With `auth/none` the routes refuse by default. `STRIPE_ALLOW_ANONYMOUS=true` makes them trust the `customer` id the client sends (`?customer=` / body `customer`) - anyone can then buy for, or read the entitlements of, any id. That's for demos, or an app whose ids you accept as guessable; it has no effect once an auth module is selected.
* Your own API routes can use the same helper: `const user = await serverAuth.getRequestUser(request)` from `@/server/session`.

## Usage [#usage]

Gate a feature on an entitlement:

```ts
import { payments } from "@/lib/payments";

const { active, loading } = payments.useEntitlements(); // active: ["pro"]
if (!loading && !active.includes("pro")) await payments.presentPaywall?.();
```

Start Checkout from your own screen:

```ts
import { startCheckout, getPrice, formatPrice } from "@/lib/payments";

const { price } = await getPrice();
// session.user.id keys the local entitlements cache; the server charges the verified session user.
const result = await startCheckout(session.user.id); // "success" | "cancel" | "dismiss"
```

Refresh after a purchase, which is also what Restore does here:

```ts
import { payments } from "@/lib/payments";

await payments.restorePurchases();
```

## Gotchas [#gotchas]

* A `401` from `checkout` or `entitlements` means the session didn't reach or didn't verify on the server: check that the app and the API talk to the same auth backend (for Better Auth, `BETTER_AUTH_URL` = the API origin), and that the auth module's server keys are set where the API runs (EAS Hosting env, not just `.env`).
* The custom-scheme bounce needs `app.scheme` in `readynative.config.ts`; in Expo Go the `exp://` return URL is accepted too.
* Apple and Google require in-app purchase for digital goods sold inside the app. Check the store rules for what you're selling before you ship Checkout as the only path: a Stripe link-out for digital goods is allowed on the US App Store storefront, elsewhere only with Apple's external purchase entitlement. `examples/snap-recipe` runs Checkout next to RevenueCat (`src/lib/store-purchases.ts`) with one merged entitlement set.
* On a physical iPhone, `EXPO_PUBLIC_API_URL` must be `https://` unless it is a LAN IP, `localhost`, `*.local` or a dot-less host name - App Transport Security blocks plain http to anything else ("requires the use of a secure connection"), including `expo start --tunnel` hosts. Tunnels and EAS Hosting serve https, so switch the scheme rather than the host. The paywall turns that failure into this advice instead of the raw `NSURLError`, and `src/lib/env.ts` warns about it in dev.
* Apple Pay needs no code: turn it on in Stripe → \[Settings] → \[Payment methods] and hosted Checkout offers it automatically. The button renders in the iOS Simulator, but the Apple Pay sheet needs a card in Wallet, so test it on a real iPhone.

Check it works (the Examples steps need a tree set up with `--with-examples`):

1. In Stripe test mode, create the product and recurring price for `STRIPE_PRICE_ID`, set `STRIPE_SECRET_KEY`, run the API (`npx expo start` with api-routes, or deploy to EAS Hosting), and point `EXPO_PUBLIC_API_URL` at its LAN or public origin.
2. Run `stripe listen --forward-to localhost:8081/api/stripe/webhook` and paste the printed `whsec_…` into `STRIPE_WEBHOOK_SECRET`.
3. Sign in with an auth module - with a null user the paywall shows "Sign in to subscribe". Examples → "Paywall & entitlements" reads "none active". `curl <API_URL>/api/stripe/entitlements?customer=<your user id>` without the session answers `401`.
4. Tap "Open paywall" → a card with the product name and price → Subscribe → the browser opens Checkout → pay with `4242 4242 4242 4242` → the "Payment complete" page bounces back → toast "Subscription active" and entitlements show `pro`; `stripe listen` prints `checkout.session.completed` → 200.
5. Cancel in Checkout → you return with the toast "Checkout cancelled"; swipe the browser away → nothing changes.
6. Cancel the subscription in the dashboard, then tap "Restore purchases" → `none active`.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --payments none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/api/stripe/checkout+api.ts`, `src/app/api/stripe/entitlements+api.ts`, `src/app/api/stripe/return+api.ts`, `src/app/api/stripe/webhook+api.ts`, `src/app/examples/paywall.tsx`, `src/app/paywall/_layout.tsx`, `src/app/paywall/index.tsx`, `src/lib/__tests__/payments-stripe.test.ts`, `src/screens/examples/paywall-example-screen.tsx`, `src/screens/paywall/paywall-screen.tsx`, `src/server/__tests__/stripe-routes.test.ts`, `src/server/stripe.ts`.
2. **Replace, don't delete** `src/lib/payments.ts`: core code imports it, so swap in the no-op version from `modules/payments/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove stripe`.
4. **Unwrap the provider**: delete `<PaymentsProvider>` and its import from `src/providers.tsx`.
5. **Remove the env keys** `EXPO_PUBLIC_API_URL`, `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID`, `STRIPE_ALLOW_ANONYMOUS` from `.env`, `.env.example` and your EAS environment, and `EXPO_PUBLIC_API_URL`, `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY` from `src/lib/env.ts`.
6. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
7. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/payments/stripe/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --payments stripe
</Cmd>

Module id: `payments/stripe`.

### Dependencies [#dependencies]

| Package  | Version   | Kind       |
| -------- | --------- | ---------- |
| `stripe` | `^22.6.2` | dependency |

### Environment keys [#environment-keys]

| Key                                  | Required | Server-only | Example                            | Docs                                                            |
| ------------------------------------ | -------- | ----------- | ---------------------------------- | --------------------------------------------------------------- |
| `EXPO_PUBLIC_API_URL`                | no       | no          | `https://your-app.expo.app`        | [dashboard](https://docs.expo.dev/router/reference/api-routes/) |
| `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY` | yes      | no          | `pk_test_xxxxxxxxxxxxxxxxxxxxxxxx` | [dashboard](https://dashboard.stripe.com/apikeys)               |
| `STRIPE_SECRET_KEY`                  | yes      | yes         | `sk_test_xxxxxxxxxxxxxxxxxxxxxxxx` | [dashboard](https://dashboard.stripe.com/apikeys)               |
| `STRIPE_WEBHOOK_SECRET`              | yes      | yes         | `whsec_xxxxxxxxxxxxxxxxxxxxxxxx`   | [dashboard](https://dashboard.stripe.com/webhooks)              |
| `STRIPE_PRICE_ID`                    | yes      | yes         | `price_xxxxxxxxxxxxxxxxxxxxxxxx`   | [dashboard](https://dashboard.stripe.com/products)              |
| `STRIPE_ALLOW_ANONYMOUS`             | no       | yes         | `false`                            | [dashboard](https://docs.stripe.com/payments/checkout)          |

Keys go in `.env` (see `.env.example`). `Required` keys are checked by `bun run doctor`; `Server-only` keys have no `EXPO_PUBLIC_` prefix, are read only by API routes and never reach the bundle.

### Privacy [#privacy]

Play Data safety draft: collects &#x2A;Payment info (entered in Stripe's hosted checkout, never in the app)*, *Email address*, &#x2A;User id (customer metadata)*; shared with Stripe (processor). Source of truth: [vendor disclosure](https://stripe.com/privacy).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type              | Linked to user | Tracking | Purposes         |
| ----------------- | -------------- | -------- | ---------------- |
| `PurchaseHistory` | yes            | no       | AppFunctionality |
| `EmailAddress`    | yes            | no       | AppFunctionality |
| `UserID`          | yes            | no       | AppFunctionality |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider           | From             |
| ----- | ------------------ | ---------------- |
| 70    | `PaymentsProvider` | `@/lib/payments` |

### Compatibility [#compatibility]

* Requires `backend` = [`api-routes`](https://readynative.app/docs/features/backend/api-routes)

### Doctor checks [#doctor-checks]

* env: `EXPO_PUBLIC_API_URL`, `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID`

### After setup [#after-setup]

1. Stripe: create a Product with a recurring Price at [https://dashboard.stripe.com/products](https://dashboard.stripe.com/products) and copy the price id (price\_...) into .env as STRIPE\_PRICE\_ID (server-only, no EXPO\_PUBLIC\_ prefix).
2. Stripe: copy the secret key (sk\_test\_...) from [https://dashboard.stripe.com/apikeys](https://dashboard.stripe.com/apikeys) into .env as STRIPE\_SECRET\_KEY, and the publishable key as EXPO\_PUBLIC\_STRIPE\_PUBLISHABLE\_KEY.
3. Stripe: add a webhook endpoint `<API_URL>/api/stripe/webhook` at [https://dashboard.stripe.com/webhooks](https://dashboard.stripe.com/webhooks) (events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted) and put its signing secret (whsec\_...) into .env as STRIPE\_WEBHOOK\_SECRET. Locally: `stripe listen --forward-to localhost:8081/api/stripe/webhook`.
4. Stripe: the routes under src/app/api/stripe/ only run with `backend/api-routes` (web.output "server"); set EXPO\_PUBLIC\_API\_URL to that server's origin. Without it the paywall shows "Configure Stripe".
5. Stripe: checkout needs a signed-in user - pick an auth module. The API routes resolve the caller server-side from the session (src/server/session.ts, sent via auth.getAuthHeaders()), never from a client-supplied id; with auth `none` they answer 401 unless you set STRIPE\_ALLOW\_ANONYMOUS=true (trusts client ids - demos only).

### Files [#files]

<details>
  <summary>
    13 files copied to the project root
  </summary>

  * `src/app/api/stripe/checkout+api.ts`
  * `src/app/api/stripe/entitlements+api.ts`
  * `src/app/api/stripe/return+api.ts`
  * `src/app/api/stripe/webhook+api.ts`
  * `src/app/examples/paywall.tsx`
  * `src/app/paywall/_layout.tsx`
  * `src/app/paywall/index.tsx`
  * `src/lib/__tests__/payments-stripe.test.ts`
  * `src/lib/payments.ts`
  * `src/screens/examples/paywall-example-screen.tsx`
  * `src/screens/paywall/paywall-screen.tsx`
  * `src/server/__tests__/stripe-routes.test.ts`
  * `src/server/stripe.ts`
</details>


# Expo Notifications (/docs/features/push/expo-notifications)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/push/expo-notifications - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="push" option="expo-notifications" />

<Callout type="warn" title="Expo Go: no - dev build required">
  Ships native code. Make a dev build with `bunx expo run:ios` / `bunx expo run:android` (or `bunx eas-cli build --profile development`).
</Callout>

This gives you remote and local push through Expo's push service: `src/lib/push.ts` implements the shim, `src/hooks/use-push-token.ts` is a provider-free store that checks permission and calls `getExpoPushTokenAsync({ projectId })` with the id from `Constants.expoConfig.extra.eas.projectId`, and `PushProvider` (order 80) installs the foreground handler, creates the Android `default` channel, and deep-links to `data.url` when a notification is tapped - including from a cold start. If you set up with `--with-examples` there's also an example screen at `/examples/push` with a copyable token and a local test notification. Either way you get a `bun run push:test` script that sends one message through Expo's API. `@/lib/push` keeps the same API whichever option you pick - pick this when you want push without running your own APNs and FCM plumbing.

## Setup [#setup]

```bash
bun run setup --push expo-notifications
```

1. Run `bunx eas-cli init`. It can't write into the dynamic `app.config.ts`, so it only prints the project id: paste it into `readynative.config.ts` → `app.easProjectId` (or set `EAS_PROJECT_ID`), and `app.config.ts` turns it into `extra.eas.projectId`, which is what the token request needs. With an empty project id the hook reports `unsupported` and warns in the console.
2. In the \[Apple Developer] portal, create a Push Notifications key, then run `eas credentials` → \[iOS] → \[Push Notifications] and upload it. Expo's guide is at [https://docs.expo.dev/push-notifications/push-notifications-setup/](https://docs.expo.dev/push-notifications/push-notifications-setup/).
3. In the \[Firebase console], open \[Project settings] → \[Service accounts], generate a private key, then run `eas credentials` → \[Android] → \[FCM V1] and upload the JSON.
4. Check the Android notification icon. The module adds the config plugin `["expo-notifications", { icon: "./assets/images/android-icon-monochrome.png", color: "#ffffff" }]`, and the status-bar icon has to be monochrome.
5. Make a dev build and install it on a **physical** phone: `eas build --profile development`, or `npx expo run:ios --device`. Since SDK 53 Expo Go doesn't receive remote push, and simulators never do.
6. There are no `EXPO_PUBLIC_*` keys to paste for this module. To send a test by hand, open [https://expo.dev/notifications](https://expo.dev/notifications), paste a token, and send.

<Callout type="info" title="Going to production?">
  The APNs key and the FCM v1 service account are per app, not per build profile - upload them once with `eas credentials` and every profile uses them. Store the tokens your users register on your own server, and send with `data: { url: "/some/route" }` so a tap lands people where you meant. Delivery errors show up in Expo's push receipts, not in the send response.
</Callout>

7. Run `bun run doctor` - every row for this module should be green.

The things to set up, in one place (no env keys here):

| What                      | Where                                                                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| EAS project id            | `eas init` prints it → `readynative.config.ts` `app.easProjectId`. [https://expo.dev/accounts/\[account\]/projects](https://expo.dev/accounts/\[account]/projects)                         |
| APNs key (iOS)            | `eas credentials` → iOS → Push Notifications key. [https://docs.expo.dev/push-notifications/push-notifications-setup/](https://docs.expo.dev/push-notifications/push-notifications-setup/) |
| FCM v1 service account    | Firebase console → Project settings → Service accounts → upload via `eas credentials` → Android → FCM V1                                                                                   |
| Push receipts / dashboard | [https://expo.dev/notifications](https://expo.dev/notifications) (paste a token to send a test)                                                                                            |

Deps: `expo-notifications`, `expo-device`, `expo-constants`, `expo-clipboard`, all installed with `npx expo install`.

## Usage [#usage]

Read the token and the permission status:

```tsx
import { push } from "@/lib/push";

const { token, status } = push.usePushToken(); // "loading" | "unsupported" | "denied" | "granted"
```

Ask for permission when it makes sense in your flow, not on first launch:

```ts
import { push } from "@/lib/push";

const granted = await push.requestPermission(); // true when granted; a token registers when remote push is possible
```

`push.sendTestNotification({ title, body })` schedules a local notification 3 seconds out (pass a second argument for another delay), asking for permission first; it resolves `false` when notifications aren't allowed. Settings → Developer tools uses it.

Send one from a server - or from your machine, with the bundled script:

```bash
bun run push:test "ExponentPushToken[xxx]" "Title" "Body" --url /settings
```

That's a POST to `https://exp.host/--/api/v2/push/send` with `{ to, title, body, data: { url } }`; `data.url` is the route the app opens on tap.

## Gotchas [#gotchas]

* Expo Go can't receive remote push since SDK 53 - no token on Android, and the iOS token only works with Expo's own credentials. The module degrades instead of crashing: `status` becomes `unsupported` or `denied`. Local notifications still work in Expo Go.
* `push:test` only reports the ticket. Delivery errors like `DeviceNotRegistered` or bad credentials show up in the receipts - follow the link the script prints.
* iOS `undetermined` and `denied` both report as `denied`, since the shim has no separate state. The button prompts in the first case and does nothing in the second.

Check it works - steps 2 to 7 use the example screen, so run this in a tree set up with `--with-examples`:

1. Link the EAS project (step 1 of Setup), then `eas credentials` for the APNs key and FCM v1, then `eas build --profile development` (or `npx expo run:ios --device`) and install it on a physical phone.
2. Open the app → Examples → Push notifications: the status reads "Permission not granted". Tap **Allow notifications** → the OS dialog → Allow → toast "Push enabled" and an `ExponentPushToken[...]` appears.
3. Tap **Copy token**, then on your computer run `bun run push:test "<token>" "Hi" "It works"` - it prints `Sent. Ticket …`.
4. Background the app: the banner arrives within seconds. Foreground it and send again: the banner still shows, thanks to the foreground handler.
5. Tap the banner → the app opens on `/examples/push` from `data.url`. Kill the app, send again, tap: the same screen from a cold start.
6. Tap **Schedule local test notification in 5s** and background the app: the local banner arrives after 5 seconds and takes you back to the screen. This one works in Expo Go too.
7. Deny permission in the OS settings and reopen: the status reads "Permission not granted", nothing crashes, and the button re-prompts (or points to settings on iOS).

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --push none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `scripts/push-test.ts`, `src/app/examples/push.tsx`, `src/hooks/__tests__/use-push-token.test.tsx`, `src/hooks/use-push-token.ts`, `src/lib/__tests__/push.test.tsx`, `src/screens/examples/push-example-screen.tsx`.
2. **Replace, don't delete** `src/lib/push.ts`: core code imports it, so swap in the no-op version from `modules/push/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove expo-notifications`.
4. **Drop the config plugin** `expo-notifications` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Unwrap the provider**: delete `<PushProvider>` and its import from `src/providers.tsx`.
6. **Delete the script** `push:test` from `package.json`.
7. **Update the privacy declarations**: remove this module's entries from `.readynative.json` → `modules.app.expo.ios.privacyManifests`, then re-run `bun run gen:privacy` and revise your store privacy answers.
8. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/push/expo-notifications/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --push expo-notifications
</Cmd>

Module id: `push/expo-notifications` (the default for this category).

### Dependencies [#dependencies]

| Package              | Version    | Kind                        |
| -------------------- | ---------- | --------------------------- |
| `expo-clipboard`     | `~57.0.2`  | dependency (`expo install`) |
| `expo-constants`     | `~57.0.19` | dependency (`expo install`) |
| `expo-device`        | `~57.0.2`  | dependency (`expo install`) |
| `expo-notifications` | `~57.0.18` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-notifications` (with options)

### Privacy [#privacy]

Play Data safety draft: collects &#x2A;Push token (device id)*; shared with Expo push service, APNs, FCM. Source of truth: [vendor disclosure](https://expo.dev/privacy).

Apple privacy manifest data types (composed into `ios.privacyManifests` by setup):

| Type       | Linked to user | Tracking | Purposes         |
| ---------- | -------------- | -------- | ---------------- |
| `DeviceID` | yes            | no       | AppFunctionality |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider       | From         |
| ----- | -------------- | ------------ |
| 80    | `PushProvider` | `@/lib/push` |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Doctor checks [#doctor-checks]

* dev build toolchain (Xcode / Android SDK)

### After setup [#after-setup]

1. Link an EAS project: `bunx eas-cli init` prints the project id but cannot write into the dynamic app.config.ts - paste it into readynative.config.ts `app.easProjectId` (CI: EAS\_PROJECT\_ID). app.config.ts derives `extra.eas.projectId` from it; getExpoPushTokenAsync needs it, and until then usePushToken() reports `unsupported`.
2. Run `eas credentials` and upload APNs (iOS) and FCM v1 service-account (Android) keys: [https://docs.expo.dev/push-notifications/push-notifications-setup/#get-credentials-for-development-builds](https://docs.expo.dev/push-notifications/push-notifications-setup/#get-credentials-for-development-builds)
3. Remote push needs a dev build on a physical device (`eas build --profile development` or `npx expo run:ios|android`); Expo Go only delivers local notifications.
4. On a device: `push.requestPermission()` then read `push.usePushToken().token` (or open /examples/push with `--with-examples`), and run `bun run push:test <token> "Title" "Body"` (or `npm run push:test`, `pnpm run push:test`, `yarn push:test` - it runs on plain node).

### Files [#files]

<details>
  <summary>
    7 files copied to the project root
  </summary>

  * `scripts/push-test.ts`
  * `src/app/examples/push.tsx`
  * `src/hooks/__tests__/use-push-token.test.tsx`
  * `src/hooks/use-push-token.ts`
  * `src/lib/__tests__/push.test.tsx`
  * `src/lib/push.ts`
  * `src/screens/examples/push-example-screen.tsx`
</details>


# Push notifications (/docs/features/push)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/push/README.md - do not edit. */}

<Badge>
  Pro
</Badge>

Hey - here's how push works in ReadyNative.

This category owns notifications: asking for permission, registering a token, showing a banner while the app is in the foreground, and opening the right route when someone taps one.

`@/lib/push` always exists, whichever option you pick: `push.usePushToken()` and `push.requestPermission()` read the same in both, and `push/none` is a no-op that reports `{ token: null, status: "unsupported" }`. Screens you write against the shim keep working when you switch options.

Pick **Expo Notifications** for push without running your own APNs and FCM plumbing: `eas credentials` holds the certificates, Expo's service does the sending, and the module handles tokens, the Android channel and deep links from a tap. It needs a dev build on a physical phone - Expo Go hasn't received remote push since SDK 53. Pick **none** until you have something worth notifying people about; asking for permission before then is the fastest way to have it denied forever.

This category is part of ReadyNative Pro.

## Options [#options]

One option per category - `--push <option>` picks it:

<Cmd>
  bun run setup --push expo-notifications
</Cmd>

| Option                                       | Label                        | Expo Go                 | Hint                                                                                               |
| -------------------------------------------- | ---------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| [`expo-notifications`](./expo-notifications) | Expo Notifications (default) | no - dev build required | Expo push service + local notifications · dev build required for remote push (Expo Go: local only) |
| [`none`](./none)                             | No push notifications        | yes                     | nothing registered                                                                                 |


# No push notifications (/docs/features/push/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/push/none - do not edit. */}

<Badge>
  Pro
</Badge>

<OptionBanner cat="push" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-op push option: nothing registers, no permission prompt ever appears, and there are no credentials to upload. It owns `src/lib/push.ts` as a re-export of the core shim, so `@/lib/push` keeps the same API whichever option you pick - `push.usePushToken()` returns `{ token: null, status: "unsupported" }` and `requestPermission()` resolves `false`. Pick this until you actually have something to notify people about.

## Setup [#setup]

```bash
bun run setup --push none
```

There's nothing to configure, no keys to paste, and no `eas credentials` to run.

When you want notifications, switch with `bun run setup --push expo-notifications`.

## Usage [#usage]

The calls exist and are safe to write today, so screens don't need rewriting when you switch:

```tsx
import { push } from "@/lib/push";

const { token, status } = push.usePushToken(); // always { token: null, status: "unsupported" }
const granted = await push.requestPermission(); // always false
```

## Gotchas [#gotchas]

* `status` is `"unsupported"`, the same value the real module reports on web and simulators - so a screen that handles it correctly here handles those cases too.
* Nothing here needs a dev build; Expo Go is fine.

## Reference [#reference]

Everything below is generated from `modules/push/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --push none
</Cmd>

Module id: `push/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/push.ts`
</details>


# State (/docs/features/state)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/state/README.md - do not edit. */}

Hey - here's how state works in ReadyNative. This category is about state shared between screens.
Local `useState` is always fine, and the built-in stores (`src/stores/create-store.ts`, a tiny
`useSyncExternalStore` helper) already back theme mode and onboarding - they never depend on
your choice here.

What stays the same: persistence goes through the storage adapter you picked in the `storage`
category, under `readynative:*` keys, and with `--with-examples` every option ships `src/stores/example-store.ts` plus the
`/examples/store` route as the shape to copy. Swap with `bun run setup --state <option>`.

* **zustand** - the default. Pick it when you think in stores and selectors; `persist` is already
  wired to your storage adapter.
* **jotai** - pick it when your state is lots of small independent values and you want derived
  state for free.
* **none** - keep the built-in stores and nothing else.

## Options [#options]

One option per category - `--state <option>` picks it:

<Cmd>
  bun run setup --state zustand
</Cmd>

| Option                 | Label             | Expo Go | Hint                                                        |
| ---------------------- | ----------------- | ------- | ----------------------------------------------------------- |
| [`zustand`](./zustand) | Zustand (default) | yes     | tiny stores, persisted on the storage adapter · Expo Go OK  |
| [`jotai`](./jotai)     | Jotai             | yes     | atomic state, persisted on the storage adapter · Expo Go OK |
| [`none`](./none)       | No state library  | yes     | built-in useSyncExternalStore stores only                   |


# Jotai (/docs/features/state/jotai)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/state/jotai - do not edit. */}

<OptionBanner cat="state" option="jotai" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Jotai gives you atoms: tiny pieces of state you compose, with persistence through `atomWithAppStorage` on your storage adapter. I'd pick it over `zustand` when your state is naturally lots of small independent values and you want derived state for free, and over `none` as soon as two screens share something. The built-in theme and onboarding stores stay on `createPersistedStore` in core either way.

## Setup [#setup]

```bash
bun run setup --state jotai
```

That's it - setup wires the storage bridge for you. It adds `src/stores/jotai-storage.ts` (`atomWithAppStorage(key, initial)`, plus `createJotaiStorage<Value>()` and `hasSyncStorage` for custom atoms), and a test, plus the example `src/stores/example-store.ts` and the `/examples/store` route and screen with `--with-examples`. There's no provider: atoms live in Jotai's default store. Add `<Provider>` from `jotai` in `src/providers.tsx` only if you need isolated stores - tests can use `createStore()` instead.

## Usage [#usage]

A persisted atom is one line:

```ts
export const settingsAtom = atomWithAppStorage("readynative:settings", { sound: true });
```

Its type is `Value | Promise<Value>` because the web path loads asynchronously. Read it with `useAtomValue` (which unwraps), or derive a sync view like this:

```ts
export const countAtom = unwrap(counterAtom, (prev) => prev ?? 0);
export const incrementAtom = atom(null, (get, set) => set(counterAtom, get(countAtom) + 1));
```

Prefer write-only action atoms like that over `set((prev) => …)`, so an updater never receives a promise. Outside React, use `getDefaultStore().get(countAtom)` and `.set(incrementAtom)`.

## Gotchas [#gotchas]

* Expo Go works - it's pure JS.
* A storage module has to be selected (`kv-store`, `mmkv` or `async-storage`).
* On web the first render shows the initial value until the async read resolves, and a write during that window overwrites the stored value (same as zustand `persist` on web).
* The module pins `jotai` ^2.x. Version 3.0.0 exists (2026-09-08) and the `jotai/vanilla/utils/atomWithStorage` type imports may move in it.
* Swapping stacks: `bun run setup --state none` (or `--state zustand`) removes the files and the dependency.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --state none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/store.tsx`, `src/screens/examples/store-example-screen.tsx`, `src/stores/__tests__/example-store.test.ts`, `src/stores/example-store.ts`, `src/stores/jotai-storage.ts`.
2. **Uninstall the dependencies**: `bun remove jotai`.
3. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/state/jotai/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --state jotai
</Cmd>

Module id: `state/jotai`.

### Dependencies [#dependencies]

| Package | Version   | Kind       |
| ------- | --------- | ---------- |
| `jotai` | `^2.20.3` | dependency |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Files [#files]

<details>
  <summary>
    5 files copied to the project root
  </summary>

  * `src/app/examples/store.tsx`
  * `src/screens/examples/store-example-screen.tsx`
  * `src/stores/__tests__/example-store.test.ts`
  * `src/stores/example-store.ts`
  * `src/stores/jotai-storage.ts`
</details>


# No state library (/docs/features/state/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/state/none - do not edit. */}

<OptionBanner cat="state" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Only the built-in stores remain - `src/stores/create-store.ts`, a tiny `useSyncExternalStore` helper that backs theme mode and onboarding. I'd keep this while local `useState` and those two stores are enough; there's no extra dependency and nothing to learn. With `--with-examples`, `/examples/store` shows the core "Module not installed" screen.

## Setup [#setup]

```bash
bun run setup --state none
```

That's it - there's nothing to configure.

## Usage [#usage]

`createPersistedStore` in `src/stores/create-store.ts` is the pattern to copy if you need one more shared value: it persists through `@/lib/storage` and exposes a `useStore()` hook plus `useHydrated()`.

## Gotchas [#gotchas]

* Reach for a library once you have derived state, selectors or many small stores: `bun run setup --state zustand` (stores and selectors) or `--state jotai` (atoms). Both bring a persistence bridge and an example route.

## Reference [#reference]

Everything below is generated from `modules/state/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --state none
</Cmd>

Module id: `state/none`.


# Zustand (/docs/features/state/zustand)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/state/zustand - do not edit. */}

<OptionBanner cat="state" option="zustand" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Zustand gives you small global stores with a hook-shaped API and a `persist` middleware already pointed at your storage adapter. I'd pick it over `jotai` when you think in stores and selectors rather than in atoms, and over `none` as soon as two screens need to share state. It doesn't replace the built-in stores: theme mode and onboarding stay on `createPersistedStore` in core.

## Setup [#setup]

```bash
bun run setup --state zustand
```

That's it - setup wires the storage bridge for you. It adds `src/stores/zustand-storage.ts` (a `StateStorage` on the app storage adapter, sync on native and async on web), and a test, plus the example `src/stores/example-store.ts` and the `/examples/store` route and screen with `--with-examples`.

## Usage [#usage]

A persisted store looks like this (`src/stores/example-store.ts` with `--with-examples`):

```ts
import { create } from "zustand";
import { createJSONStorage, persist } from "zustand/middleware";
import { zustandStorage } from "./zustand-storage";

export const useCounterStore = create<CounterState>()(
  persist(
    (set) => ({
      count: 0,
      increment: () => set((s) => ({ count: s.count + 1 })),
      reset: () => set({ count: 0 }),
    }),
    {
      name: "readynative:counter",
      storage: createJSONStorage(() => zustandStorage),
      partialize: (s) => ({ count: s.count }),
    }
  )
);
```

Select a slice in components so you only re-render on what you read:

```tsx
const count = useCounterStore((s) => s.count);
```

Outside React, reach for `useCounterStore.getState().increment()`.

## Gotchas [#gotchas]

* Expo Go works - it's pure JS.
* A storage module has to be selected (`kv-store`, `mmkv` or `async-storage`); `persist` writes through whichever one you picked.
* On web the adapter is async, so the first render shows the initial state until hydration finishes. Gate first paint on hydration if a wrong first frame would be visible.
* Swapping stacks: `bun run setup --state none` (or `--state jotai`) removes the files and the dependency.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --state none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there (the demo screens are gone already unless you set up with `--with-examples`): `src/app/examples/store.tsx`, `src/screens/examples/store-example-screen.tsx`, `src/stores/__tests__/example-store.test.ts`, `src/stores/example-store.ts`, `src/stores/zustand-storage.ts`.
2. **Uninstall the dependencies**: `bun remove zustand`.
3. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/state/zustand/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --state zustand
</Cmd>

Module id: `state/zustand` (the default for this category).

### Dependencies [#dependencies]

| Package   | Version   | Kind       |
| --------- | --------- | ---------- |
| `zustand` | `^5.0.15` | dependency |

### Compatibility [#compatibility]

* Requires `storage` = [`kv-store`](https://readynative.app/docs/features/storage/kv-store), [`mmkv`](https://readynative.app/docs/features/storage/mmkv), [`async-storage`](https://readynative.app/docs/features/storage/async-storage)

### Files [#files]

<details>
  <summary>
    5 files copied to the project root
  </summary>

  * `src/app/examples/store.tsx`
  * `src/screens/examples/store-example-screen.tsx`
  * `src/stores/__tests__/example-store.test.ts`
  * `src/stores/example-store.ts`
  * `src/stores/zustand-storage.ts`
</details>


# AsyncStorage (/docs/features/storage/async-storage)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/storage/async-storage - do not edit. */}

<OptionBanner cat="storage" option="async-storage" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

AsyncStorage is the community-standard async key/value store (`@react-native-async-storage/async-storage`), behind the same `src/lib/storage.ts`. I'd pick it for one reason: a library you depend on hard-requires AsyncStorage - some auth and analytics SDKs take it as a `storage` option, and this way you keep a single store. Otherwise prefer `kv-store` (Expo Go **and** sync reads on native) or `mmkv` (fastest, dev build). Callers don't change: they import `storage` from `@/lib/storage`.

## Setup [#setup]

```bash
bun run setup --storage async-storage
```

That's it - setup writes `src/lib/storage.ts` (`createAsyncStorageStorage()` plus the active `storage`, with no `*Sync` methods), adds `@react-native-async-storage/async-storage 2.2.0` (the SDK 57 pin), a jest stand-in under `__mocks__/` that re-exports the package's own `jest/async-storage-mock`, and an adapter test. There's no config plugin.

## Usage [#usage]

```ts
import { storage } from "@/lib/storage";

await storage.setItem("readynative:draft", JSON.stringify(draft));
const raw = await storage.getItem("readynative:draft");
storage.getItemSync; // undefined - always await getItem()
```

If a SDK wants the raw module, pass `AsyncStorage` straight in; it's the same store your adapter writes to.

## Gotchas [#gotchas]

* Expo Go and web both work.
* There's no sync API, so the built-in stores, zustand `persist` and i18n all hydrate asynchronously: gate first paint on `store.useHydrated()` or the splash screen, and remember the initial language is only known after `initI18n()` resolves.
* Values are strings only - `setItem` with a non-string throws in the native module, so serialize first (the built-in stores already do).
* Android has a 6 MB total-size default; raise it with `AsyncStorage_db_size_in_MB` in `gradle.properties` if you store more.
* Swapping stacks: `bun run setup --storage kv-store|mmkv` replaces `src/lib/storage.ts`. Keys stay the same `readynative:*` strings but the data lives in a different backend, so existing values do **not** move - users start fresh. No migration ships.

## Remove it [#remove-it]

Every app needs a `storage` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --storage kv-store --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/storage/async-storage/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --storage async-storage
</Cmd>

Module id: `storage/async-storage`.

### Dependencies [#dependencies]

| Package                                     | Version | Kind                        |
| ------------------------------------------- | ------- | --------------------------- |
| `@react-native-async-storage/async-storage` | `2.2.0` | dependency (`expo install`) |

### Privacy [#privacy]

Required-reason APIs: `UserDefaults` (CA92.1), `FileTimestamp` (C617.1).

### Files [#files]

<details>
  <summary>
    3 files copied to the project root
  </summary>

  * `__mocks__/@react-native-async-storage/async-storage.ts`
  * `src/lib/__tests__/storage-async-storage.test.ts`
  * `src/lib/storage.ts`
</details>


# Storage (/docs/features/storage)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/storage/README.md - do not edit. */}

Hey - here's how storage works in ReadyNative. This category picks the key/value backend that
persists theme mode, onboarding, language, and anything your state library writes.

The contract is `StorageAdapter` in core `src/lib/storage-adapter.ts`: `getItem` / `setItem` /
`removeItem`, plus optional `*Sync` methods when the backend can read without awaiting. Callers
only ever import `storage` from `@/lib/storage`, so swapping backends with
`bun run setup --storage <option>` touches exactly one file. Keys are the same `readynative:*`
strings everywhere, but the data lives in a different backend per option - switching does not
migrate existing values, so users start fresh.

* **kv-store** - the default (`expo-sqlite/kv-store`). Expo Go **and** sync reads on native, so
  stores hydrate before first paint.
* **mmkv** - the fastest, memory-mapped and fully synchronous. Needs a dev build.
* **async-storage** - pick it when a library hard-requires AsyncStorage. Async only.

## Options [#options]

One option per category - `--storage <option>` picks it:

<Cmd>
  bun run setup --storage kv-store
</Cmd>

| Option                             | Label                          | Expo Go                 | Hint                                                             |
| ---------------------------------- | ------------------------------ | ----------------------- | ---------------------------------------------------------------- |
| [`kv-store`](./kv-store)           | expo-sqlite/kv-store (default) | yes                     | sync + async key/value on SQLite · Expo Go OK                    |
| [`mmkv`](./mmkv)                   | MMKV                           | no - dev build required | fastest sync key/value (Nitro) · dev build required (no Expo Go) |
| [`async-storage`](./async-storage) | AsyncStorage                   | yes                     | async-only key/value, the community standard · Expo Go OK        |


# expo-sqlite/kv-store (/docs/features/storage/kv-store)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/storage/kv-store - do not edit. */}

<OptionBanner cat="storage" option="kv-store" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the default storage adapter: Expo's SQLite-backed key/value store behind `src/lib/storage.ts`. I'd keep it unless you have a reason not to - it runs in Expo Go **and** gives you sync reads on native, so the built-in stores hydrate before first paint. Pick `mmkv` if you're already on a dev build and want the fastest possible reads, and `async-storage` only when a library hard-requires it. Whichever one you choose, callers only ever import `storage` from `@/lib/storage`; the `StorageAdapter` interface and `createMemoryStorage()` for tests live in core `src/lib/storage-adapter.ts`.

## Setup [#setup]

```bash
bun run setup --storage kv-store
```

That's it - setup writes `src/lib/storage.ts` (`createKvStoreStorage()` plus the active `storage`) and adds the `expo-sqlite` dependency and its config plugin through `.readynative.json` → `app.config.ts`.

## Usage [#usage]

```ts
import { storage } from "@/lib/storage";

await storage.setItem("readynative:draft", JSON.stringify(draft));
const raw = await storage.getItem("readynative:draft");
await storage.removeItem("readynative:draft");

storage.getItemSync?.("readynative:draft"); // native only
```

The built-in stores (`src/stores/create-store.ts`), zustand `persist` / Jotai `atomWithAppStorage` and i18n all go through this adapter, so you rarely call it directly.

## Gotchas [#gotchas]

* Expo Go works.
* `getItemSync` is native-only - on web it's `undefined`, so always have an `await` path.
* Values are strings; serialize objects yourself (the built-in stores already do).
* Swapping stacks: `bun run setup --storage mmkv` or `--storage async-storage` replaces `src/lib/storage.ts` and nothing else. Keys stay the same `readynative:*` strings, but the data lives in a different backend, so existing values do **not** move - users start fresh on theme mode, onboarding and language. No migration ships.

## Remove it [#remove-it]

Every app needs a `storage` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --storage mmkv --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/storage/kv-store/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --storage kv-store
</Cmd>

Module id: `storage/kv-store` (the default for this category).

### Dependencies [#dependencies]

| Package       | Version   | Kind                        |
| ------------- | --------- | --------------------------- |
| `expo-sqlite` | `~57.0.3` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-sqlite`

### Privacy [#privacy]

Required-reason APIs: `UserDefaults` (CA92.1), `FileTimestamp` (C617.1).

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/storage.ts`
</details>


# MMKV (/docs/features/storage/mmkv)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/storage/mmkv - do not edit. */}

<OptionBanner cat="storage" option="mmkv" />

<Callout type="warn" title="Expo Go: no - dev build required">
  Ships native code. Make a dev build with `bunx expo run:ios` / `bunx expo run:android` (or `bunx eas-cli build --profile development`).
</Callout>

MMKV is the fastest option: a synchronous, memory-mapped key/value store on `react-native-mmkv` 4 (Nitro), behind the same `src/lib/storage.ts`. I'd pick it when you already need a dev build for something else (Unistyles, Sentry, RevenueCat…) and want stores and zustand `persist` to hydrate before first paint with no async fallback. Stay on `kv-store` if Expo Go matters, and choose `async-storage` only for a library that hard-requires it. Callers don't change either way: they import `storage` from `@/lib/storage`.

## Setup [#setup]

```bash
bun run setup --storage mmkv
```

1. Make a dev build - `react-native-mmkv` is autolinked native code: `npx expo run:ios` or `npx expo run:android` (or `eas build --profile development`). &#x2A;*Expo Go will not load it.**

Setup writes `src/lib/storage.ts` (`createMmkvStorage()` with the instance id `readynative`), adds `react-native-mmkv ^4.3.2` and `react-native-nitro-modules 0.37.1` (the same pin as `ui/unistyles`), a `__mocks__/react-native-nitro-modules.ts` jest stand-in, and a round-trip test. There's no config plugin.

## Usage [#usage]

```ts
import { storage } from "@/lib/storage";

storage.getItemSync?.("readynative:draft"); // always present with MMKV
storage.setItemSync?.("readynative:draft", JSON.stringify(draft));
await storage.setItem("readynative:draft", JSON.stringify(draft)); // async methods wrap the sync ones
```

The built-in stores, zustand `persist` / Jotai `atomWithAppStorage` and i18n all go through the adapter, so switching to MMKV needs no caller changes - they stop awaiting.

## Gotchas [#gotchas]

* **Dev build required.** `bun run doctor` flags it if you're on Expo Go.
* `react-native-nitro-modules` throws on import without the native runtime, hence the `__mocks__` file. If you add another Nitro library, extend that mock or add your own `jest.mock`.
* Each `createMMKV({ id })` is its own file. Don't change `MMKV_INSTANCE_ID` after shipping or stored data becomes invisible.
* Web falls back to `localStorage` (web isn't a gate).
* Swapping stacks: `bun run setup --storage kv-store|async-storage` replaces `src/lib/storage.ts`. Keys stay the same `readynative:*` strings but the data lives in a different file, so existing values do **not** move - users start fresh. No migration ships.

## Remove it [#remove-it]

Every app needs a `storage` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --storage kv-store --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/storage/mmkv/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --storage mmkv
</Cmd>

Module id: `storage/mmkv`.

### Dependencies [#dependencies]

| Package                      | Version  | Kind       |
| ---------------------------- | -------- | ---------- |
| `react-native-mmkv`          | `^4.3.2` | dependency |
| `react-native-nitro-modules` | `0.37.1` | dependency |

### Privacy [#privacy]

Required-reason APIs: `UserDefaults` (CA92.1).

### Doctor checks [#doctor-checks]

* dev build toolchain (Xcode / Android SDK)

### After setup [#after-setup]

1. MMKV 4 is a native (Nitro) module: make a dev build with `npx expo run:ios` / `npx expo run:android` (or `eas build --profile development`). Expo Go will not load it.

### Files [#files]

<details>
  <summary>
    3 files copied to the project root
  </summary>

  * `__mocks__/react-native-nitro-modules.ts`
  * `src/lib/__tests__/storage-mmkv.test.ts`
  * `src/lib/storage.ts`
</details>


# Testing (/docs/features/testing)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/testing/README.md - do not edit. */}

Hey - here's how testing works in ReadyNative. This category decides whether the tree ships a test
runner - and every other module ships tests that live and die with it, so this is the safety net
that makes swapping stacks cheap.

What stays the same: `jest.config.js` is a core file (the setup engine shares it) and stays in
place under both options, and each UI stack that needs one carries a jest setup file (`src/components/ui/jest-setup.ts`)
that `jest.setup.ts` requires. Swap with `bun run setup --testing <option>`.

* **jest** - the default. Jest on `jest-expo` with React Native Testing Library and the mocks a
  real Expo app needs; core tests cover the stores, theme, env, the i18n shim, two kit
  primitives and the Settings screen.
* **none** - no runner and no test files. Only pick it if you're bringing your own.

## Options [#options]

One option per category - `--testing <option>` picks it:

<Cmd>
  bun run setup --testing jest
</Cmd>

| Option           | Label                            | Expo Go | Hint                                              |
| ---------------- | -------------------------------- | ------- | ------------------------------------------------- |
| [`jest`](./jest) | Jest + Testing Library (default) | yes     | jest-expo preset, RNTL, tests for stores/theme/ui |
| [`none`](./none) | No test runner                   | yes     | no jest; module tests are removed                 |


# Jest + Testing Library (/docs/features/testing/jest)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/testing/jest - do not edit. */}

<OptionBanner cat="testing" option="jest" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Jest on `jest-expo`, with React Native Testing Library and the mocks a real Expo app needs. I'd keep this on - it's what makes swapping modules safe, since each module ships its own tests and they disappear with it. Pick `testing/none` only if you're bringing another runner. Tests import from `@jest/globals` and render screens wrapped in the kit's `ThemeProvider`, so they're stack-agnostic.

## Setup [#setup]

```bash
bun run setup --testing jest
```

That's it - setup adds `jest.setup.ts` (in-memory `expo-sqlite/kv-store`, a virtual `expo-localization`, plus reanimated, haptics and symbols mocks), the core tests under `src/**/__tests__/` (stores, theme, env, the i18n shim, the kit's `Button`, `List`, `Row` and `Toast`, the Settings screen), the dev dependencies (`jest`, `jest-expo`, `@testing-library/react-native`, `@jest/globals`, `react-test-renderer`, types) and the `test` script.

## Usage [#usage]

```bash
bun run test           # everything
npx jest src/stores    # one folder
npx jest --watch       # while you work
```

A test looks like this. React Native Testing Library 14's `render` returns a promise, so `await` it:

```tsx
import { expect, it } from "@jest/globals";
import { render, screen } from "@testing-library/react-native";

import { ThemeProvider } from "@/components/ui";
import { SettingsScreen } from "@/screens/settings/settings-screen";

it("renders the title", async () => {
  await render(
    <ThemeProvider>
      <SettingsScreen />
    </ThemeProvider>
  );
  expect(screen.getByText("Settings")).toBeTruthy();
});
```

That's the finalized tree; before setup, or with `--keep-modules`, import `ThemeProvider` from `@/ui`. Wrap in whatever else the screen reads - a screen that runs a query needs your query provider too.

Module-specific tests (`client.test.ts`, `field.test.tsx`, `i18n.test.tsx`, and `example-store.test.ts` with `--with-examples`) are owned by their modules, so they arrive and leave with the module.

## Gotchas [#gotchas]

* `jest.config.js` is a core file, not part of this module, because the setup engine shares it. That means `testing/none` leaves it in place - harmless, unused.
* Each UI stack adds its own jest setup where it needs one (`src/components/ui/jest-setup.ts` after setup), required by `jest.setup.ts`. Unistyles' official mock strips `variants`; Tamagui needs its ESM entries in `transformIgnorePatterns` (already handled).
* Picking `--testing none` at setup (or later in a `--keep-modules` tree) removes the setup file, every test file and the dev dependencies. In a finalized tree, delete them by hand.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --testing none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there: `jest.setup.ts`, `src/lib/__tests__/env.test.ts`, `src/lib/__tests__/i18n-shim.test.ts`, `src/lib/__tests__/analytics-shim.test.ts`, `src/lib/__tests__/confirm.test.ts`, `src/lib/weather/__tests__/weather.test.ts`, `src/lib/__tests__/cache.test.ts`, `src/lib/__tests__/native-toast.test.ts`, `src/lib/__tests__/privacy.test.ts`, `src/screens/__tests__/developer-tools.test.tsx`, `src/screens/__tests__/settings-screen.test.tsx`, `src/stores/__tests__/create-store.test.ts`, `src/stores/__tests__/onboarding.test.ts`, `src/stores/__tests__/consent.test.ts`, `src/stores/__tests__/theme-mode.test.ts`, `src/theme/__tests__/mode.test.ts`, `src/theme/__tests__/mode.web.test.ts`, `src/theme/__tests__/tokens.test.ts`, `src/ui/__tests__/button.test.tsx`, `src/ui/__tests__/list.test.tsx`, `src/ui/__tests__/row.test.tsx`, `src/ui/__tests__/toast.test.tsx`, `src/lib/__tests__/store-review.test.ts`, `src/lib/__tests__/clipboard-share-browser.test.ts`, `src/components/__tests__/updates-banner.test.tsx`, `jest.config.js`, `scripts/test-utils/fixture.ts`, `scripts/__tests__/apply.test.ts`, `scripts/__tests__/doctor.test.ts`, `scripts/__tests__/e2e.test.ts`, `scripts/__tests__/gen-links.test.ts`, `scripts/__tests__/gen-privacy.test.ts`, `scripts/__tests__/graph.test.ts`, `scripts/__tests__/pm.test.ts`, `scripts/__tests__/store-check.test.ts`, `scripts/__tests__/gen-theme.test.ts`, `scripts/__tests__/gen-theme-tamagui.test.ts`, `scripts/__tests__/gen-theme-nativewind4.test.ts`, `scripts/__tests__/generate.test.ts`, `scripts/__tests__/registry.test.ts`, `scripts/__tests__/resolve.test.ts`, `scripts/__tests__/scaffold-clean.test.ts`, `scripts/__tests__/setup-clean.test.ts`, `scripts/__tests__/finalize.test.ts`, `scripts/__tests__/scaffold-tab.test.ts`, `scripts/__tests__/__snapshots__/gen-theme.test.ts.snap`, `scripts/__tests__/__snapshots__/gen-theme-tamagui.test.ts.snap`, `scripts/__tests__/__snapshots__/gen-theme-nativewind4.test.ts.snap`, `scripts/__tests__/__snapshots__/generate.test.ts.snap`, `scripts/__tests__/gen-assets.test.ts`, `src/components/__tests__/error-boundary.test.tsx`, `src/hooks/__tests__/use-sign-out-cleanup.test.tsx`.
2. **Uninstall the dependencies**: `bun remove @jest/globals @testing-library/react-native @types/jest @types/react-test-renderer jest jest-expo react-test-renderer`.
3. **Delete the script** `test` from `package.json`.
4. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/testing/jest/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --testing jest
</Cmd>

Module id: `testing/jest` (the default for this category).

### Dependencies [#dependencies]

| Package                         | Version   | Kind          |
| ------------------------------- | --------- | ------------- |
| `@jest/globals`                 | `~29.7.0` | devDependency |
| `@testing-library/react-native` | `^14.0.1` | devDependency |
| `@types/jest`                   | `29.5.14` | devDependency |
| `@types/react-test-renderer`    | `^19.3.0` | devDependency |
| `jest`                          | `~29.7.0` | devDependency |
| `jest-expo`                     | `~57.0.5` | devDependency |
| `react-test-renderer`           | `19.2.3`  | devDependency |

### Files [#files]

<details>
  <summary>
    52 files copied to the project root
  </summary>

  * `jest.setup.ts`
  * `src/lib/__tests__/env.test.ts`
  * `src/lib/__tests__/i18n-shim.test.ts`
  * `src/lib/__tests__/analytics-shim.test.ts`
  * `src/lib/__tests__/confirm.test.ts`
  * `src/lib/weather/__tests__/weather.test.ts`
  * `src/lib/__tests__/cache.test.ts`
  * `src/lib/__tests__/native-toast.test.ts`
  * `src/lib/__tests__/privacy.test.ts`
  * `src/screens/__tests__/developer-tools.test.tsx`
  * `src/screens/__tests__/settings-screen.test.tsx`
  * `src/stores/__tests__/create-store.test.ts`
  * `src/stores/__tests__/onboarding.test.ts`
  * `src/stores/__tests__/consent.test.ts`
  * `src/stores/__tests__/theme-mode.test.ts`
  * `src/theme/__tests__/mode.test.ts`
  * `src/theme/__tests__/mode.web.test.ts`
  * `src/theme/__tests__/tokens.test.ts`
  * `src/ui/__tests__/button.test.tsx`
  * `src/ui/__tests__/list.test.tsx`
  * `src/ui/__tests__/row.test.tsx`
  * `src/ui/__tests__/toast.test.tsx`
  * `src/lib/__tests__/store-review.test.ts`
  * `src/lib/__tests__/clipboard-share-browser.test.ts`
  * `src/components/__tests__/updates-banner.test.tsx`
  * `jest.config.js`
  * `scripts/test-utils/fixture.ts`
  * `scripts/__tests__/apply.test.ts`
  * `scripts/__tests__/doctor.test.ts`
  * `scripts/__tests__/e2e.test.ts`
  * `scripts/__tests__/gen-links.test.ts`
  * `scripts/__tests__/gen-privacy.test.ts`
  * `scripts/__tests__/graph.test.ts`
  * `scripts/__tests__/pm.test.ts`
  * `scripts/__tests__/store-check.test.ts`
  * `scripts/__tests__/gen-theme.test.ts`
  * `scripts/__tests__/gen-theme-tamagui.test.ts`
  * `scripts/__tests__/gen-theme-nativewind4.test.ts`
  * `scripts/__tests__/generate.test.ts`
  * `scripts/__tests__/registry.test.ts`
  * `scripts/__tests__/resolve.test.ts`
  * `scripts/__tests__/scaffold-clean.test.ts`
  * `scripts/__tests__/setup-clean.test.ts`
  * `scripts/__tests__/finalize.test.ts`
  * `scripts/__tests__/scaffold-tab.test.ts`
  * `scripts/__tests__/__snapshots__/gen-theme.test.ts.snap`
  * `scripts/__tests__/__snapshots__/gen-theme-tamagui.test.ts.snap`
  * `scripts/__tests__/__snapshots__/gen-theme-nativewind4.test.ts.snap`
  * `scripts/__tests__/__snapshots__/generate.test.ts.snap`
  * `scripts/__tests__/gen-assets.test.ts`
  * `src/components/__tests__/error-boundary.test.tsx`
  * `src/hooks/__tests__/use-sign-out-cleanup.test.tsx`
</details>


# No test runner (/docs/features/testing/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/testing/none - do not edit. */}

<OptionBanner cat="testing" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

No Jest, no test files. I'd only choose this if you're bringing a different runner or genuinely won't write tests - every other module ships tests that vanish with this option, so you lose the safety net that makes swapping stacks cheap. Setup removes `jest.setup.ts`, every `src/**/__tests__/**` file (core and module-owned, through `removeFiles`) and the Jest dev dependencies.

## Setup [#setup]

```bash
bun run setup --testing none
```

That's it - there's nothing to configure. `jest.config.js` stays behind: it's a core file shared with the setup engine, and it's harmless without a runner.

## Usage [#usage]

Nothing to run. `bun run lint` and `npx tsc --noEmit` still cover the tree, and `bun run doctor` still checks your configuration.

## Gotchas [#gotchas]

* Changing your mind is one command: `bun run setup --testing jest` brings back the setup file, the core tests and the dev dependencies. Module-owned tests come back with their modules.

## Reference [#reference]

Everything below is generated from `modules/testing/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --testing none
</Cmd>

Module id: `testing/none`.


# UI (/docs/features/ui)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/ui/README.md - do not edit. */}

Hey - here's how UI works in ReadyNative. This category picks the styling engine behind your
screens: the primitives (`Screen`, `Box`, `Text`, `Button`, `Input`, `Card`, `Switch`, `Toast`
and friends), the theme provider and the dark-mode plumbing.

The contract is what makes the choice cheap. Every option implements the same token-typed
props (with `style` as the only escape hatch), so the screens are identical on all five. After
`bun run setup` the kit lives in `src/components/ui` and screens import `@/components/ui`; before
setup, or with `--keep-modules`, it's `src/ui` behind `@/ui`, and switching is
`bun run setup --ui <option> --keep-modules`. Colours live in `src/theme/tokens.ts`, and
`bun run gen:theme` regenerates whatever the stack needs. [Styling](https://readynative.app/docs/styling)
shows the day-to-day pattern; the option pages below cover setup and gotchas per stack.

* **nativewind4** - the default. Stable NativeWind 4.2 on Tailwind 3 with React Native Reusables, biggest component ecosystem, Expo Go OK.
* **nativewind5** - RC · Tailwind 4. NativeWind 5 is still a release candidate; pick it if you want Tailwind 4 today.
* **stylesheet** - no framework at all, plain `StyleSheet.create` from the tokens. Zero extra dependencies and the clearest read of the contract.
* **tamagui** - a typed styling API with variants and a compiler, still JS-only.
* **unistyles** - a C++/Nitro engine that re-themes without React re-renders. The fastest, and the only option that needs a dev build.

## Options [#options]

One option per category - `--ui <option>` picks it:

<Cmd>
  bun run setup --ui nativewind4
</Cmd>

| Option                         | Label                  | Expo Go                 | Hint                                                                                 |
| ------------------------------ | ---------------------- | ----------------------- | ------------------------------------------------------------------------------------ |
| [`nativewind4`](./nativewind4) | NativeWind 4 (default) | yes                     | Stable · Tailwind 3 classes + RNR components behind @/ui · Expo Go OK                |
| [`nativewind5`](./nativewind5) | NativeWind 5           | yes                     | RC · Tailwind 4 classes behind @/ui · Expo Go OK                                     |
| [`tamagui`](./tamagui)         | Tamagui                | yes                     | Tamagui 2 (v5 config, optimising compiler) behind @/ui · Expo Go OK                  |
| [`unistyles`](./unistyles)     | Unistyles 3            | no - dev build required | C++ StyleSheet with themes/breakpoints behind @/ui · dev build required (no Expo Go) |
| [`stylesheet`](./stylesheet)   | StyleSheet (plain RN)  | yes                     | no style engine, tokens + StyleSheet.create · Expo Go OK                             |


# NativeWind 4 (/docs/features/ui/nativewind4)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/ui/nativewind4 - do not edit. */}

<OptionBanner cat="ui" option="nativewind4" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

The default UI stack: stable NativeWind 4.2 (`nativewind@4.2.7`) on Tailwind 3, with React Native Reusables (RNR) `text` / `button` as the kit in `src/components/ui/` (`src/ui/nativewind4/` before setup). Every preset and the committed tree use it. Pick `nativewind5` (RC · Tailwind 4) instead only if you want Tailwind 4 before NativeWind 5 is released. Pull components straight from the RNR registry - `components.json` already points at `@/components/ui`. Expo Go works.

## Setup [#setup]

```bash
bun run setup --ui nativewind4
```

1. Set your colours in `src/theme/tokens.ts` (hex).
2. `bun run gen:theme` - converts them to HSL triples and rewrites `src/global.css` and `tailwind.config.js`.
3. `bun run start -- -c` - once, so Metro picks up the NativeWind transform.

Setup writes `babel.config.js` (`jsxImportSource: "nativewind"` + `nativewind/babel`), `metro.config.js` (`withNativeWind`, `inlineRem: 16`), `tailwind.config.js` (`darkMode: "class"`, colours as `hsl(var(--x) / <alpha-value>)`), `src/global.css`, `nativewind-env.d.ts` and `components.json`, and registers `ThemeProvider` (order 50).

<Callout type="info" title="8-digit hex loses its alpha">
  HSL triples can't carry alpha, so a token like the dark `border` `#ffffff1a` is composited onto that mode's `background` by the generator. The generated CSS says so inline.
</Callout>

## Usage [#usage]

Screens use the primitives:

```tsx
import { Box, Button, Screen, Text } from "@/components/ui";

<Screen>
  <Box p={4} gap={2}>
    <Text variant="heading">Settings</Text>
    <Button onPress={signOut}>Sign out</Button>
  </Box>
</Screen>;
```

Your own components use `className` for static classes and `useTheme()` for anything token-driven:

```tsx
import { useTheme } from "@/components/ui";

const { colors, mode } = useTheme(); // resolved-mode hex, for inline styles
```

To add a primitive to the kit: create it in `src/components/ui/`, add its prop type to `src/components/ui/types.ts`, and export it from `src/components/ui/index.ts`.

## Gotchas [#gotchas]

* `darkMode: "class"` means NativeWind never follows the OS by itself. `ThemeProvider` calls `colorScheme.set(mode)` with the stored preference - `Appearance.setColorScheme` on native, the `dark` class on `<html>` on web.
* `ForcedMode` (the dev catalog) wraps a subtree in a `View` with `style={vars(hslTriples)}` because NativeWind 4 has no `VariableContextProvider`. Inside it, `dark:` utilities still follow the global scheme, and it adds one layout node.
* **nativewind #1834** (open): LogBox breaks on RN 0.86 with `nativewind/babel` in the preset list (fix PR #1840 unmerged). Dev-only; release bundles and `expo export` are fine. If the red box misbehaves, drop `"nativewind/babel"` from `babel.config.js` - only `React.createElement`-style code loses `className`.
* Web is best-effort: `colorScheme.set` throws outside a browser (guarded) and SSR export of `.dark:root` is untested.
* Before setup, or with `--keep-modules`, `bun run setup --ui <other>` swaps the adapter and config. Screens don't change.

## Remove it [#remove-it]

Every app needs a `ui` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --ui nativewind5 --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/ui/nativewind4/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --ui nativewind4
</Cmd>

Module id: `ui/nativewind4` (the default for this category).

### Dependencies [#dependencies]

| Package                    | Version   | Kind          |
| -------------------------- | --------- | ------------- |
| `@rn-primitives/slot`      | `^1.5.2`  | dependency    |
| `class-variance-authority` | `^0.7.1`  | dependency    |
| `clsx`                     | `^2.1.1`  | dependency    |
| `nativewind`               | `4.2.7`   | dependency    |
| `tailwind-merge`           | `^3.7.0`  | dependency    |
| `tailwindcss-animate`      | `^1.0.7`  | dependency    |
| `tailwindcss`              | `^3.4.19` | devDependency |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider                           | From   |
| ----- | ---------------------------------- | ------ |
| 50    | `ThemeProvider as UiThemeProvider` | `@/ui` |

### After setup [#after-setup]

1. Run `bun run start -- -c` once so Metro picks up the NativeWind transform.

### Files [#files]

<details>
  <summary>
    31 files copied to the project root
  </summary>

  * `babel.config.js`
  * `metro.config.js`
  * `tailwind.config.js`
  * `components.json`
  * `nativewind-env.d.ts`
  * `src/global.css`
  * `src/ui/nativewind4/box.tsx`
  * `src/ui/nativewind4/button.tsx`
  * `src/ui/nativewind4/card.tsx`
  * `src/ui/nativewind4/cn.ts`
  * `src/ui/nativewind4/divider.tsx`
  * `src/ui/nativewind4/empty-state.tsx`
  * `src/ui/nativewind4/error-state.tsx`
  * `src/ui/nativewind4/hsl.ts`
  * `src/ui/nativewind4/icon.tsx`
  * `src/ui/nativewind4/index.ts`
  * `src/ui/nativewind4/jest-setup.ts`
  * `src/ui/nativewind4/input.tsx`
  * `src/ui/nativewind4/list.tsx`
  * `src/ui/nativewind4/loading.tsx`
  * `src/ui/nativewind4/pressable.tsx`
  * `src/ui/nativewind4/rnr-button.tsx`
  * `src/ui/nativewind4/rnr-text.tsx`
  * `src/ui/nativewind4/row.tsx`
  * `src/ui/nativewind4/screen.tsx`
  * `src/ui/nativewind4/sheet.tsx`
  * `src/ui/nativewind4/skeleton.tsx`
  * `src/ui/nativewind4/switch.tsx`
  * `src/ui/nativewind4/text.tsx`
  * `src/ui/nativewind4/theme-provider.tsx`
  * `src/ui/nativewind4/toast.tsx`
</details>


# NativeWind 5 (/docs/features/ui/nativewind5)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/ui/nativewind5 - do not edit. */}

<OptionBanner cat="ui" option="nativewind5" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

**RC · Tailwind 4.** Tailwind 4 classes compiled by `react-native-css`, as the kit in `src/components/ui/` (`src/ui/nativewind5/` before setup). NativeWind 5 is still a release candidate, so it is not the default (that is [`nativewind4`](../nativewind4/docs.md), the stable release); pick it if you want Tailwind 4 today and accept an RC. Pure JS, so Expo Go works.

`nativewind@5.0.0-rc.0` and `react-native-css@3.1.0-rc.0` are pinned as a pair - NativeWind's peer dependency names the engine version exactly. The module also adds a `lightningcss` override to `package.json` (both pin 1.30.1; without it npm hoists a newer one and Metro fails to parse `src/global.css`).

## Setup [#setup]

```bash
bun run setup --ui nativewind5
```

1. Set your brand in `readynative.config.ts` (or the full palette in `src/theme/tokens.ts`).
2. `bun run gen:theme` - rewrites `src/global.css` (`@theme` / `:root` colours, dark mode via `prefers-color-scheme`).
3. `bun run start -- -c` - once, so Metro picks up the NativeWind transform.

Setup writes `babel.config.js`, `metro.config.js`, `postcss.config.mjs` and `nativewind-env.d.ts`, registers `ThemeProvider` (order 50) and pins `lightningcss@1.30.1` as a package override for Tailwind 4's native binary.

## Usage [#usage]

Screens use the primitives:

```tsx
import { Box, Button, Screen, Text } from "@/components/ui";

<Screen scroll>
  <Box p={4} gap={2}>
    <Text variant="title">Profile</Text>
    <Button onPress={save}>Save</Button>
  </Box>
</Screen>;
```

Your own components use classes; the token names are the colours:

```tsx
export function Badge({ children }: BadgeProps) {
  return <View className="rounded-full bg-primary px-3 py-1">{children}</View>;
}
```

Anything dynamic reads `useTheme()` - `p-${n}` can't be generated at runtime.

To add a primitive to the kit: create it in `src/components/ui/`, add its prop type to `src/components/ui/types.ts`, and export it from `src/components/ui/index.ts`.

## Gotchas [#gotchas]

* Changed `metro.config.js` or `babel.config.js`? `bun run start -- -c`, or you'll chase a stale cache.
* `ThemeProvider` applies the mode through `VariableContextProvider`; the rc prefers it over the deprecated `vars()`.
* Before setup, or with `--keep-modules`, `bun run setup --ui <other>` swaps the adapter, config and deps. Screens don't change.

## Remove it [#remove-it]

Every app needs a `ui` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --ui nativewind4 --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/ui/nativewind5/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --ui nativewind5
</Cmd>

Module id: `ui/nativewind5`.

### Dependencies [#dependencies]

| Package                    | Version      | Kind          |
| -------------------------- | ------------ | ------------- |
| `@rn-primitives/slot`      | `^1.5.2`     | dependency    |
| `class-variance-authority` | `^0.7.1`     | dependency    |
| `clsx`                     | `^2.1.1`     | dependency    |
| `nativewind`               | `5.0.0-rc.0` | dependency    |
| `react-native-css`         | `3.1.0-rc.0` | dependency    |
| `tailwind-merge`           | `^3.7.0`     | dependency    |
| `@tailwindcss/postcss`     | `^4.3.3`     | devDependency |
| `postcss`                  | `^8.5.28`    | devDependency |
| `tailwindcss`              | `^4.3.3`     | devDependency |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider                           | From   |
| ----- | ---------------------------------- | ------ |
| 50    | `ThemeProvider as UiThemeProvider` | `@/ui` |

### After setup [#after-setup]

1. Run `bun run start -- -c` once so Metro picks up the NativeWind transform.

### Files [#files]

<details>
  <summary>
    29 files copied to the project root
  </summary>

  * `babel.config.js`
  * `metro.config.js`
  * `postcss.config.mjs`
  * `nativewind-env.d.ts`
  * `src/global.css`
  * `src/ui/nativewind5/box.tsx`
  * `src/ui/nativewind5/button.tsx`
  * `src/ui/nativewind5/card.tsx`
  * `src/ui/nativewind5/cn.ts`
  * `src/ui/nativewind5/divider.tsx`
  * `src/ui/nativewind5/empty-state.tsx`
  * `src/ui/nativewind5/error-state.tsx`
  * `src/ui/nativewind5/icon.tsx`
  * `src/ui/nativewind5/index.ts`
  * `src/ui/nativewind5/jest-setup.ts`
  * `src/ui/nativewind5/input.tsx`
  * `src/ui/nativewind5/list.tsx`
  * `src/ui/nativewind5/loading.tsx`
  * `src/ui/nativewind5/pressable.tsx`
  * `src/ui/nativewind5/rnr-button.tsx`
  * `src/ui/nativewind5/rnr-text.tsx`
  * `src/ui/nativewind5/row.tsx`
  * `src/ui/nativewind5/screen.tsx`
  * `src/ui/nativewind5/sheet.tsx`
  * `src/ui/nativewind5/skeleton.tsx`
  * `src/ui/nativewind5/switch.tsx`
  * `src/ui/nativewind5/text.tsx`
  * `src/ui/nativewind5/theme-provider.tsx`
  * `src/ui/nativewind5/toast.tsx`
</details>


# StyleSheet (plain RN) (/docs/features/ui/stylesheet)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/ui/stylesheet - do not edit. */}

<OptionBanner cat="ui" option="stylesheet" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

The "no framework" stack: every primitive in `@/components/ui` is plain React Native styled with `StyleSheet.create` from `src/theme/tokens.ts`. Pick it when you don't want a style engine at all - nothing to compile, no `className`, no dependency beyond core. It's also the clearest read of the contract: `src/components/ui/` (`src/ui/stylesheet/` before setup) is the reference implementation. Expo Go works.

## Setup [#setup]

```bash
bun run setup --ui stylesheet
```

That's it. Setup writes a plain `babel.config.js` and `metro.config.js` (Expo defaults plus the `.wasm` asset extension), every primitive under `src/components/ui/`, registers `ThemeProvider` (order 50), and adds `src/components/ui/jest-setup.ts`, which stubs `@expo/ui` native views under jest. Edit `src/theme/tokens.ts` and the next render picks it up - there's no generate step.

## Usage [#usage]

Screens use the primitives:

```tsx
import { Card, Screen, Text } from "@/components/ui";

<Screen scroll>
  <Card p={4}>
    <Text variant="title">Today</Text>
  </Card>
</Screen>;
```

Your own components use `useStyles` - `StyleSheet.create` bound to the current theme, memoised per mode. Declare the factory at module scope:

```tsx
import { useStyles, useTheme } from "@/components/ui";
import type { Theme } from "@/components/ui";

const panelStyles = (t: Theme) => ({
  root: { backgroundColor: t.colors.card, borderRadius: t.radius.md, padding: t.space[4] },
});

export function Panel() {
  const styles = useStyles(panelStyles);
  const { colors } = useTheme(); // { mode, colors, space, radius } for inline colours
  return <View style={styles.root} />;
}
```

Styles that never read the theme can use `StyleSheet.create` directly.

To add a primitive to the kit: add its prop type to `src/components/ui/types.ts`, create `src/components/ui/<name>.tsx`, and export it from `src/components/ui/index.ts`.

## Gotchas [#gotchas]

* `@expo/ui` universal components (`Host`, `Switch`) are bundled in Expo Go on SDK 57.
* A mode change re-renders the context and every primitive rebuilds its styles - there's no engine to notify. `ForcedMode` overrides the context for a subtree.
* `Switch` is a native SwiftUI / Compose control inside `Host`, measured natively, so it can lay out one frame after its siblings. Swap in react-native's `Switch` in `switch.tsx` if that bothers you - the label row is already there.
* Text variants approximate NativeWind 5's `rnr-text` scale (`title` = h3, `heading` = h4, `subtitle` = lead, `caption` = muted, `label` = small); `code` is `fontFamily: "monospace"` (Menlo on iOS).
* Web is best-effort: `@expo/ui`'s web `Switch` is a styled checkbox from react-native-web.

## Remove it [#remove-it]

Every app needs a `ui` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --ui nativewind4 --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/ui/stylesheet/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --ui stylesheet
</Cmd>

Module id: `ui/stylesheet`.

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider                           | From   |
| ----- | ---------------------------------- | ------ |
| 50    | `ThemeProvider as UiThemeProvider` | `@/ui` |

### After setup [#after-setup]

1. Run `bun run start -- -c` once so Metro drops the NativeWind transform cache.

### Files [#files]

<details>
  <summary>
    24 files copied to the project root
  </summary>

  * `babel.config.js`
  * `metro.config.js`
  * `src/ui/stylesheet/box.tsx`
  * `src/ui/stylesheet/button.tsx`
  * `src/ui/stylesheet/card.tsx`
  * `src/ui/stylesheet/divider.tsx`
  * `src/ui/stylesheet/empty-state.tsx`
  * `src/ui/stylesheet/error-state.tsx`
  * `src/ui/stylesheet/icon.tsx`
  * `src/ui/stylesheet/index.ts`
  * `src/ui/stylesheet/input.tsx`
  * `src/ui/stylesheet/jest-setup.ts`
  * `src/ui/stylesheet/list.tsx`
  * `src/ui/stylesheet/loading.tsx`
  * `src/ui/stylesheet/pressable.tsx`
  * `src/ui/stylesheet/row.tsx`
  * `src/ui/stylesheet/screen.tsx`
  * `src/ui/stylesheet/sheet.tsx`
  * `src/ui/stylesheet/skeleton.tsx`
  * `src/ui/stylesheet/switch.tsx`
  * `src/ui/stylesheet/text.tsx`
  * `src/ui/stylesheet/theme-provider.tsx`
  * `src/ui/stylesheet/toast.tsx`
  * `src/ui/stylesheet/use-styles.ts`
</details>


# Tamagui (/docs/features/ui/tamagui)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/ui/tamagui - do not edit. */}

<OptionBanner cat="ui" option="tamagui" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

Tamagui 2.7.7 on the `@tamagui/config/v5` preset, as the kit in `src/components/ui/` (`src/ui/tamagui/` before setup). Pick it when you want a typed styling API with variants and a compiler instead of class strings. JS-only, so Expo Go works; animations use the `react-native-reanimated` you already have.

## Setup [#setup]

```bash
bun run setup --ui tamagui
```

1. Set your colours and radius in `readynative.config.ts` / `src/theme/tokens.ts`.
2. `bun run gen:theme` - regenerates `tamagui.config.ts`.
3. `bun run start -- -c` - once, so Metro and Babel pick up the compiler.

Setup installs `tamagui`, `@tamagui/config`, `@tamagui/animations-reanimated` and `@tamagui/font-inter` (exact 2.7.7) plus the Babel and Metro plugins, and writes `babel.config.js` (`@tamagui/babel-plugin`, extraction off in development), `metro.config.js` (`withTamagui`) and the generated `tamagui.config.ts`.

That config is static on purpose - the compiler loads it outside Metro, so no `@/` imports. It registers `light` / `dark` themes with every colour token as a key (`$card`, `$primaryForeground`, `$destructiveForeground`, `$success`, `$brandAccent`…) plus Tamagui's semantic keys (`background`, `color`, `borderColor`…) mapped from them; `space` and `radius` extend the v5 scales with the token keys. `settings.onlyAllowShorthands` is `false`, so full React Native prop names work. There's no `global.css` and you never run `tamagui generate` - `TamaguiProvider` injects the theme CSS at runtime.

## Usage [#usage]

Screens use the primitives:

```tsx
import { Box, Button, Screen, Text } from "@/components/ui";

<Screen>
  <Box p={4} gap={2}>
    <Text variant="title">Inbox</Text>
    <Button onPress={refresh}>Refresh</Button>
  </Box>
</Screen>;
```

Your own components use `styled` with `$token` keys:

```tsx
import { styled, YStack } from "tamagui";

export const Panel = styled(YStack, {
  backgroundColor: "$card",
  borderRadius: "$md",
  variants: { tone: { danger: { backgroundColor: "$destructive" } } } as const,
});
```

The `as const` on `variants` is what types the variant prop.

Inside the kit, RN-backed primitives (`Switch`, `Input`'s `TextInput`, `Icon`, `Skeleton`, `Screen`'s SafeAreaView) read `useTheme()`; Tamagui-styled ones use `$token` keys. `ForcedMode` is `<Theme name="dark">` plus the mode context, so both agree inside the subtree. To add a primitive: add its prop type to `src/components/ui/types.ts` and export it from `src/components/ui/index.ts`.

## Gotchas [#gotchas]

* jest: Tamagui ships ESM `.native.js` entries, so `jest.config.js` `transformIgnorePatterns` includes `|tamagui|@tamagui/.*`. No extra mocks - reanimated is already mocked in `jest.setup.ts`.
* The compiler writes `.tamagui/` at the project root on first build (gitignored). `[tamagui] skipped loading 2 module … warning-001` a few times is its benign "could not statically load" notice.
* Tamagui's `Input` is typed against the web DOM (`disabled`, no `editable` / `keyboardType`), so the kit's `Input` wraps a plain RN `TextInput` in a Tamagui frame. `Switch` is the platform switch.
* `@tamagui/font-inter` is installed but not wired - v5 uses the system fonts. To use Inter, load `@tamagui/font-inter/otf/*.otf` with `expo-font` and pass `createInterFont()` as `fonts.body` / `fonts.heading` in the generator.
* React Compiler stays on: tsc, jest and `expo export` pass. Only a device run proves the reanimated press animations; if they misbehave, set `"app": { "expo": { "experiments": { "reactCompiler": false } } }` in `module.json`.
* Web is best-effort: `outputCSS` is only honoured by the `tamagui generate` CLI; runtime CSS injection is what ships.
* Core `src/lib/utils.ts` still imports `clsx` / `tailwind-merge` (nativewind5 deps); it typechecks only while those linger in `node_modules`.

## Remove it [#remove-it]

Every app needs a `ui` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --ui nativewind4 --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/ui/tamagui/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --ui tamagui
</Cmd>

Module id: `ui/tamagui`.

### Dependencies [#dependencies]

| Package                          | Version | Kind          |
| -------------------------------- | ------- | ------------- |
| `@tamagui/animations-reanimated` | `2.7.7` | dependency    |
| `@tamagui/config`                | `2.7.7` | dependency    |
| `@tamagui/font-inter`            | `2.7.7` | dependency    |
| `tamagui`                        | `2.7.7` | dependency    |
| `@tamagui/babel-plugin`          | `2.7.7` | devDependency |
| `@tamagui/metro-plugin`          | `2.7.7` | devDependency |

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider                           | From   |
| ----- | ---------------------------------- | ------ |
| 50    | `ThemeProvider as UiThemeProvider` | `@/ui` |

### After setup [#after-setup]

1. Run `bun run start -- -c` once so Metro/Babel pick up the Tamagui compiler.

### Files [#files]

<details>
  <summary>
    23 files copied to the project root
  </summary>

  * `babel.config.js`
  * `metro.config.js`
  * `tamagui.config.ts`
  * `src/ui/tamagui/box.tsx`
  * `src/ui/tamagui/button.tsx`
  * `src/ui/tamagui/card.tsx`
  * `src/ui/tamagui/divider.tsx`
  * `src/ui/tamagui/empty-state.tsx`
  * `src/ui/tamagui/error-state.tsx`
  * `src/ui/tamagui/icon.tsx`
  * `src/ui/tamagui/index.ts`
  * `src/ui/tamagui/input.tsx`
  * `src/ui/tamagui/list.tsx`
  * `src/ui/tamagui/loading.tsx`
  * `src/ui/tamagui/pressable.tsx`
  * `src/ui/tamagui/row.tsx`
  * `src/ui/tamagui/screen.tsx`
  * `src/ui/tamagui/sheet.tsx`
  * `src/ui/tamagui/skeleton.tsx`
  * `src/ui/tamagui/switch.tsx`
  * `src/ui/tamagui/text.tsx`
  * `src/ui/tamagui/theme-provider.tsx`
  * `src/ui/tamagui/toast.tsx`
</details>


# Unistyles 3 (/docs/features/ui/unistyles)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/ui/unistyles - do not edit. */}

<OptionBanner cat="ui" option="unistyles" />

<Callout type="warn" title="Expo Go: no - dev build required">
  Ships native code. Make a dev build with `bunx expo run:ios` / `bunx expo run:android` (or `bunx eas-cli build --profile development`).
</Callout>

A C++/Nitro style engine: `StyleSheet.create((theme) => …)` styles are bound to the shadow tree and re-themed without a React re-render, as the kit in `src/components/ui/` (`src/ui/unistyles/` before setup). Pick it when theme switching and breakpoints need to be as cheap as possible and you're already on a dev build - it's the one UI option that can't run in Expo Go.

## Setup [#setup]

```bash
bun run setup --ui unistyles
```

1. Make a dev build: `npx expo run:ios` / `npx expo run:android` (or `eas build --profile development`). Unistyles is a native module.
2. Set your colours in `src/theme/tokens.ts` - `src/unistyles.ts` builds both themes from them, no generate step.
3. `bun run start -- -c` - once, since the Babel plugin and the entry file both changed.

Setup installs `react-native-unistyles ^3.3.0`, `react-native-nitro-modules 0.37.1` (exact - Unistyles pins the Nitro ABI) and `react-native-edge-to-edge ^1.8.1` with its config plugin, and writes:

* `babel.config.js` - `babel-preset-expo` plus `["react-native-unistyles/plugin", { root: "src" }]`.
* `index.ts` at the root plus `package.json` `main: "index.ts"`, so `src/unistyles.ts` runs `StyleSheet.configure` **before** `expo-router/entry` creates any stylesheet. Switching stacks restores `main: "expo-router/entry"`.
* `src/unistyles.ts` - the `light` / `dark` themes, breakpoints `xs` `sm` `md` `lg` `xl`, `settings.adaptiveThemes: true`, and the `UnistylesThemes` / `UnistylesBreakpoints` augmentations.
* `src/app/+html.tsx` (web shell), every primitive under `src/components/ui/`, and `src/components/ui/jest-setup.ts`.

## Usage [#usage]

Screens use the primitives:

```tsx
import { Box, Screen, Text } from "@/components/ui";

<Screen>
  <Box p={4} gap={2}>
    <Text variant="title">Library</Text>
  </Box>
</Screen>;
```

Your own components write theme functions:

```tsx
import { StyleSheet } from "react-native-unistyles";

const styles = StyleSheet.create((theme) => ({
  card: { backgroundColor: theme.colors.card, padding: theme.space[4] },
}));
```

`variants` plus `styles.useVariants({ tone: "danger" })` for prop-driven looks; `useTheme()` for inline token colours. Theme mode is the usual `setThemeMode("system" | "light" | "dark")` from `@/components/ui` - `ThemeProvider` mirrors it into the runtime (`system` turns adaptive themes on, an explicit mode turns them off, then `setTheme(mode)`).

To add a primitive to the kit: create `src/components/ui/<name>.tsx`, add its prop type to `src/components/ui/types.ts`, and export it from `src/components/ui/index.ts`.

## Gotchas [#gotchas]

* **No Expo Go.** `bun run doctor` flags it in its `devBuild` check. `expo export` still works - it's only the JS bundle.
* `setTheme` throws while adaptive themes are on, which is why `ThemeProvider` calls `setAdaptiveThemes(false)` first.
* The official jest mock strips `variants` and resolves against the first registered theme (light), so tests see base styles only.
* `react-native-edge-to-edge` is an optional peer of Unistyles ≥ 3.1 (Expo 54+ is edge-to-edge itself), installed for ecosystem compatibility. `expo install` can't add its plugin to a dynamic `app.config.ts`, so the module declares it in `app.expo.plugins`.
* Native is the target; the web export is best-effort.

## Remove it [#remove-it]

Every app needs a `ui` option, so there is no `none` to fall back to - you switch instead. While `modules/` exists (a tree set up with `--keep-modules`), one call does it:

<Cmd>
  bun run setup --ui nativewind4 --yes --keep-modules
</Cmd>

A finalized tree can't switch: clone a fresh copy of your tier repo, run `setup` there with the new option and port your code across - see [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).

## Reference [#reference]

Everything below is generated from `modules/ui/unistyles/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --ui unistyles
</Cmd>

Module id: `ui/unistyles`.

### Dependencies [#dependencies]

| Package                      | Version  | Kind       |
| ---------------------------- | -------- | ---------- |
| `react-native-edge-to-edge`  | `^1.8.1` | dependency |
| `react-native-nitro-modules` | `0.37.1` | dependency |
| `react-native-unistyles`     | `^3.3.0` | dependency |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `react-native-edge-to-edge`

### Providers [#providers]

Rendered in `src/providers.tsx` (lower order = outermost):

| Order | Provider                           | From   |
| ----- | ---------------------------------- | ------ |
| 50    | `ThemeProvider as UiThemeProvider` | `@/ui` |

### Doctor checks [#doctor-checks]

* dev build toolchain (Xcode / Android SDK)

### After setup [#after-setup]

1. Unistyles is a native (Nitro) module: make a dev build with `npx expo run:ios` / `npx expo run:android` (or `eas build --profile development`). Expo Go will not load it.
2. Run `bun run start -- -c` once so Metro picks up the Unistyles Babel plugin and the new entry file.

### Files [#files]

<details>
  <summary>
    26 files copied to the project root
  </summary>

  * `babel.config.js`
  * `index.ts`
  * `metro.config.js`
  * `src/app/+html.tsx`
  * `src/ui/unistyles/box.tsx`
  * `src/ui/unistyles/button.tsx`
  * `src/ui/unistyles/card.tsx`
  * `src/ui/unistyles/divider.tsx`
  * `src/ui/unistyles/empty-state.tsx`
  * `src/ui/unistyles/error-state.tsx`
  * `src/ui/unistyles/icon.tsx`
  * `src/ui/unistyles/index.ts`
  * `src/ui/unistyles/input.tsx`
  * `src/ui/unistyles/jest-setup.ts`
  * `src/ui/unistyles/list.tsx`
  * `src/ui/unistyles/loading.tsx`
  * `src/ui/unistyles/pressable.tsx`
  * `src/ui/unistyles/row.tsx`
  * `src/ui/unistyles/screen.tsx`
  * `src/ui/unistyles/sheet.tsx`
  * `src/ui/unistyles/skeleton.tsx`
  * `src/ui/unistyles/switch.tsx`
  * `src/ui/unistyles/text.tsx`
  * `src/ui/unistyles/theme-provider.tsx`
  * `src/ui/unistyles/toast.tsx`
  * `src/unistyles.ts`
</details>


# Expo Widgets (/docs/features/widgets/expo-widgets)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/widgets/expo-widgets - do not edit. */}

<OptionBanner cat="widgets" option="expo-widgets" />

<Callout type="warn" title="Expo Go: no - dev build required">
  Ships native code. Make a dev build with `bunx expo run:ios` / `bunx expo run:android` (or `bunx eas-cli build --profile development`).
</Callout>

This gives you an iOS home-screen widget and a Live Activity (Lock Screen and Dynamic Island) through [expo-widgets](https://docs.expo.dev/versions/latest/sdk/widgets/). The widget's layout is `src/widgets/app-widget.tsx`: a React component marked with the `'widget'` directive and built from `@expo/ui/swift-ui` views, which Expo compiles into a real WidgetKit extension. The app feeds it through `src/lib/widgets.ts`, which implements the shim - `widgets.update({ title, value, subtitle, symbol })` hands a new snapshot to the widget, and does nothing in Expo Go, on Android and on web. The weather demo pushes the current temperature to it every time a forecast loads. The Live Activity is `src/widgets/app-activity.tsx`, driven by `widgets.activity.start / update / end`; the weather demo's **Show on Lock Screen** button starts it and every forecast refresh updates it.

## Setup [#setup]

```bash
bun run setup --widgets expo-widgets
```

1. Make a dev build: `npx expo run:ios` (or `eas build --profile development`). The widget is an app extension, so Expo Go can't show it.
2. On the simulator or phone, long-press the Home Screen → **Edit** → **Add Widget** → your app → **At a glance**, small or medium.
3. Open the app once so it pushes a first snapshot (the weather demo does this on its home screen).
4. Rename it for your app: the `displayName` and `description` in the `expo-widgets` plugin entry are what the widget gallery shows.
5. Run `bun run doctor` - every row for this module should be green.

The config plugin adds a second iOS target, `<your bundle id>.ExpoWidgetsTarget`, and an App Group `group.<your bundle id>` that the app and the widget share. It also registers both with EAS, so the first `eas build` asks to create the extra provisioning profile.

## Usage [#usage]

Push a snapshot whenever the value changes:

```ts
import { widgets } from "@/lib/widgets";

widgets.update({
  title: "Almaty",
  value: "21°",
  subtitle: "Partly cloudy · H 24° L 12°",
  symbol: "cloud.sun.fill", // SF Symbol
});
```

Change the look in `src/widgets/app-widget.tsx`. Inside the `'widget'` function only `@expo/ui/swift-ui` components, their modifiers and the props work: no hooks, no `fetch`, no imports from the app, no constants from outside the function. It reads `environment.widgetFamily` to size itself for `systemSmall` and `systemMedium`.

### Live Activities [#live-activities]

Put the same glance on the Lock Screen and in the Dynamic Island while something is happening - a delivery, a workout, a timer, today's weather:

```ts
import { widgets } from "@/lib/widgets";

if (widgets.activity.supported) {
  const shown = await widgets.activity.start({
    title: "Almaty",
    value: "21°",
    subtitle: "Rain in 20 min",
    symbol: "cloud.rain.fill",
    progress: 0.4, // optional bar, 0-1
  });
  // shown === false: iOS < 16.2, or the user turned Live Activities off for the app
}

await widgets.activity.update({ title: "Almaty", value: "20°" }); // no-op when none is running
await widgets.activity.end();
```

`start` updates the running activity instead of stacking a second one, and `isRunning()` finds one left over from a previous launch. The layout - banner, compact leading/trailing, minimal and expanded Dynamic Island regions - is `src/widgets/app-activity.tsx`, under the same `'widget'` rules as the widget. The plugin sets `NSSupportsLiveActivities` for you. Updates while the app is closed need push-to-update (`enablePushNotifications` in the plugin options and a server that sends ActivityKit pushes); that isn't wired here.

To add a second widget, write another `createWidget("OtherWidget", …)` file and add a matching `{ "name": "OtherWidget", … }` entry to the plugin's `widgets` array.

## Gotchas [#gotchas]

* The widget never fetches. It shows the last snapshot until the app sends a new one, so update it after every refresh (and from a background task if you add one).
* `name` in the plugin config must equal the first argument of `createWidget`, and must be a Swift identifier - no spaces or dashes.
* Snapshot props replace the previous ones entirely: send every field each time.
* Images need to live in the shared container (`widgetsDirectory` from `expo-widgets`); a bundled `require()` path means nothing to the extension.
* A Live Activity lasts at most 8 hours active (12 on the Lock Screen) - iOS ends it after that. Start one for something with an end, not as a permanent widget.

## Remove it [#remove-it]

While `modules/` exists (a tree set up with `--keep-modules`), `setup` does all of it:

<Cmd>
  bun run setup --widgets none --yes --keep-modules
</Cmd>

In a finalized tree `setup` is a stub, so you undo it by hand. Here is everything this module added:

1. **Delete the files** that are still there: `src/lib/__tests__/widgets.test.ts`, `src/widgets/app-activity.tsx`, `src/widgets/app-widget.tsx`.
2. **Replace, don't delete** `src/lib/widgets.ts`: core code imports it, so swap in the no-op version from `modules/widgets/none/files/` of a fresh clone of your tier repo - same exports, nothing behind them.
3. **Uninstall the dependencies**: `bun remove expo-widgets`.
4. **Drop the config plugin** `expo-widgets` from `.readynative.json` → `modules.app.expo.plugins` (that is where `app.config.ts` reads it from), then rebuild the dev build.
5. **Check it**: `bun run typecheck` and `bun run lint` point at anything that still imports the removed files; `bun run gen:graph` refreshes `docs/ARCHITECTURE.md`.

## Reference [#reference]

Everything below is generated from `modules/widgets/expo-widgets/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --widgets expo-widgets
</Cmd>

Module id: `widgets/expo-widgets` (the default for this category).

### Dependencies [#dependencies]

| Package        | Version    | Kind                        |
| -------------- | ---------- | --------------------------- |
| `expo-widgets` | `~57.0.21` | dependency (`expo install`) |

### Config plugins [#config-plugins]

Merged into `app.config.ts` through `.readynative.json` (`modules.app`):

* `expo-widgets` (with options)

### Doctor checks [#doctor-checks]

* dev build toolchain (Xcode / Android SDK)

### After setup [#after-setup]

1. Widgets are an iOS app extension: make a dev build with `npx expo run:ios` (or `eas build --profile development`). Expo Go cannot show them, and `widgets.update()` is a no-op there.
2. Rename the widget for your app: `displayName` / `description` in the `expo-widgets` plugin entry (modules/widgets/expo-widgets/module.json, or override it in app.config.ts). Keep `name: "AppWidget"` in step with `createWidget("AppWidget", …)` in src/widgets/app-widget.tsx.
3. The widget is its own iOS target (`<your bundle id>.ExpoWidgetsTarget`) sharing an App Group (`group.<your bundle id>`) with the app. The plugin registers both with EAS, so the first `eas build` asks to create the extra provisioning profile - say yes.

### Files [#files]

<details>
  <summary>
    4 files copied to the project root
  </summary>

  * `src/lib/__tests__/widgets.test.ts`
  * `src/lib/widgets.ts`
  * `src/widgets/app-activity.tsx`
  * `src/widgets/app-widget.tsx`
</details>


# Home-screen widgets (/docs/features/widgets)



{/* Generated by apps/docs/scripts/gen-modules.ts; the intro is modules/widgets/README.md - do not edit. */}

Hey - here's how home-screen widgets work in ReadyNative.

This category owns the widget people add to their Home Screen: the one thing your app is about
(today's weather, a streak, a balance, the next booking), visible without opening the app.
`@/lib/widgets` always exists, whichever option you pick - `widgets.update(&#123; title, value,
subtitle, symbol &#125;)` replaces what the widget shows, and it is a safe no-op wherever widgets
can't run (the `none` option, Android, web, Expo Go). Screens call it unconditionally.

Pick **Expo Widgets** when a glance is worth a Home Screen slot: it adds an iOS widget extension
built with `@expo/ui` SwiftUI components, written in TypeScript in `src/widgets/app-widget.tsx`,
in small and medium sizes, plus a Live Activity for the Lock Screen and the Dynamic Island
(`widgets.activity.start()`). It needs a dev build. Pick **none** until you have that one number -
no extension target, no App Group, nothing extra to sign.

Both options are in Starter and Pro. Widgets are iOS-only for now (expo-widgets' Android support
is experimental); on Android `widgets.supported` is `false`.

## Options [#options]

One option per category - `--widgets <option>` picks it:

<Cmd>
  bun run setup --widgets expo-widgets
</Cmd>

| Option                           | Label                  | Expo Go                 | Hint                                                                                                                                           |
| -------------------------------- | ---------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`expo-widgets`](./expo-widgets) | Expo Widgets (default) | no - dev build required | iOS home-screen widget + Live Activity (Lock Screen, Dynamic Island) in SwiftUI (@expo/ui), fed from the app · dev build required (no Expo Go) |
| [`none`](./none)                 | No widgets             | yes                     | no app extension, widgets.update() is a no-op                                                                                                  |


# No widgets (/docs/features/widgets/none)



{/* Generated by apps/docs/scripts/gen-modules.ts from modules/widgets/none - do not edit. */}

<OptionBanner cat="widgets" option="none" />

<Callout type="info" title="Expo Go: yes">
  Runs in Expo Go; no dev build needed for this module.
</Callout>

This is the no-op widgets option: no app extension, no App Group, no extra target to sign. It owns `src/lib/widgets.ts` as a re-export of the core shim, so `@/lib/widgets` keeps the same API - `widgets.supported` is `false` and `widgets.update(...)` does nothing.

## Setup [#setup]

```bash
bun run setup --widgets none
```

There's nothing to configure. Switch with `bun run setup --widgets expo-widgets` when you want an iOS home-screen widget.

## Usage [#usage]

```ts
import { widgets } from "@/lib/widgets";

widgets.update({ title: "Almaty", value: "21°" }); // no-op
```

## Gotchas [#gotchas]

* Screens that already call `widgets.update()` need no change when you switch to Expo Widgets later.
* Nothing here needs a dev build; Expo Go is fine.

## Reference [#reference]

Everything below is generated from `modules/widgets/none/module.json` - the same file `bun run setup` reads, so it is what actually lands in your repo.

### Install [#install]

<Cmd>
  bun run setup --widgets none
</Cmd>

Module id: `widgets/none`.

### Files [#files]

<details>
  <summary>
    1 files copied to the project root
  </summary>

  * `src/lib/widgets.ts`
</details>


# Add your first feature (/docs/first-feature)



Hey - let's put something real in the app. By the end you'll have a **Notes** tab that loads
notes from a public demo API, keeps your own drafts on the device, adds one through a validated
form, and has a test that proves the list renders.

I wrote this against the `default` preset: TanStack Query, Zustand, React Hook Form and jest.
Pick a different option in the **Your stack** toggle above and the snippets that depend on it
switch too.

## Before you start [#before-you-start]

* **Tier:** any. Free has no `gen` script and no test runner; step 1 and step 6 say what to do
  there.
* **Time:** about 30 minutes.
* **Runs in:** Expo Go. Nothing here adds native code.
* **Accounts:** none. The notes come from [JSONPlaceholder](https://jsonplaceholder.typicode.com),
  a free fake REST API, so you see real data without building a backend.
* **Previous tutorial:** [Make it yours](https://readynative.app/docs/make-it-yours) (optional - this page doesn't
  depend on it).

Every snippet imports the kit from `@/components/ui`, where it lives in the finalized tree. If
you ran setup with `--keep-modules`, write `@/ui` instead.

## 1. Generate the tab [#1-generate-the-tab]

<Cmd>
  bun run gen screen notes --tab --icon note.text --icon-fallback description --title "Notes"
</Cmd>

That writes `src/screens/notes/notes-screen.tsx`, the route `src/app/(tabs)/notes.tsx`, a
`<NativeTabs.Trigger>` entry at the `{/* gen:tabs */}` marker in `src/app/(tabs)/_layout.tsx`
(the native tab bar: Liquid Glass on iOS 26, Material 3 on Android), and the
`"Notes"` key in every `src/locales/*.json`. If the marker isn't there, `gen` prints the block
to paste instead.

The Free tier ships without `gen`, so create the route by hand:

```tsx title="src/app/(tabs)/notes.tsx"
import { NotesScreen } from "@/screens/notes/notes-screen";

export default function Route() {
  return <NotesScreen />;
}
```

Then add a trigger next to the `settings` one in `src/app/(tabs)/_layout.tsx`:

```tsx title="src/app/(tabs)/_layout.tsx"
<NativeTabs.Trigger name="notes">
  <NativeTabs.Trigger.Icon sf="note.text" md="description" />
  <NativeTabs.Trigger.Label>Notes</NativeTabs.Trigger.Label>
</NativeTabs.Trigger>
```

`sf` is the SF Symbol iOS draws, `md` the Material Symbol for Android. Step 5 writes the screen
file itself.

<Cmd>
  bun run start
</Cmd>

**You should see:** a **Notes** tab after Settings, with a "Notes" title on an empty screen.

## 2. Fetch the notes [#2-fetch-the-notes]

Hooks live in `src/hooks/`. This one returns the same shape - `notes`, `loading`, `error`,
`reload` - whichever data option you picked, so the screen in step 5 doesn't care which.

<If cat="data" is="react-query">
  `fetchJson` is the typed client in `src/lib/api/client.ts`. It prefixes `EXPO_PUBLIC_API_URL`
  to relative paths and passes absolute URLs through, so the demo API works with no key set.

  ```ts title="src/hooks/use-notes.ts"
  import { useQuery } from "@tanstack/react-query";

  import { fetchJson } from "@/lib/api/client";

  export interface Note {
    id: number;
    title: string;
    body: string;
  }

  export const NOTES_URL = "https://jsonplaceholder.typicode.com/posts?_limit=5";
  export const notesQueryKey = ["notes"] as const;

  export function useNotes() {
    const query = useQuery({
      queryKey: notesQueryKey,
      queryFn: () => fetchJson<Note[]>(NOTES_URL),
    });

    return {
      notes: query.data ?? [],
      loading: query.isPending,
      error: query.error,
      reload: () => void query.refetch(),
    };
  }
  ```
</If>

<If cat="data" is="swr">
  `fetchJson` is the typed client in `src/lib/api/client.ts`. It prefixes `EXPO_PUBLIC_API_URL`
  to relative paths and passes absolute URLs through, so the demo API works with no key set.

  ```ts title="src/hooks/use-notes.ts"
  import useSWR from "swr";

  import { fetchJson } from "@/lib/api/client";

  export interface Note {
    id: number;
    title: string;
    body: string;
  }

  export const NOTES_URL = "https://jsonplaceholder.typicode.com/posts?_limit=5";

  export function useNotes() {
    const { data, error, isLoading, mutate } = useSWR(NOTES_URL, (url: string) =>
      fetchJson<Note[]>(url)
    );

    return {
      notes: data ?? [],
      loading: isLoading,
      error: error instanceof Error ? error : null,
      reload: () => void mutate(),
    };
  }
  ```
</If>

<If cat="data" is="apollo|none">
  <If cat="data" is="apollo">
    Apollo talks GraphQL and the demo API is REST, so this hook uses plain `fetch`. Swap it for
    `useQuery` from `@apollo/client/react` once you have a GraphQL server - the
    [Apollo page](https://readynative.app/docs/features/data/apollo) shows how.
  </If>

  <If cat="data" is="none">
    With no data module there's no query cache, so the hook wraps `fetch` in `useState` +
    `useEffect`.
  </If>

  ```ts title="src/hooks/use-notes.ts"
  import { useEffect, useState } from "react";

  export interface Note {
    id: number;
    title: string;
    body: string;
  }

  export const NOTES_URL = "https://jsonplaceholder.typicode.com/posts?_limit=5";

  export function useNotes() {
    const [notes, setNotes] = useState<Note[]>([]);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState<Error | null>(null);
    const [attempt, setAttempt] = useState(0);

    useEffect(() => {
      let cancelled = false;
      fetch(NOTES_URL)
        .then((res) => {
          if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
          return res.json() as Promise<Note[]>;
        })
        .then((data) => {
          if (cancelled) return;
          setNotes(data);
          setError(null);
        })
        .catch((err: unknown) => {
          if (!cancelled) setError(err instanceof Error ? err : new Error(String(err)));
        })
        .finally(() => {
          if (!cancelled) setLoading(false);
        });
      return () => {
        cancelled = true;
      };
    }, [attempt]);

    return {
      notes,
      loading,
      error,
      reload: () => {
        setLoading(true);
        setAttempt((n) => n + 1);
      },
    };
  }
  ```
</If>

**You should see:** nothing new on screen yet - the hook isn't used until step 5 - and
`bun run typecheck` passing.

## 3. Keep drafts on the device [#3-keep-drafts-on-the-device]

Stores live in `src/stores/`. `useDrafts()` returns `{ drafts, add }` for every state option,
so the rest of the page reads the same.

<If cat="state" is="zustand">
  `zustandStorage` is the adapter over whichever storage option you picked, so this persists the
  same way on `kv-store`, MMKV and AsyncStorage.

  ```ts title="src/stores/drafts.ts"
  import { create } from "zustand";
  import { createJSONStorage, persist } from "zustand/middleware";

  import { zustandStorage } from "@/stores/zustand-storage";

  export interface Draft {
    id: string;
    title: string;
    body: string;
  }

  interface DraftsState {
    drafts: Draft[];
    add: (title: string, body: string) => void;
  }

  const useDraftsStore = create<DraftsState>()(
    persist(
      (set) => ({
        drafts: [],
        add: (title, body) =>
          set((s) => ({ drafts: [{ id: String(Date.now()), title, body }, ...s.drafts] })),
      }),
      {
        name: "notes:drafts",
        storage: createJSONStorage(() => zustandStorage),
        partialize: (s) => ({ drafts: s.drafts }),
      }
    )
  );

  export function useDrafts() {
    const drafts = useDraftsStore((s) => s.drafts);
    const add = useDraftsStore((s) => s.add);
    return { drafts, add };
  }
  ```
</If>

<If cat="state" is="jotai">
  `atomWithAppStorage` persists through whichever storage option you picked; `unwrap` keeps the
  atom synchronous while the web (async) path loads.

  ```ts title="src/stores/drafts.ts"
  import { atom, useAtomValue, useSetAtom } from "jotai";
  import { unwrap } from "jotai/utils";

  import { atomWithAppStorage } from "@/stores/jotai-storage";

  export interface Draft {
    id: string;
    title: string;
    body: string;
  }

  const storedDraftsAtom = atomWithAppStorage<Draft[]>("notes:drafts", []);
  const draftsAtom = unwrap(storedDraftsAtom, (prev) => prev ?? []);

  const addDraftAtom = atom(null, (get, set, draft: { title: string; body: string }) =>
    set(storedDraftsAtom, [{ id: String(Date.now()), ...draft }, ...get(draftsAtom)])
  );

  export function useDrafts() {
    const drafts = useAtomValue(draftsAtom);
    const addDraft = useSetAtom(addDraftAtom);
    return { drafts, add: (title: string, body: string) => addDraft({ title, body }) };
  }
  ```
</If>

<If cat="state" is="none">
  With no state library the drafts live in component state, so they're gone when the app restarts.
  Add Zustand or Jotai at setup when you want them persisted.

  ```ts title="src/stores/drafts.ts"
  import { useState } from "react";

  export interface Draft {
    id: string;
    title: string;
    body: string;
  }

  export function useDrafts() {
    const [drafts, setDrafts] = useState<Draft[]>([]);
    const add = (title: string, body: string) =>
      setDrafts((prev) => [{ id: String(Date.now()), title, body }, ...prev]);
    return { drafts, add };
  }
  ```
</If>

**You should see:** `bun run typecheck` still passing.

## 4. Add the form [#4-add-the-form]

The form doesn't know where drafts go - it calls `onSave`, and the screen wires that to the
store.

<If cat="forms" is="react-hook-form">
  `Form` and `Field` from `src/components/form` bind the kit's `Input` to React Hook Form, and
  the zod schema does the validation.

  ```tsx title="src/screens/notes/note-form.tsx"
  import { zodResolver } from "@hookform/resolvers/zod";
  import { useForm } from "react-hook-form";
  import { z } from "zod";

  import { Field, Form } from "@/components/form";
  import { Box, Button, Card } from "@/components/ui";

  const schema = z.object({
    title: z.string().trim().min(2, "At least 2 characters"),
    body: z.string().trim().min(1, "Write something"),
  });
  type Values = z.infer<typeof schema>;

  export function NoteForm({ onSave }: { onSave: (title: string, body: string) => void }) {
    const form = useForm<Values>({
      resolver: zodResolver(schema),
      defaultValues: { title: "", body: "" },
    });

    const submit = form.handleSubmit((values) => {
      onSave(values.title, values.body);
      form.reset();
    });

    return (
      <Box p={4}>
        <Card>
          <Form form={form}>
            <Box gap={3}>
              <Field<Values> name="title" label="Title" placeholder="Morning walk" />
              <Field<Values> name="body" label="Note" placeholder="What happened?" multiline />
              <Button onPress={() => void submit()}>Save</Button>
            </Box>
          </Form>
        </Card>
      </Box>
    );
  }
  ```
</If>

<Else cat="forms" is="react-hook-form">
  With no form library, two `useState` calls and a check before saving do the job.

  ```tsx title="src/screens/notes/note-form.tsx"
  import { useState } from "react";

  import { Box, Button, Card, Input } from "@/components/ui";

  export function NoteForm({ onSave }: { onSave: (title: string, body: string) => void }) {
    const [title, setTitle] = useState("");
    const [body, setBody] = useState("");
    const [errors, setErrors] = useState<{ title?: string; body?: string }>({});

    const submit = () => {
      const next = {
        title: title.trim().length < 2 ? "At least 2 characters" : undefined,
        body: body.trim().length === 0 ? "Write something" : undefined,
      };
      setErrors(next);
      if (next.title || next.body) return;
      onSave(title.trim(), body.trim());
      setTitle("");
      setBody("");
    };

    return (
      <Box p={4}>
        <Card>
          <Box gap={3}>
            <Input
              label="Title"
              placeholder="Morning walk"
              value={title}
              onChangeText={setTitle}
              error={errors.title}
            />
            <Input
              label="Note"
              placeholder="What happened?"
              value={body}
              onChangeText={setBody}
              error={errors.body}
              multiline
            />
            <Button onPress={submit}>Save</Button>
          </Box>
        </Card>
      </Box>
    );
  }
  ```
</Else>

**You should see:** `bun run typecheck` passing. The form appears on screen in the next step.

## 5. Render the list [#5-render-the-list]

Replace the generated screen. A list screen is a non-scrolling `<Screen padded={false}>` with a
`<List>` inside, so the safe-area insets and the scrolling don't fight. `List` draws the
separators; `Row` draws none.

```tsx title="src/screens/notes/notes-screen.tsx"
import type { ReactNode } from "react";

import { useNotes } from "@/hooks/use-notes";
import { useDrafts } from "@/stores/drafts";
import { EmptyState, ErrorState, Icon, List, Loading, Row, Screen } from "@/components/ui";

import { NoteForm } from "./note-form";

interface Item {
  key: string;
  title: string;
  body: string;
  draft: boolean;
}

export function NotesScreen() {
  const { notes, loading, error, reload } = useNotes();
  const { drafts, add } = useDrafts();

  const items: Item[] = [
    ...drafts.map((d) => ({ key: `draft-${d.id}`, title: d.title, body: d.body, draft: true })),
    ...notes.map((n) => ({ key: `api-${n.id}`, title: n.title, body: n.body, draft: false })),
  ];

  let empty: ReactNode = (
    <EmptyState title="No notes yet" description="Write your first one above." />
  );
  if (loading) empty = <Loading label="Loading notes" />;
  if (error) {
    empty = <ErrorState title="Couldn't load notes" description={error.message} retry={reload} />;
  }

  return (
    <Screen padded={false}>
      <List
        data={items}
        keyExtractor={(item) => item.key}
        header={<NoteForm onSave={add} />}
        empty={empty}
        onRefresh={reload}
        refreshing={false}
        renderItem={(item) => (
          <Row
            title={item.title}
            subtitle={item.body}
            leading={
              <Icon
                name={item.draft ? "pencil" : "note.text"}
                fallback={item.draft ? "edit" : "description"}
              />
            }
          />
        )}
      />
    </Screen>
  );
}
```

**You should see:** the form on top and five notes from the demo API below it (Latin-looking
titles - that's JSONPlaceholder). Type a title and a note, tap **Save**, and your draft appears
first with a pencil icon. Save with an empty title and the field shows "At least 2
characters". Reload the app: with Zustand or Jotai your draft is still there.

Spacing, colours and radii are tokens (`gap={3}`, `p={4}`), never raw numbers. For anything the
kit has no prop for, every primitive takes `style` - see [Styling](https://readynative.app/docs/styling).

## 6. Test it [#6-test-it]

<If cat="testing" is="jest">
  Like the repo's own tests, this one renders inside the kit's `ThemeProvider` and uses Testing
  Library v14, where `render` is async - always `await` it. The network call is mocked, so the
  test runs offline.

  <If cat="data" is="react-query">
    ```tsx title="src/screens/notes/__tests__/notes-screen.test.tsx"
    import { describe, expect, it, jest } from "@jest/globals";
    import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
    import { render, screen } from "@testing-library/react-native";

    import { ThemeProvider } from "@/components/ui";
    import { NotesScreen } from "@/screens/notes/notes-screen";

    jest.mock("@/lib/api/client", () => ({
      fetchJson: () => Promise.resolve([{ id: 1, title: "From the API", body: "Mocked note" }]),
    }));

    describe("NotesScreen", () => {
      it("renders the notes the API returns", async () => {
        // A fresh client per test: no retries, and no garbage-collection timer left running.
        const client = new QueryClient({
          defaultOptions: { queries: { retry: false, gcTime: Infinity } },
        });

        await render(
          <QueryClientProvider client={client}>
            <ThemeProvider>
              <NotesScreen />
            </ThemeProvider>
          </QueryClientProvider>
        );

        expect(await screen.findByText("From the API")).toBeTruthy();
        expect(screen.getByText("Mocked note")).toBeTruthy();
      });
    });
    ```
  </If>

  <If cat="data" is="swr">
    ```tsx title="src/screens/notes/__tests__/notes-screen.test.tsx"
    import { describe, expect, it, jest } from "@jest/globals";
    import { render, screen } from "@testing-library/react-native";
    import { SWRConfig } from "swr";

    import { ThemeProvider } from "@/components/ui";
    import { NotesScreen } from "@/screens/notes/notes-screen";

    jest.mock("@/lib/api/client", () => ({
      fetchJson: () => Promise.resolve([{ id: 1, title: "From the API", body: "Mocked note" }]),
    }));

    describe("NotesScreen", () => {
      it("renders the notes the API returns", async () => {
        // A fresh cache per test, so nothing leaks between tests.
        await render(
          <SWRConfig value={{ provider: () => new Map(), dedupingInterval: 0 }}>
            <ThemeProvider>
              <NotesScreen />
            </ThemeProvider>
          </SWRConfig>
        );

        expect(await screen.findByText("From the API")).toBeTruthy();
        expect(screen.getByText("Mocked note")).toBeTruthy();
      });
    });
    ```
  </If>

  <If cat="data" is="apollo|none">
    ```tsx title="src/screens/notes/__tests__/notes-screen.test.tsx"
    import { afterEach, describe, expect, it, jest } from "@jest/globals";
    import { render, screen } from "@testing-library/react-native";

    import { ThemeProvider } from "@/components/ui";
    import { NotesScreen } from "@/screens/notes/notes-screen";

    describe("NotesScreen", () => {
      afterEach(() => {
        jest.restoreAllMocks();
      });

      it("renders the notes the API returns", async () => {
        jest.spyOn(globalThis, "fetch").mockResolvedValue({
          ok: true,
          status: 200,
          statusText: "OK",
          json: () => Promise.resolve([{ id: 1, title: "From the API", body: "Mocked note" }]),
        } as unknown as Response);

        await render(
          <ThemeProvider>
            <NotesScreen />
          </ThemeProvider>
        );

        expect(await screen.findByText("From the API")).toBeTruthy();
        expect(screen.getByText("Mocked note")).toBeTruthy();
      });
    });
    ```
  </If>

  <Cmd>
    bun run test
  </Cmd>

  **You should see:** the `NotesScreen` suite pass alongside the tests that shipped with the app.
</If>

<Else cat="testing" is="jest">
  You picked `testing=none` (as the Free tier does), so there's no test runner in this tree. If
  you kept modules, add one with `bun run setup --testing jest --yes --keep-modules`; a finalized
  tree starts from a fresh clone instead - see
  [Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).
</Else>

## Check it [#check-it]

<Cmd>
  bun run typecheck
</Cmd>

<Cmd>
  bun run lint
</Cmd>

Both should finish without errors. `bun run lint:fix` fixes what it can and formats with
Prettier.

## If it doesn't work [#if-it-doesnt-work]

* **"Unable to resolve @/components/ui"** (Starter / Pro) - your tree still has `modules/` (you
  ran setup with `--keep-modules`), so import from `@/ui` instead.
* **"Unable to resolve @/components/form" or "zustand"** - your stack differs from the
  `default` preset. Set the **Your stack** toggle above to what you picked; the snippets change
  with it.
* **The list shows "Couldn't load notes"** - the device can't reach
  `jsonplaceholder.typicode.com`. Check the phone's connection and pull to refresh; a corporate
  network or VPN can block it.
* **The new tab doesn't appear** - `gen` couldn't find the `{/* gen:tabs */}` marker and printed
  a block instead. Paste it into `src/app/(tabs)/_layout.tsx` inside `<Tabs>`.
* **The test times out on `findByText`** - check that the `jest.mock` path matches the import
  in `use-notes.ts`, and that the file imports from `@jest/globals`.

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

You shipped a feature: a tab, a data hook, a persisted store, a validated form, a list and a
test - all through the same `@/components/ui` kit the rest of the app uses. To point it at your
own backend later, swap `NOTES_URL` for a relative path and set `EXPO_PUBLIC_API_URL`
([Do I need a backend?](https://readynative.app/docs/backend)). Next, put a real account behind it:
[Add sign-in](https://readynative.app/docs/add-sign-in).


# Conventions (/docs/for-agents/conventions)



These are the rules the repo won't tell you itself. Follow them and your change looks like the
rest of the app; break one and the next `bun run gen:graph`, `bun run lint` or
`bun run doctor` tells on you.

## The shim contract [#the-shim-contract]

Every capability is reached through `@/lib/<category>`: `@/lib/auth`, `@/lib/payments`,
`@/lib/analytics`, `@/lib/push`, `@/lib/crash`, `@/lib/storage`. The shim exists whether or not
a module was selected - when the category is `none`, the shim is a no-op with exactly the same
signature, so a screen written against it compiles and runs either way.

That single rule is what keeps screens portable:

* Import `@/lib/auth` from a screen, never `@supabase/supabase-js` or another vendor SDK.
* To swap a provider, rewrite the shim, not its call sites. That's the whole point.
* UI comes from `@/components/ui` (`Screen`, `Box`, `Text`, `Button`, `Row`, `List`, …), not
  from raw `react-native` views: the primitives carry the theme tokens and dark mode.
  [Styling](https://readynative.app/docs/styling) has the pattern.

## Where things live [#where-things-live]

In the finalized tree `bun run setup` leaves:

| Path                | What belongs there                                                      |
| ------------------- | ----------------------------------------------------------------------- |
| `src/app`           | routes only - every file is a route, `_layout.tsx` files are navigators |
| `src/screens`       | screen bodies; a route imports one and renders it                       |
| `src/components/ui` | the primitive kit, reached as `@/components/ui`; types in `types.ts`    |
| `src/components`    | your own shared components, next to the kit                             |
| `src/stores`        | zustand stores (or whatever the `state` category selected)              |
| `src/lib`           | the shims, `env.ts`, the API client - the app's plumbing                |
| `src/hooks`         | hooks shared across screens                                             |
| `src/theme`         | `tokens.ts`, the design tokens every stack's theme is generated from    |
| `docs`              | `ARCHITECTURE.md` and `graph.json`, both generated                      |

Before setup, or after `setup --keep-modules`, the kit is in `src/ui/<stack>` behind `@/ui`,
typed by the [UI contract](https://readynative.app/docs/ui-contract), and `modules/` holds every option.

Keep non-route code out of `src/app`: expo-router turns every file there into a route, and a
helper next to a screen becomes a URL nobody asked for.

## Generated - do not hand-edit [#generated---do-not-hand-edit]

Each of these files has an owner that rewrites it:

| File                                                        | Owner                                                                       |
| ----------------------------------------------------------- | --------------------------------------------------------------------------- |
| `src/providers.tsx`                                         | `setup` (from every selected module's `providers[]`, sorted by order)       |
| `src/lib/env.ts`, `.env.example`                            | `setup` (from every module's `env[]`)                                       |
| `.readynative.json`                                         | `setup` - the record of what was applied                                    |
| `src/global.css`, `tailwind.config.js`, `tamagui.config.ts` | `bun run gen:theme`, from `src/theme/tokens.ts` (whichever your stack uses) |
| `public/.well-known/*`                                      | `bun run gen:links`                                                         |
| `docs/graph.json`, `docs/ARCHITECTURE.md`                   | `bun run gen:graph`                                                         |

Editing one of these isn't fatal, only temporary: the next generator run overwrites you. To add
an env key, add it to `src/lib/env.ts` **and** `.env.example`, then re-run `bun run gen:graph`;
`bun run doctor` is what tells a human the key is missing from `.env`.

<Callout type="warn" title="setup runs once">
  In a finalized tree, `bun run setup` is a stub that prints "Already applied" - there's no "re-run
  setup with a different option". Switching an option starts from a fresh clone; see [Can I change a
  module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).
</Callout>

## Extending the graph [#extending-the-graph]

`gen:graph` only knows about files. When you add something it can't see - a background job, a
webhook, an external service - say so where you wrote it, with a one-line annotation in any
`src/**` file:

```ts
// @graph node=job:digest kind=feature label="Nightly digest" edges=lib:api/client,env:EXPO_PUBLIC_API_URL
```

One node per line. `node` is the id, `kind` is one of `module`, `service`, `provider`, `route`,
`screen`, `feature`, `hook`, `store`, `lib`, `env`, `script`, `custom` (anything else becomes
`custom`), `label` is quoted and `edges` is a comma-separated list of node ids the new node
points at.

For anything with no natural home under `src/`, add it to `docs/graph.extra.json`, which is
merged verbatim and has the last word over both the generator and the annotations:

```json
{
  "nodes": [{ "id": "service:stripe", "kind": "service", "label": "Stripe" }],
  "edges": [{ "from": "service:stripe", "to": "env:EXPO_PUBLIC_API_URL", "kind": "reads" }]
}
```

An edge pointing at a node that doesn't exist is reported as a warning, not an error - it may
point at work you haven't done yet.

## Commands [#commands]

```bash
bun run doctor       # env keys, config placeholders, EAS login, SDK versions
bun run gen:graph    # docs/graph.json + docs/ARCHITECTURE.md (--check fails when stale)
bun run gen:theme    # src/theme/tokens.ts to src/global.css / tailwind.config.js / tamagui.config.ts
bun run gen:links    # links config to public/.well-known/*
bun run gen:assets   # assets/brand/icon.png to icons and splash
bun run typecheck && bun run lint && bun run test
```

Install packages with `expo install`, never a bare `add` - it resolves the version that matches
this SDK:

<Cmd>
  bunx expo install expo-haptics
</Cmd>

Use whichever package manager's lockfile is in the repo (`bun.lock` → bun, `package-lock.json`
→ npm, and so on); the scripts themselves run under plain node, so all four work. A library
with native code needs a dev build (`bunx expo run:ios`), not Expo Go - see
[Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build).

Run lint and typecheck before you call a task done.


# Full picture (/docs/for-agents/full-picture)



{/* Generated by apps/docs/scripts/gen-modules.ts from apps/template/docs/graph.json - do not edit. */}

Here is the entire template as one picture. Every app I ship with ReadyNative writes the same
graph about itself into `docs/graph.json`, so this is not a drawing I maintain by hand - it is
`bun run gen:graph` run on the template tree as it ships: 9 modules, 4 providers, 18 routes, 15 screens, 5 hooks, 8 stores, 44 libs, 2 env keys.

Untick a kind to cut the noise; edges disappear with the nodes on either end. If you want your
own app instead of mine, open "Paste your own graph.json" and drop your `docs/graph.json` in -
it is rendered in your browser and goes nowhere.

<GraphView />

## How to read it [#how-to-read-it]

Node ids are `kind:name`, so you can grep them: `route:/examples/[slug]`,
`screen:home/home-screen`, `lib:auth`, `env:EXPO_PUBLIC_API_URL`, `module:ui/nativewind5`,
`provider:QueryProvider`.

| Edge         | Reads as                                                         |
| ------------ | ---------------------------------------------------------------- |
| `imports`    | this file imports that one through `@/…`                         |
| `provides`   | a module contributes a provider to `src/providers.tsx`           |
| `renders`    | a route renders a screen, or a provider wraps the next one       |
| `reads`      | something reads an env key                                       |
| `configures` | a module configures an Expo config plugin or an external service |
| `custom`     | you added it, through `// @graph` or `docs/graph.extra.json`     |

The graph deliberately leaves out `@/ui` and `@/components`: every screen imports the primitive
kit, and an edge from all of them to one node tells you nothing.

## Your own map [#your-own-map]

Your repo has this same picture in two files, both written by `bun run gen:graph`:
`docs/ARCHITECTURE.md` for reading and `docs/graph.json` for grepping. Regenerate them after
you add a route, a screen, a `@/lib` shim, a provider, a store, a hook or an env key:

<Cmd>
  bun run gen:graph
</Cmd>

`bun run gen:graph --check` exits 1 when the two files are stale; the shipped CI runs exactly
that until you finalize, and it's worth adding back to `ci.yml` after. [Conventions](https://readynative.app/docs/for-agents/conventions) covers how to put a node on the
graph that no file can imply.

## The same map, as text [#the-same-map-as-text]

```mermaid
flowchart LR
  subgraph modules["module"]
    nmodule_data_react_query["data: react-query"]
    nmodule_forms_react_hook_form["forms: react-hook-form"]
    nmodule_i18n_i18next["i18n: i18next"]
    nmodule_location_expo_location["location: expo-location"]
    nmodule_onboarding_on["onboarding: on"]
    nmodule_state_zustand["state: zustand"]
    nmodule_storage_kv_store["storage: kv-store"]
    nmodule_testing_jest["testing: jest"]
    nmodule_ui_nativewind4["ui: nativewind4"]
  end
  subgraph providers["provider"]
    nprovider_I18nProvider["I18nProvider"]
    nprovider_QueryProvider["QueryProvider"]
    nprovider_ToastHost["ToastHost"]
    nprovider_UiThemeProvider["UiThemeProvider"]
  end
  subgraph routes["route"]
    nroute__layout["/ (layout)"]
    nroute__tabs___layout["/ (layout)"]
    nroute__tabs__cities__layout["/cities (layout)"]
    nroute__["/"]
    nroute___not_found["/+not-found"]
    nroute__cities["/cities"]
    nroute__cities__id_["/cities/[id]"]
    nroute__examples["/examples"]
    nroute__examples__slug_["/examples/[slug]"]
    nroute__examples_form["/examples/form"]
    nroute__examples_i18n["/examples/i18n"]
    nroute__examples_query["/examples/query"]
    nroute__examples_store["/examples/store"]
    nroute__explore["/explore"]
    nroute__onboarding["/onboarding"]
    nroute__settings["/settings"]
    nroute_examples__layout["/examples (layout)"]
    nroute_onboarding__layout["/onboarding (layout)"]
  end
  subgraph screens["screen"]
    nscreen_examples_examples_screen["@/screens/examples/examples-screen"]
    nscreen_examples_form_example_screen["@/screens/examples/form-example-screen"]
    nscreen_examples_i18n_example_screen["@/screens/examples/i18n-example-screen"]
    nscreen_examples_not_installed_screen["@/screens/examples/not-installed-screen"]
    nscreen_examples_query_example_screen["@/screens/examples/query-example-screen"]
    nscreen_examples_store_example_screen["@/screens/examples/store-example-screen"]
    nscreen_explore_explore_screen["@/screens/explore/explore-screen"]
    nscreen_home_home_screen["@/screens/home/home-screen"]
    nscreen_onboarding_onboarding_screen["@/screens/onboarding/onboarding-screen"]
    nscreen_settings_developer_tools["@/screens/settings/developer-tools"]
    nscreen_settings_settings_screen["@/screens/settings/settings-screen"]
    nscreen_weather_cities_screen["@/screens/weather/cities-screen"]
    nscreen_weather_city_screen["@/screens/weather/city-screen"]
    nscreen_weather_use_pro["@/screens/weather/use-pro"]
    nscreen_weather_weather_view["@/screens/weather/weather-view"]
  end
  subgraph hooks["hook"]
    nhook_use_auth_redirect["@/hooks/use-auth-redirect"]
    nhook_use_example_query["@/hooks/use-example-query"]
    nhook_use_forecast["@/hooks/use-forecast"]
    nhook_use_onboarding_redirect["@/hooks/use-onboarding-redirect"]
    nhook_use_sign_out_cleanup["@/hooks/use-sign-out-cleanup"]
  end
  subgraph stores["store"]
    nstore_consent["@/stores/consent"]
    nstore_create_store["@/stores/create-store"]
    nstore_example_store["@/stores/example-store"]
    nstore_onboarding["@/stores/onboarding"]
    nstore_review_prompt["@/stores/review-prompt"]
    nstore_theme_mode["@/stores/theme-mode"]
    nstore_weather["@/stores/weather"]
    nstore_zustand_storage["@/stores/zustand-storage"]
  end
  subgraph libs["lib"]
    nlib_account_data["@/lib/account-data"]
    nlib_analytics["@/lib/analytics"]
    nlib_api_client["@/lib/api/client"]
    nlib_auth["@/lib/auth"]
    nlib_browser["@/lib/browser"]
    nlib_cache["@/lib/cache"]
    nlib_clipboard["@/lib/clipboard"]
    nlib_confirm["@/lib/confirm"]
    nlib_consent["@/lib/consent"]
    nlib_crash["@/lib/crash"]
    nlib_env["@/lib/env"]
    nlib_i18n["@/lib/i18n"]
    nlib_location["@/lib/location"]
    nlib_native_toast["@/lib/native-toast"]
    nlib_payments["@/lib/payments"]
    nlib_privacy["@/lib/privacy"]
    nlib_privacy_categories["@/lib/privacy-categories"]
    nlib_push["@/lib/push"]
    nlib_query["@/lib/query"]
    nlib_readynative["@/lib/readynative"]
    nlib_readynative_config["@/lib/readynative-config"]
    nlib_share["@/lib/share"]
    nlib_shims_account_data["@/lib/shims/account-data"]
    nlib_shims_analytics["@/lib/shims/analytics"]
    nlib_shims_auth["@/lib/shims/auth"]
    nlib_shims_consent["@/lib/shims/consent"]
    nlib_shims_crash["@/lib/shims/crash"]
    nlib_shims_i18n["@/lib/shims/i18n"]
    nlib_shims_location["@/lib/shims/location"]
    nlib_shims_payments["@/lib/shims/payments"]
    nlib_shims_push["@/lib/shims/push"]
    nlib_shims_server_auth["@/lib/shims/server-auth"]
    nlib_shims_tracking["@/lib/shims/tracking"]
    nlib_shims_widgets["@/lib/shims/widgets"]
    nlib_storage["@/lib/storage"]
    nlib_storage_adapter["@/lib/storage-adapter"]
    nlib_store_review["@/lib/store-review"]
    nlib_tracking["@/lib/tracking"]
    nlib_utils["@/lib/utils"]
    nlib_weather_api["@/lib/weather/api"]
    nlib_weather_conditions["@/lib/weather/conditions"]
    nlib_weather_format["@/lib/weather/format"]
    nlib_weather_types["@/lib/weather/types"]
    nlib_widgets["@/lib/widgets"]
  end
  subgraph envs["env"]
    nenv_EXPO_PUBLIC_API_URL["EXPO_PUBLIC_API_URL"]
    nenv_EXPO_PUBLIC_APP_VARIANT["EXPO_PUBLIC_APP_VARIANT"]
  end
  nhook_use_example_query -->|imports| nlib_api_client
  nhook_use_example_query -->|imports| nlib_env
  nhook_use_example_query -->|reads| nenv_EXPO_PUBLIC_API_URL
  nhook_use_forecast -->|imports| nlib_cache
  nhook_use_forecast -->|imports| nlib_weather_api
  nhook_use_forecast -->|imports| nlib_weather_types
  nhook_use_onboarding_redirect -->|imports| nstore_onboarding
  nhook_use_sign_out_cleanup -->|imports| nlib_auth
  nhook_use_sign_out_cleanup -->|imports| nlib_crash
  nhook_use_sign_out_cleanup -->|imports| nlib_privacy
  nlib_api_client -->|imports| nlib_env
  nlib_api_client -->|reads| nenv_EXPO_PUBLIC_API_URL
  nlib_browser -->|imports| nlib_crash
  nlib_cache -->|imports| nlib_storage
  nlib_cache -->|imports| nlib_storage_adapter
  nlib_clipboard -->|imports| nlib_crash
  nlib_env -->|reads| nenv_EXPO_PUBLIC_API_URL
  nlib_env -->|reads| nenv_EXPO_PUBLIC_APP_VARIANT
  nlib_i18n -->|imports| nlib_storage
  nlib_privacy -->|imports| nlib_analytics
  nlib_privacy -->|imports| nlib_auth
  nlib_privacy -->|imports| nlib_share
  nlib_privacy -->|imports| nlib_storage
  nlib_privacy_categories -->|imports| nlib_analytics
  nlib_privacy_categories -->|imports| nlib_crash
  nlib_privacy_categories -->|imports| nstore_consent
  nlib_query -->|imports| nlib_privacy
  nlib_share -->|imports| nlib_crash
  nlib_shims_consent -->|imports| nstore_consent
  nlib_storage -->|imports| nlib_storage_adapter
  nlib_store_review -->|imports| nlib_crash
  nlib_store_review -->|imports| nlib_readynative
  nlib_store_review -->|imports| nstore_review_prompt
  nmodule_data_react_query -->|provides| nprovider_QueryProvider
  nmodule_i18n_i18next -->|provides| nprovider_I18nProvider
  nprovider_I18nProvider -->|imports| nlib_i18n
  nprovider_I18nProvider -->|renders| nprovider_ToastHost
  nprovider_QueryProvider -->|imports| nlib_query
  nprovider_QueryProvider -->|renders| nprovider_UiThemeProvider
  nprovider_UiThemeProvider -->|renders| nprovider_I18nProvider
  nroute__layout -->|imports| nhook_use_auth_redirect
  nroute__layout -->|imports| nhook_use_onboarding_redirect
  nroute__layout -->|imports| nhook_use_sign_out_cleanup
  nroute__layout -->|imports| nlib_analytics
  nroute__layout -->|imports| nstore_theme_mode
  nroute__tabs___layout -->|imports| nlib_i18n
  nroute__ -->|renders| nscreen_home_home_screen
  nroute___not_found -->|imports| nlib_i18n
  nroute__cities -->|renders| nscreen_weather_cities_screen
  nroute__cities__id_ -->|renders| nscreen_weather_city_screen
  nroute__examples -->|renders| nscreen_examples_examples_screen
  nroute__examples__slug_ -->|renders| nscreen_examples_not_installed_screen
  nroute__examples_form -->|renders| nscreen_examples_form_example_screen
  nroute__examples_i18n -->|renders| nscreen_examples_i18n_example_screen
  nroute__examples_query -->|renders| nscreen_examples_query_example_screen
  nroute__examples_store -->|renders| nscreen_examples_store_example_screen
  nroute__explore -->|renders| nscreen_explore_explore_screen
  nroute__onboarding -->|renders| nscreen_onboarding_onboarding_screen
  nroute__settings -->|renders| nscreen_settings_settings_screen
  nscreen_examples_examples_screen -->|imports| nlib_i18n
  nscreen_examples_form_example_screen -->|imports| nlib_i18n
  nscreen_examples_i18n_example_screen -->|imports| nlib_i18n
  nscreen_examples_not_installed_screen -->|imports| nlib_i18n
  nscreen_examples_query_example_screen -->|imports| nhook_use_example_query
  nscreen_examples_query_example_screen -->|imports| nlib_env
  nscreen_examples_query_example_screen -->|imports| nlib_i18n
  nscreen_examples_query_example_screen -->|reads| nenv_EXPO_PUBLIC_API_URL
  nscreen_examples_store_example_screen -->|imports| nlib_i18n
  nscreen_examples_store_example_screen -->|imports| nstore_example_store
  nscreen_explore_explore_screen -->|imports| nlib_readynative
  nscreen_home_home_screen -->|imports| nlib_cache
  nscreen_home_home_screen -->|imports| nlib_i18n
  nscreen_home_home_screen -->|imports| nlib_location
  nscreen_home_home_screen -->|imports| nlib_weather_types
  nscreen_home_home_screen -->|imports| nscreen_weather_weather_view
  nscreen_home_home_screen -->|imports| nstore_weather
  nscreen_onboarding_onboarding_screen -->|imports| nlib_i18n
  nscreen_onboarding_onboarding_screen -->|imports| nlib_readynative
  nscreen_onboarding_onboarding_screen -->|imports| nstore_onboarding
  nscreen_settings_developer_tools -->|imports| nhook_use_onboarding_redirect
  nscreen_settings_developer_tools -->|imports| nlib_auth
  nscreen_settings_developer_tools -->|imports| nlib_consent
  nscreen_settings_developer_tools -->|imports| nlib_crash
  nscreen_settings_developer_tools -->|imports| nlib_env
  nscreen_settings_developer_tools -->|imports| nlib_i18n
  nscreen_settings_developer_tools -->|imports| nlib_payments
  nscreen_settings_developer_tools -->|imports| nlib_privacy_categories
  nscreen_settings_developer_tools -->|imports| nlib_push
  nscreen_settings_developer_tools -->|imports| nstore_onboarding
  nscreen_settings_developer_tools -->|reads| nenv_EXPO_PUBLIC_APP_VARIANT
  nscreen_settings_settings_screen -->|imports| nhook_use_onboarding_redirect
  nscreen_settings_settings_screen -->|imports| nlib_account_data
  nscreen_settings_settings_screen -->|imports| nlib_analytics
  nscreen_settings_settings_screen -->|imports| nlib_auth
  nscreen_settings_settings_screen -->|imports| nlib_browser
  nscreen_settings_settings_screen -->|imports| nlib_confirm
  nscreen_settings_settings_screen -->|imports| nlib_consent
  nscreen_settings_settings_screen -->|imports| nlib_crash
  nscreen_settings_settings_screen -->|imports| nlib_i18n
  nscreen_settings_settings_screen -->|imports| nlib_payments
  nscreen_settings_settings_screen -->|imports| nlib_privacy
  nscreen_settings_settings_screen -->|imports| nlib_privacy_categories
  nscreen_settings_settings_screen -->|imports| nlib_readynative
  nscreen_settings_settings_screen -->|imports| nlib_store_review
  nscreen_settings_settings_screen -->|imports| nscreen_settings_developer_tools
  nscreen_settings_settings_screen -->|imports| nstore_consent
  nscreen_settings_settings_screen -->|imports| nstore_onboarding
  nscreen_weather_cities_screen -->|imports| nlib_analytics
  nscreen_weather_cities_screen -->|imports| nlib_confirm
  nscreen_weather_cities_screen -->|imports| nlib_i18n
  nscreen_weather_cities_screen -->|imports| nlib_share
  nscreen_weather_cities_screen -->|imports| nlib_weather_api
  nscreen_weather_cities_screen -->|imports| nlib_weather_types
  nscreen_weather_cities_screen -->|imports| nstore_weather
  nscreen_weather_city_screen -->|imports| nlib_i18n
  nscreen_weather_city_screen -->|imports| nlib_weather_types
  nscreen_weather_city_screen -->|imports| nstore_weather
  nscreen_weather_use_pro -->|imports| nlib_crash
  nscreen_weather_use_pro -->|imports| nlib_payments
  nscreen_weather_weather_view -->|imports| nhook_use_forecast
  nscreen_weather_weather_view -->|imports| nlib_analytics
  nscreen_weather_weather_view -->|imports| nlib_i18n
  nscreen_weather_weather_view -->|imports| nlib_push
  nscreen_weather_weather_view -->|imports| nlib_share
  nscreen_weather_weather_view -->|imports| nlib_weather_conditions
  nscreen_weather_weather_view -->|imports| nlib_weather_format
  nscreen_weather_weather_view -->|imports| nlib_weather_types
  nscreen_weather_weather_view -->|imports| nlib_widgets
  nscreen_weather_weather_view -->|imports| nstore_weather
  nstore_consent -->|imports| nlib_storage
  nstore_create_store -->|imports| nlib_storage_adapter
  nstore_onboarding -->|imports| nlib_storage
  nstore_review_prompt -->|imports| nlib_storage
  nstore_theme_mode -->|imports| nlib_storage
  nstore_weather -->|imports| nlib_storage
  nstore_weather -->|imports| nlib_weather_types
  nstore_weather -->|imports| nstore_create_store
  nstore_zustand_storage -->|imports| nlib_storage
```


# For agents (/docs/for-agents)



Hey - this section is written for whoever is doing the typing. If that is Claude Code, Cursor,
Codex or any other agent working inside a buyer's repo, point it here and it will stop guessing
at the layout. If that is you, read it anyway: it is the shortest description of how an Expo
Fast app fits together that I know how to write.

A ReadyNative app is a plain Expo app - Expo Router, TypeScript, `src/` - plus three things you
cannot see from the file tree: a graph the repo keeps about itself, a set of shims every screen
imports through, and a handful of files a generator owns.

## Start here [#start-here]

In this order, and it takes about two minutes:

1. **`bun run setup` already ran.** It picked one option per category, copied those modules in,
   deleted `modules/` and removed itself. What it chose is written down in `.readynative.json` -
   read that first and you know the stack without grepping for imports.
2. **`src/providers.tsx`** is the composition it wrote: every provider the selected modules
   asked for, nested in order. Outermost first.
3. **`src/lib/env.ts`** is every env key the app reads. `bun run doctor` tells a human which of
   them are still missing from `.env`.
4. **`@/lib/<category>`** is how screens reach any of it - `@/lib/auth`, `@/lib/payments`,
   `@/lib/analytics`, `@/lib/push`, `@/lib/crash`, `@/lib/storage`. The shim exists whether or
   not a module was selected; when the category is `none` it is a no-op with the same
   signature. Never import a vendor SDK from a screen.
5. **`src/screens`** holds screen bodies. `src/app` is routing only - every file there is a
   route and `_layout.tsx` files are navigators.

The long version of that list is [Conventions](https://readynative.app/docs/for-agents/conventions), and
[Full picture](https://readynative.app/docs/for-agents/full-picture) draws it.

## The graph [#the-graph]

Every ReadyNative app writes a graph about itself. `bun run gen:graph` walks the tree -
`.readynative.json`, `src/providers.tsx`, `src/app/**`, `src/screens/**`, `src/lib/**`,
`src/stores/**`, `src/hooks/**` - and rewrites two files:

<Cmd>
  bun run gen:graph
</Cmd>

* `docs/ARCHITECTURE.md` - a mermaid map plus one table per kind of node, for reading.
* `docs/graph.json` - the same thing machine-readable, for grepping.

Nothing in either file is hand-written, so neither can lie for long - but they can go stale.
Regenerate after adding or removing a route, a screen, a `@/lib` shim, a provider, a store, a
hook or an env key. `bun run gen:graph --check` exits 1 when they are stale; run it before you
commit, or add it to your own CI.

Reading `docs/graph.json` is usually faster than walking the tree:

```bash
node -e 'const g=require("./docs/graph.json");console.log(g.edges.filter(e=>e.from==="route:/"))'
```

## The skills in your repo [#the-skills-in-your-repo]

Four skills ship inside `.agents/skills/`, and any agent that reads skills will pick them up:

| Skill                | What it covers                                                            |
| -------------------- | ------------------------------------------------------------------------- |
| `readynative`        | this app: the graph, the shim contract, the generated files, the commands |
| `expo-router`        | file-based routing, layouts, typed params, navigation patterns            |
| `expo-native-ui`     | building screens that feel native instead of like a web page              |
| `expo-data-fetching` | fetching, caching, offline and cancellation on a phone                    |

<Callout type="info" title="Expo moves fast">
  Your training data about Expo is probably wrong. Read the `expo` major in `package.json` and
  fetch `https://docs.expo.dev/versions/v<major>.0.0/` before writing anything that touches an
  Expo, EAS or React Native API.
</Callout>

## The rest of this section [#the-rest-of-this-section]

* [Full picture](https://readynative.app/docs/for-agents/full-picture) - the template drawn as one graph, with a box
  to paste your own `docs/graph.json` into.
* [Conventions](https://readynative.app/docs/for-agents/conventions) - the shim contract, where code lives, what is
  generated and how to extend the graph.
* [llms.txt](https://readynative.app/docs/for-agents/llms) - the machine-readable copy of this whole site.
* [Store review](https://readynative.app/docs/for-agents/store-review) - the Pro skill that reviews your app against App Store and Play policies, on top of `bun run doctor --store`.


# llms.txt (/docs/for-agents/llms)



This site is a Next app, but none of that is useful to an agent. So it also serves itself as
plain markdown, at three URLs, all static and all cacheable.

## The three files [#the-three-files]

| URL                                                       | What it is                                                                                   |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [`/llms.txt`](https://readynative.app/llms.txt)           | the index: one line per page, with its title, description and a link to that page's markdown |
| [`/llms-full.txt`](https://readynative.app/llms-full.txt) | every page concatenated into one file - the whole documentation in a single fetch            |
| `/llms.mdx/docs/<slug>/content.md`                        | one page, as the markdown it was written in                                                  |

The third one is the interesting one when context is tight. Any page here has a copy button and
a "View as markdown" item in the menu at the top; both point at that URL. The Conventions page
is served as `/llms.mdx/docs/for-agents/conventions/content.md`.

Start at `/llms.txt`, pick the two or three pages that matter for the task, fetch those. Reach
for `/llms-full.txt` when you would rather spend the tokens than the round trips.

## Pointing an agent at them [#pointing-an-agent-at-them]

Nothing to install - they are URLs:

```
Read https://readynative.app/llms.txt, then fetch the pages you need from it
before changing anything in this repo.
```

That line belongs in your repo's `AGENTS.md` or `CLAUDE.md`, next to the "Start here" block
`setup` already wrote there.

## READYNATIVE\_DOCS\_URL [#readynative_docs_url]

Every guide link the CLI prints - `bun run setup`, `bun run doctor`, the module guides in
`.readynative.json` - is built from one base: `https://readynative.app/docs/`. Set `READYNATIVE_DOCS_URL`
to point them somewhere else, at a mirror or a local build:

```bash
READYNATIVE_DOCS_URL=http://localhost:3000 bun run doctor
```

A trailing slash is stripped, so both forms work. The same variable is what an air-gapped team
sets once in CI so that no link in the tooling points at the public internet.

<Callout type="info" title="Expo has its own">
  `https://docs.expo.dev/llms.txt` is the index of the Expo docs, including corrections to the
  things models most often get wrong about Expo. Fetch it before you write anything against an Expo
  or EAS API.
</Callout>


# Store review (/docs/for-agents/store-review)



<Badge>
  Pro
</Badge>

Hey - this is the one skill in the tree that reads policy instead of code. It reviews your app
against the App Store Review Guidelines and the Google Play Developer Program Policies before
you submit, and every line it writes cites the guideline it comes from.

## Where it lives [#where-it-lives]

In a Pro tree:

```
.agents/skills/store-review/
  SKILL.md                    the procedure and the report format
  references/apple-review.md  App Store guidelines 1-5, distilled, dated, linked
  references/play-policy.md   Play policies by group, distilled, dated, linked
```

The references carry a `Last reviewed:` date and the canonical URLs. The skill warns when that
date is more than a quarter old, so an agent never trusts a stale checklist silently. Starter
trees do not ship the folder; `bun run doctor --store` there prints that the check is part of
Pro.

## What doctor --store covers, what the skill judges [#what-doctor---store-covers-what-the-skill-judges]

Two halves, on purpose. The mechanical half is code in `scripts/lib/store-check.ts` and runs
without an agent:

<Cmd>
  bun run doctor --store
</Cmd>

It checks the things a file can prove: a usage string for every permission-bearing dependency,
`ITSAppUsesNonExemptEncryption`, App Tracking Transparency when analytics or ads are selected,
privacy and terms URLs set and linked from the paywall and sign-in screens, a Restore Purchases
action and a price on the paywall, an account-deletion route when any auth option is on, Sign
in with Apple next to other social logins, every Android permission justified by a dependency,
the target SDK, and a Data safety draft table built from the selected modules. Each finding has
an id, a `guideline` citation, a `file:line` and a `fix`. Details are in
[Doctor](https://readynative.app/docs/doctor).

The skill does what code cannot:

1. Runs `doctor --store` and copies its findings into the report verbatim.
2. Reads `readynative.config.ts`, `app.config.ts`, `.readynative.json`, every route under
   `src/app/` and the paywall, onboarding, auth and settings screens.
3. Walks both reference checklists and marks each item **likely rejection**, **fix before
   submit** or **fine**, with the guideline id and the exact line.
4. Optionally screenshots the paywall and permission prompts on the iOS Simulator and judges the
   copy: price, period and renewal terms visible; Restore present; nothing called "free" that
   charges; purpose strings that read as reasons.
5. Writes the report - a table of severity, guideline, where, what, fix - followed by the
   metadata checklist: screenshots per device class, age rating, export compliance, a demo
   account for the reviewer, Data safety answers, live privacy and support URLs.

## Running it [#running-it]

Claude Code reads `.agents/skills/` on its own. Ask in plain words:

```
Run the store-review skill and give me the report.
```

Or with a scope, after a change:

```
I added Google sign-in. Run store-review on the auth screens only.
```

Cursor and other agents that load `.agents/skills/*/SKILL.md` work the same way; if yours does
not, paste the path `.agents/skills/store-review/SKILL.md` into the prompt and it will read the
references from there.

The skill never edits the app. Ask for the fixes as a second step, then run it again.

## No guarantee [#no-guarantee]

The skill flags; it does not approve. A clean report means the predictable rejections are
handled - it does not mean a reviewer will not find something else, and the references are a
snapshot that needs a human re-read once a quarter. The rules in `SKILL.md` forbid the agent
from claiming otherwise.

The buyer-facing walkthrough is [Pass App Review](https://readynative.app/docs/pass-app-review).


# How setup works (/docs/how-setup-works)



`bun run setup` runs once on a Starter or Pro tree. Here's what it does, step by step, and the
tree it leaves behind. To run it, see [Quickstart](https://readynative.app/docs/ship-in-5-minutes); for the flags, see
[Scripts](https://readynative.app/docs/scripts#bun-run-setup).

## The steps [#the-steps]

For the selected option of every category, `setup`:

1. Copies the module's `files/**` to the repo root byte-for-byte and deletes files owned only
   by non-selected modules (a file listed by several modules survives while one owner is
   selected).
2. Generates `src/ui/index.ts` (re-exports the active UI adapter), `src/providers.tsx`
   (providers nested by `order`), `src/lib/env.ts` (zod-validated `EXPO_PUBLIC_*` keys),
   `.env.example` and `.readynative.json` (the applied selection plus the merged app patch,
   post-setup steps and doctor checks).
3. Patches `package.json` (adds module dependencies, removes those that belong only to
   non-selected modules, merges `scripts` / `overrides`) and `tsconfig.json` (`include`
   entries), then runs your package manager's install and `expo install` for the packages that
   need SDK-matched versions.
4. Strips the demo content so you start from a clean app: the [weather demo](https://readynative.app/docs/examples#the-weather-demo)
   (the Cities tab in `src/app/(tabs)/cities/`, `src/screens/weather/`, `src/lib/weather/`,
   `src/stores/weather.ts` and the `useForecast` hook), the example screens
   (`src/app/examples/`, `src/screens/examples/` and the hook/store behind them), the UI
   catalog route and its Settings row, and the placeholder assets. The home screen becomes a
   plain welcome and the Weather tab turns back into Home. Pass `--with-examples` to keep all
   of it. What stays is everything the demo was built on - `@/lib/location`, `@/lib/widgets`,
   the offline cache in `@/lib/cache`, every locale and the native tab bar. `bun run clean` removes it later, but only while
   `modules/` exists (`--keep-modules`); in a finalized tree, delete those files by hand.
5. Removes the `no-restricted-imports` block from `eslint.config.js` (unless `--keep-modules`).
   It exists only so the shipped screens work on every UI stack; once your stack is fixed, you
   can import `View` / `StyleSheet` straight from `react-native`.
6. Reconciles the tree with your package manager: the other package managers' lockfiles go
   (see [Package managers](https://readynative.app/docs/package-managers)).
7. **Finalizes the tree** (unless `--keep-modules`): `src/ui/<stack>/*` moves to
   `src/components/ui/*`, every `@/ui` import becomes `@/components/ui` (and `@/ui/contract`
   → `@/components/ui/types`), the `UiKit` contract is dropped, and the product tooling
   leaves: `modules/` is deleted, `scripts/` keeps `doctor`, `gen` (the screen scaffolder),
   `gen:theme`, `gen:links`, `gen:privacy`, `gen:assets`, `gen:graph` and `e2e`, plus any
   script a module added; `README.md` / `AGENTS.md` are rewritten for your app. `docs/` (the
   architecture graph) stays, and so does `examples/` in the Pro repo - the example apps are
   standalone projects you keep or delete.
8. Prints the post-setup steps of every selected module (dashboards to create, keys to paste)
   and a `https://readynative.app/docs/?stack=…` link that pre-filters these docs to your tree.

## The tree you end up with [#the-tree-you-end-up-with]

After a finalizing run:

```
src/
  app/            routes (expo-router)
  screens/        screen bodies
  components/
    ui/           the kit: box.tsx, button.tsx, list.tsx, …, index.ts, types.ts
  lib/            env, storage, i18n, auth/analytics/payments shims
  stores/  theme/  locales/
scripts/          doctor.ts, gen.ts, gen-*.ts, e2e.ts (+ lib/)
docs/             ARCHITECTURE.md, graph.json
examples/         Pro only: two standalone example apps
readynative.config.ts  app.config.ts  eas.json  .env.example  .readynative.json
```

No `modules/`, no `src/ui`, no contract to satisfy - a normal Expo Router app you edit like any
other.

<Callout type="warn" title="Finalizing is one-way">
  After a finalizing run, `bun run setup` is a one-line stub that prints "Already applied" and
  changes nothing. Switching an option then means a fresh clone of your tier repo - [Can I change a
  module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup) has the steps. To keep the tree
  switchable, run `bun run setup --keep-modules` instead.
</Callout>

## With `--keep-modules` [#with---keep-modules]

Steps 1-4 and 8 run as above, step 6 only removes the other lockfiles, and steps 5 and 7 are
skipped. `modules/` stays, the kit stays in `src/ui/<stack>` behind `@/ui` and the
[UI contract](https://readynative.app/docs/ui-contract), and `scripts/` keeps `setup`, `clean` and `gen module`.
Running `setup` again with a different selection re-resolves the plan, copies the new modules,
removes the old ones' files and regenerates providers and env. The same selection twice
produces no diff.


# ReadyNative (/docs)



Hey - welcome. ReadyNative is the Expo SDK 57 starter I wish I'd had: React Native 0.86, Expo
Router and the React Compiler already wired, and a **module system** on top so you don't
inherit my opinions. Every optional thing - UI stack, data layer, state, storage, forms, i18n,
auth, payments, analytics, crash reporting, push, backend, onboarding, consent, testing - lives
in `modules/<category>/<option>/`. You pick one option per category, and `bun run setup` copies
those modules into the tree, generates the providers and env plumbing, and deletes the rest.

What you're left with is a plain Expo app: no runtime "starter kit" layer, no framework of mine
to learn on top of Expo's.

## Get the repo [#get-the-repo]

Buying Starter or Pro gets you a GitHub invite to a private repo named after your tier. Accept
it and clone - [Get access](https://readynative.app/docs/after-you-buy) walks the Polar portal, the invite and what each
tier contains. Then [Quickstart](https://readynative.app/docs/ship-in-5-minutes) takes you from `bun install` to a
running app. The Free tier ([`ready-native-free`](https://github.com/ReadyNative/ready-native-free)) is
public: clone it and go.

## What you get [#what-you-get]

* **One UI kit, five engines.** Screens use the same token-typed primitives whichever stack is
  behind them: NativeWind 4, NativeWind 5 (RC), Tamagui, Unistyles or plain `StyleSheet`. See
  [Styling](https://readynative.app/docs/styling).
* **One option per category**, resolved with `requires` / `conflicts` rules, so `setup` refuses
  a combination that can't work before it writes anything. See
  [Pick your stack](https://readynative.app/docs/pick-your-stack).
* **Generated plumbing.** `setup` writes `src/providers.tsx`, `src/lib/env.ts`, `.env.example`
  and `.readynative.json` from the selected `module.json` files. See
  [How setup works](https://readynative.app/docs/how-setup-works).
* **Service shims.** Auth, payments, analytics, crash and push always exist behind
  `@/lib/<category>`; the `none` option is a no-op, so your code never branches on a module.
* **Ship tooling.** `eas.json` build and submit profiles per variant, `gen:assets` for icons
  and splash, `gen:links` for universal links. See
  [Ship to TestFlight](https://readynative.app/docs/ship-to-testflight) and
  [Ship to Google Play](https://readynative.app/docs/ship-to-google-play).
* **Any package manager.** I show bun first; npm, pnpm and yarn are equally supported. See
  [Package managers](https://readynative.app/docs/package-managers).

## Where to go next [#where-to-go-next]

* [Get access](https://readynative.app/docs/after-you-buy) - from checkout to a cloned repo
* [Quickstart](https://readynative.app/docs/ship-in-5-minutes) - install, setup, start, doctor
* [Pick your stack](https://readynative.app/docs/pick-your-stack) - every category and how to choose inside it
* [Make it yours](https://readynative.app/docs/make-it-yours) - the first tutorial: your name, colours, icon and font
* [Styling](https://readynative.app/docs/styling) - the primitives, the tokens, dark mode, your own components
* [Config](https://readynative.app/docs/config) - `readynative.config.ts`, `app.config.ts` variants, `.readynative.json`
* [Scripts](https://readynative.app/docs/scripts) - every `bun run` command
* [Features](https://readynative.app/docs/features) - the generated reference for each module


# License (/docs/license)



The paid tiers are sold under a commercial license, not open source. This page is a summary;
the binding text is the `LICENSE` file at the root of your `ready-native-starter` or
`ready-native-pro` repo.

The Free tier - [`ready-native-free`](https://github.com/ReadyNative/ready-native-free), one fixed
stack on a public repo - is [MIT](https://github.com/ReadyNative/ready-native-free/blob/main/LICENSE):
do what you like with it, attribution kept. Nothing below applies to it.

## Who may use the code [#who-may-use-the-code]

A Starter license covers one named individual; a Pro license covers up to 5 developers
(employees or contractors) in one company. Either way, one GitHub account gets repo access, and
a Pro company shares the code internally with the developers its license covers. Each additional
developer or company on a paid tier needs its own license. [Get
access](https://readynative.app/docs/after-you-buy#whats-in-each-tier) has the tiers side by side, repos included.

## Lifetime updates [#lifetime-updates]

Every paid license is perpetual and includes lifetime updates: every release published to your
tier's repo reaches you at no extra cost, for as long as ReadyNative is maintained. [Update from
upstream](https://readynative.app/docs/update-from-upstream) shows how to pull one in.

"Lifetime" means the life of the product, not a promise to maintain it forever. If updates ever
stop, your license and every version you already received stay yours: keep building, shipping
and selling apps with the code for as long as you like.

## Allowed [#allowed]

* Build an **unlimited number of end products** (mobile, web or desktop apps) for yourself, your
  organisation or your clients, and sell or otherwise monetise them.
* Modify the code freely and combine it with your own.
* Keep private forks of the repository for the projects your license covers.

## Not allowed [#not-allowed]

* Redistribute, resell, sublicense or transfer the starter (source or compiled) other than as
  embedded in an end product.
* Publish the source, or a substantially similar starter / template / boilerplate, publicly or
  privately - including on npm or public repositories.
* Share the private repository, or the code itself, with anyone outside the tier's scope.
* Use the code to build a competing product (a starter kit, boilerplate, template, generator or
  course whose main value is this code).
* Remove copyright, license or attribution notices.

## Ownership, warranty, termination [#ownership-warranty-termination]

The code is licensed, not sold: the licensor keeps the rights to the starter, you keep the rights
to your end products. It ships as-is with no warranty, liability is capped at what you paid, and
the license ends automatically if you breach it (apps already shipped are unaffected).

Third-party packages keep their own licenses. Parts of the tree derive from the MIT-licensed
Expo template, and the Expo agent skills in `.agents/skills` are MIT-licensed too; their
notices are kept in `LICENSES/`.

Questions or additional seats: [the support form](https://readynative.app/support/) - there's
no support email.

## Refunds [#refunds]

No refunds once you have access to the repository, except where the law requires otherwise.
Polar is the merchant of record and handles any refund the law requires; a refunded order loses
its repository access. Before you buy, the
[free version](https://github.com/ReadyNative/ready-native-free) and the
[module docs](https://readynative.app/docs/features) show exactly what you get. The
[Terms](https://readynative.app/terms#refunds) have the binding wording.


# Make it yours (/docs/make-it-yours)



Hey - this is the first thing I'd do with a fresh tree. By the end the app shows your name, your
colours in light and dark mode, your icon and splash, your font and your onboarding copy, and
`bun run doctor` stops warning about placeholders.

## Before you start [#before-you-start]

* **Tier:** any. The Free tier has no `gen:*` scripts and no `doctor`, so there you edit the
  generated files by hand (each step says which).
* **Time:** about 30 minutes, plus a native rebuild at the end.
* **Runs in:** Expo Go for colours, font and onboarding. The name, icon and splash are native,
  so you only see them in a dev build or a store build - Expo Go always shows its own. See
  [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build).
* **Accounts:** none.
* **Previous tutorial:** [Quickstart](https://readynative.app/docs/ship-in-5-minutes) - the app runs and `setup` is
  done.

Almost everything lives in one file, `readynative.config.ts` at the repo root. The full field
list is in [Config](https://readynative.app/docs/config); this page covers the branding fields in the order I'd do
them.

## 1. Set the name and ids [#1-set-the-name-and-ids]

Open `readynative.config.ts` and change the `app` block. Here's the whole file with example
values - keep your own `urls`, `store`, `links`, `features` and `privacy` if you already set
them. On the Free tier the file has no `features` line; don't add one.

```ts title="readynative.config.ts"
import type { ReadyNativeConfig } from "./src/lib/readynative-config";

export default {
  app: {
    name: "Trailmix",
    slug: "trailmix",
    scheme: "trailmix",
    owner: "",
    easProjectId: "",
    ios: { bundleId: "com.yourcompany.trailmix" },
    android: { package: "com.yourcompany.trailmix" },
  },
  brand: { primary: "#0f766e", accent: "#f59e0b", radius: 12, font: "Inter" },
  urls: { website: "", support: "mailto:", privacy: "", terms: "" },
  store: { appStoreId: "", playPackage: "" },
  links: { domain: "", appleTeamId: "", androidCertFingerprints: [] },
  features: { reviewPrompt: true, updatesBanner: true, tracking: false },
  privacy: { askEverywhere: false },
} satisfies ReadyNativeConfig;
```

`name` is the label under the icon, `scheme` is the deep-link prefix (`trailmix://`), and the
two ids are what the App Store and Google Play know your app by. Pick the ids before the first
store build: you can't change them on a published app. Dev and preview builds append `.dev` /
`.preview` to both ids and ` (Dev)` / ` (Preview)` to the name, so all three install side by
side.

<Cmd>
  bun run doctor
</Cmd>

**You should see:** no more warnings for `app.name` or the `com.acme.app` ids. The Home tab's
title already reads your name; the label under the icon changes with the next native build
(step 5).

## 2. Pick your brand colours [#2-pick-your-brand-colours]

`brand` in the same file drives the palette: `primary` becomes the light-mode `primary` token,
`accent` the `brandAccent` token, and `radius` the base corner radius (`radius.lg`; the other
sizes derive from it). They flow through `src/theme/tokens.ts`. Regenerate the files your UI
stack reads:

<Cmd>
  bun run gen:theme
</Cmd>

That rewrites `src/global.css` + `tailwind.config.js` (NativeWind 4), `src/global.css`
(NativeWind 5) or `tamagui.config.ts` (Tamagui); StyleSheet and Unistyles read `tokens.ts`
directly. On the Free tier, which has no `gen:theme`, also change the `--primary` HSL triple (for
example `--primary: 221 83% 53%;`) in the `:root` block of `src/global.css` by hand. Then
restart with a clean cache so Metro picks up the new theme:

<Cmd>
  bun run start -- -c
</Cmd>

**You should see:** primary buttons and the active tab icon in your `primary` colour.

## 3. Set the dark-mode colours [#3-set-the-dark-mode-colours]

In dark mode `primary` is a neutral light grey, not your brand colour - a dark brand colour on a
near-black background is hard to read. To keep your brand in dark mode, pick a lighter shade of
it and set it in the `dark` palette of `src/theme/tokens.ts`:

```ts title="src/theme/tokens.ts"
  dark: {
    // ...the other tokens stay as they are
    primary: "#5eead4",
    primaryForeground: "#042f2e",
    // ...
  },
```

`primaryForeground` is the text on primary buttons, so keep the pair readable. Then regenerate:

<Cmd>
  bun run gen:theme
</Cmd>

**You should see:** in **Settings → Appearance → Dark**, primary buttons and the active tab use
your dark shade.

## 4. Load your font [#4-load-your-font]

`brand.font` is only a family name, exported as `fontFamily` from `src/theme/tokens.ts`.
Nothing loads the font file for you, so until you do, the app renders the system font.

Put the file in `assets/fonts/`, then load it in `src/app/_layout.tsx` and keep the splash up
until it's ready. The key you pass to `useFonts` must equal `brand.font`. Here's the template's
root layout with the font added:

```tsx title="src/app/_layout.tsx"
import { useFonts } from "expo-font";
import { Stack, usePathname } from "expo-router";
import * as SplashScreen from "expo-splash-screen";
import { useEffect } from "react";

import { AnimatedSplashOverlay } from "@/components/animated-icon";
import { UpdatesBanner } from "@/components/updates-banner";
import { useAuthRedirect } from "@/hooks/use-auth-redirect";
import { useOnboardingRedirect } from "@/hooks/use-onboarding-redirect";
import { useSignOutCleanup } from "@/hooks/use-sign-out-cleanup";
import { analytics } from "@/lib/analytics";
import { Providers } from "@/providers";
import { hydrateThemeMode } from "@/stores/theme-mode";

export { ErrorBoundary } from "@/components/error-boundary";

SplashScreen.preventAutoHideAsync();

export default function RootLayout() {
  const [fontsLoaded, fontError] = useFonts({
    Inter: require("../../assets/fonts/Inter-Regular.ttf"),
  });
  const ready = fontsLoaded || fontError !== null;

  useEffect(() => {
    if (!ready) return;
    // Single hydration point: the theme provider only reads the store.
    hydrateThemeMode().finally(() => {
      SplashScreen.hideAsync().catch((err: unknown) => {
        console.warn("[splash] hideAsync failed", err);
      });
    });
  }, [ready]);

  if (!ready) return null;

  return (
    <Providers>
      <AnimatedSplashOverlay />
      <UpdatesBanner />
      <RootStack />
    </Providers>
  );
}

/** Inside `Providers` so redirect hooks can read stores/providers; routes come from `src/app`. */
function RootStack() {
  useOnboardingRedirect();
  useAuthRedirect();
  useSignOutCleanup();

  const pathname = usePathname();
  useEffect(() => {
    analytics.screen(pathname);
  }, [pathname]);

  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Screen name="(tabs)" />
      <Stack.Screen name="examples" />
      <Stack.Screen name="+not-found" />
      {/* gen:stack */}
    </Stack>
  );
}
```

Your root layout may differ slightly - the Free tier has no `UpdatesBanner` and no
`{/* gen:stack */}` marker, and screens you generated with `gen screen --modal` add
`<Stack.Screen>` lines. Keep those; only the `useFonts` lines, the `ready` guard and the
`[ready]` dependency are new. `expo-font` is already a dependency, and `useFonts` works in Expo
Go.

<If cat="ui" is="stylesheet">
  The StyleSheet kit's `Text` already sets `fontFamily` from `@/theme/tokens`, so you're done.
</If>

<Else cat="ui" is="stylesheet">
  Your kit's `Text` doesn't read `fontFamily`, so pass it in `src/components/ui/text.tsx`.

  <If cat="ui" is="nativewind4|nativewind5">
    Add `fontFamily` to the tokens import, and put it first in the style array so a `style` prop
    still wins:

    ```tsx title="src/components/ui/text.tsx"
    import { fontFamily, fontWeight } from "@/theme/tokens";

    // ...inside Text, the style prop of <RnrText>:
          style={[
            { fontFamily },
            color ? { color: colors[color] } : null,
            weight ? { fontWeight: fontWeight[weight] } : null,
            align ? { textAlign: align } : null,
            style,
          ]}
    ```
  </If>

  <If cat="ui" is="tamagui|unistyles">
    Import `fontFamily` from `@/theme/tokens` there and put `{ fontFamily }` first in the style the
    component passes down, so a `style` prop still wins. Leave the `code` variant on its monospace
    font.
  </If>
</Else>

Bold weights need their own file and their own family name, for example `"Inter-SemiBold"`.

**You should see:** every screen in your font after a reload. If text still looks like the
system font, the `useFonts` key doesn't match `brand.font`.

## 5. Replace the icon and splash [#5-replace-the-icon-and-splash]

Drop a square PNG, at least 1024 px, at `assets/brand/icon.png`, then:

<Cmd>
  bun run gen:assets
</Cmd>

It writes `assets/images/icon.png`, the three Android adaptive icon layers
(`android-icon-foreground/background/monochrome.png`), `splash-icon.png` and `favicon.png`, on a
`brand.primary` background. Pass `--source path/to/icon.png` to read from another file. It runs
under Node because `sharp` hangs inside bun. On the Free tier, replace those files in
`assets/images/` by hand.

The splash is the `expo-splash-screen` plugin in `app.config.ts`: `splash-icon.png`, 76 pt wide,
on `brand.primary`. `AnimatedSplashOverlay` (`src/components/animated-icon.tsx`) shows the same
image for the first frame and fades it out, so both stay in sync.

<Callout type="info" title="Optional: an Icon Composer icon for iOS">
  iOS uses `assets/images/icon.png` like every other platform. To ship a layered [Icon
  Composer](https://developer.apple.com/icon-composer/) icon instead, export a `.icon` file to
  `assets/expo.icon`: `app.config.ts` sets `ios.icon` to it only when that file exists, and
  `gen:assets` never touches it.
</Callout>

The name, ids, icon and splash are native, so rebuild to see them. `bun run ios` compiles the
dev build locally (it needs Xcode; `bun run android` needs Android Studio), or you can build one
on EAS - see [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build).

<Cmd>
  bun run ios
</Cmd>

**You should see:** your icon and "Trailmix (Dev)" on the home screen, and your splash on
launch.

## 6. Rewrite the onboarding [#6-rewrite-the-onboarding]

<If cat="onboarding" is="on">
  The three slides are the `SLIDES` array at the top of
  `src/screens/onboarding/onboarding-screen.tsx`. Each slide has an SF Symbol (`icon`), a Material
  fallback for Android and web (`fallback`), and two strings; `{{name}}` becomes your app name.

  ```tsx title="src/screens/onboarding/onboarding-screen.tsx"
  const SLIDES: readonly Slide[] = [
    {
      icon: "map",
      fallback: "map",
      title: "Welcome to {{name}}",
      description: "Log every trail you walk, with the photos and notes that go with it.",
    },
    {
      icon: "camera",
      fallback: "photo_camera",
      title: "Snap as you go",
      description: "Photos land on the trail they were taken on - no sorting later.",
    },
    {
      icon: "checkmark.seal",
      fallback: "verified",
      title: "You're all set",
      description: "Start your first trail from the Home tab.",
    },
  ];
  ```

  The strings are i18n keys (the English text is the key). With an i18n module selected, add each
  new string to every `src/locales/*.json` - a test checks all locales have the same keys - and
  delete the old slide keys.

  **You should see:** in **Settings → Reset onboarding**, then a relaunch, your three slides.
</If>

<Else cat="onboarding" is="on">
  You picked `onboarding=off`, so there are no slides to rewrite. Skip to the next step.
</Else>

## Check it [#check-it]

<Cmd>
  bun run doctor
</Cmd>

It warns while `app.name` is still `ReadyNative`, the ids are still `com.acme.app`, or the
`urls` and `store` fields are empty. Fill those in before your first store build - the Settings
screen links to `urls.privacy`, `urls.terms` and `urls.support`. The Free tier has no `doctor`,
so read those fields in `readynative.config.ts` yourself. Then:

<Cmd>
  bun run typecheck
</Cmd>

## If it doesn't work [#if-it-doesnt-work]

* **Colours didn't change** - run `bun run gen:theme` again (on Free, check the
  `--primary` triple you edited in `src/global.css`), then restart with
  `bun run start -- -c`. NativeWind caches the old CSS.
* **The icon or name is still ReadyNative's** - you're in Expo Go, or in a dev build made before
  the change. Rebuild with `bun run ios` / `bun run android` or a new EAS build.
* **`gen:assets` hangs or fails** - it needs Node >= 22.18 and a square PNG of at least 1024 px
  at `assets/brand/icon.png`. On Free there is no `gen:assets`: the files you replaced in
  `assets/images/` must keep their names and be square PNGs.
* **"Unable to resolve ../../assets/fonts/…"** - the path in `require()` is relative to
  `src/app/_layout.tsx`, and the file name must match exactly, case included.
* **A locale test fails after editing the slides** - with an i18n module and jest, a new string
  is missing from one of the `src/locales/*.json` files. The Free tier has neither.

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

It's your app now: your name, ids, colours in both modes, icon, splash, font and first-run copy.
Next, build something in it: [Add your first feature](https://readynative.app/docs/first-feature).


# Module spec (/docs/module-spec)



{/* Generated by apps/docs/scripts/gen-modules.ts from docs/module-spec.md - do not edit. */}

Every optional thing lives in `modules/<category>/<option>/` with `module.json`, `files/` (a mirror of repo-root paths), and `docs.md`.
`bun setup` copies selected `files/**` to the root byte-for-byte, deletes files owned only by non-selected modules, generates the files below, patches package/app/tsconfig, strips the demo content (unless `--with-examples`), drops the `readynative:contract-lint` entry from `eslint.config.js` (unless `--keep-modules`), finalizes the tree (see "Finalize" below, unless `--keep-modules`) and (unless `--keep-modules`) removes `modules/`.
&#x2A;*Invariant:** the committed root tree == `setup --preset default --with-examples --keep-modules` output (diff empty except lockfile and `.readynative.json`). The drift check for the dev loop is therefore:

```bash
bun run setup --dry-run --preset default --with-examples --keep-modules --yes   # must report only .readynative.json to write
```

The root keeps the examples and the lint contract on purpose: every UI stack in `modules/` has to compile the shipped screens, which is what the `no-restricted-imports` entry marked `// readynative:contract-lint` enforces. Buyers get neither - a default `setup` run removes both.

## Finalize (the buyer's tree) [#finalize-the-buyers-tree]

After the strip/ESLint step, and **only when `--keep-modules` is absent**, setup runs
`scripts/lib/finalize.ts` (`planFinalize` → moves / deletes / rewrites / packageJson, then the
same reporting writer as the rest of apply). `verify-modules.sh` always passes
`--keep-modules`, so finalize never runs there and the dev loop keeps the product tree.

* **F1 - components.** `src/ui/<active stack>/*` → `src/components/ui/*` (flat), plus
  `src/ui/theme-mode.ts` and `src/ui/__tests__/`. `src/ui/contract.ts` becomes
  `src/components/ui/types.ts` - everything after its `// readynative:uikit` marker (the `UiKit`
  type) is cut, the prop types stay because 20 components import them. The stack's `index.ts`
  loses `import type { UiKit }`, the `const kit = { … } satisfies UiKit` object and its default
  export, and gains the re-exports the generated `src/ui/index.ts` carried (`./theme-mode`,
  `./types`). Every `@/ui…` reference in `src/**`, `scripts/**`, `jest.setup.ts`, `.maestro/**`
  and the root `*.ts(x)/js` files (comments included) is rewritten:
  `@/ui` → `@/components/ui`, `@/ui/contract` → `@/components/ui/types`,
  `@/ui/<stack>/x` → `@/components/ui/x`. `jest.setup.ts` loses its `// readynative:ui-jest-setup`
  block in favour of a plain `require("./src/components/ui/jest-setup")`.
* **F2 - tooling.** `scripts/` keeps `doctor`, `gen-assets`, `gen-links`, `gen-theme`, `e2e`
  (+ `lib/{args,format,doctor,gen-assets,gen-links,gen-theme,e2e,readynative-state}.ts` and the
  `gen-theme-<gen id>.ts` emitter of the active stack) and the tests of the kept scripts that
  do not need `scripts/test-utils/fixture.ts`. `scripts/lib/gen-theme.ts` keeps only the
  `// readynative:gen <id>` lines of the active stack, so its renderer map is a direct call.
  `docs/`, `examples/`, `tools/` and `.github/workflows/docs.yml` are deleted, `ci.yml` is
  replaced by a typecheck/lint/test job, `README.md` / `AGENTS.md` are rendered from
  `scripts/lib/templates/`, and package.json loses `gen`/`clean`/`docs`/`release`/`verify`
  and `@clack/prompts` (`setup` stays as a one-line "already applied" echo so a second
  `bun run setup` exits 0). `bun install` runs after all of this, so `bun.lock` is refreshed.

Nothing outside `scripts/lib/finalize.ts` knows about the buyer's layout: the scripts that
survive read `.readynative.json` through `scripts/lib/readynative-state.ts`, which imports no part
of the module system (catalog / registry / schema / resolve).

## Categories / options (first = default) [#categories--options-first--default]

ui nativewind4·nativewind5·tamagui·unistyles·stylesheet | data react-query·apollo·swr·none | state zustand·jotai·none |
storage kv-store·mmkv·async-storage | forms react-hook-form·none | i18n i18next·lingui·none | auth supabase·clerk·better-auth·none |
payments revenuecat·adapty·stripe·none | analytics posthog·amplitude·none | crash sentry·none | push expo-notifications·none |
backend api-routes·none | onboarding on·off | testing jest·none
Presets: `minimal` (ui nativewind4 + storage kv-store, everything else none/off), `default` (nativewind4, react-query, zustand, kv-store, react-hook-form, i18next, onboarding on, testing jest, others none), `saas` (default + supabase, revenuecat, posthog, sentry, expo-notifications, api-routes).
Phase 2 ships only the modules the `default` and `minimal` presets need (plus `none`/`off` modules for every category). Unknown options in a preset → setup error.

## module.json [#modulejson]

```jsonc
{
  "id": "react-query",
  "category": "data",
  "label": "TanStack Query",
  "hint": "server state + cache · Expo Go OK",
  "expoGo": true, // false → doctor requires a dev build
  "recommended": false, // true → docs flag it as "most people pick this"
  "dependencies": { "@tanstack/react-query": "^5.102.0" },
  "devDependencies": {},
  "expoInstall": [], // passed to `bunx expo install`
  "package": { "scripts": {}, "overrides": {}, "lint-staged": {} }, // shallow-merge into package.json (per top-level key)
  "app": { "expo": { "plugins": [] } }, // JSON merge patch onto app.config extras - see "app patch" below
  "tsconfig": { "include": [] }, // append-unique
  "files": ["src/lib/query.tsx"], // root-relative; must exist under files/
  "removeFiles": [], // root paths deleted when this module is selected
  "providers": [{ "import": "QueryProvider", "from": "@/lib/query", "order": 20 }],
  "env": [
    {
      "key": "EXPO_PUBLIC_API_URL",
      "example": "https://api.example.com",
      "required": false, // doctor-only: true → `bun doctor` fails when the key is unset (see "env")
      "docsUrl": "",
      "server": false, // true → server-only secret: no EXPO_PUBLIC_ prefix, never in src/lib/env.ts
    },
  ],
  "requires": { "storage": ["kv-store", "mmkv", "async-storage"] }, // category → allowed options
  "recommends": {},
  "conflicts": [], // conflicts: ["<category>/<option>"]
  "gen": [], // gen-theme targets, ui only: ["nativewind5"]
  "doctor": [{ "type": "env", "keys": ["EXPO_PUBLIC_API_URL"] }, { "type": "devBuild" }],
  "postSetup": ["..."],
  "privacy": {
    // what this module's SDK collects; composed by setup, see "privacy"
    "dataTypes": [
      {
        "type": "NSPrivacyCollectedDataTypeEmailAddress",
        "linked": true,
        "purposes": ["NSPrivacyCollectedDataTypePurposeAppFunctionality"],
      },
    ],
    "accessedApis": [{ "type": "NSPrivacyAccessedAPICategoryUserDefaults", "reasons": ["CA92.1"] }],
    "tracking": false,
    "trackingDomains": [],
    "playDataSafety": {
      "sdk": "X (cat/opt)",
      "collects": ["..."],
      "sharedWith": "X (processor)",
      "disclosureUrl": "https://...",
    },
  },
}
```

### env [#env]

* `required` never changes the generated `src/lib/env.ts` (every key is `z.string().optional()`): a missing key must degrade the module ("Configure X"), not crash the app at import time. It only drives doctor: every `required: true` key is an implicit `{ "type": "env" }` check, so a module lists a key in `doctor` only when it is optional-but-worth-checking (e.g. `EXPO_PUBLIC_API_URL`). Explicit + implicit keys are merged per module and deduped.
* `server: true` (e.g. `BETTER_AUTH_SECRET`, `STRIPE_SECRET_KEY`): read via `process.env.X` in `src/app/api/**` / `src/server/**`; listed in `.env.example` under the trailing `# server` section; checked by doctor like any other key; **never** rendered into `src/lib/env.ts`, so it cannot leak into the bundle. Keys with `server: true` must not start with `EXPO_PUBLIC_`.
* A key declared by several selected modules (typically `EXPO_PUBLIC_API_URL`) is deduped **first-wins** in copy order (`ui` first, then catalog order): the first module's `example` + `docsUrl` land in `.env.example` and in the doctor check; `required` is OR-ed.

### Core dependencies [#core-dependencies]

`CORE_DEPENDENCIES` in `scripts/lib/catalog.ts` = every root `dependencies`/`devDependencies` key that no `default`-preset module declares (`expo`, `expo-constants`, `expo-device`, `react-native`, `zod`, …). `removeDependencies` never touches them, so a module may redeclare a core package it imports (`push/expo-notifications` → `expo-device`, `expo-constants`) without turning it off for every selection that lacks the module. A unit test asserts the constant ⊆ root package.json; regenerate the list when core deps change.

`none`/`off` modules: `{ id, category, label, hint, expoGo: true, recommended: false, files: [], providers: [], env: [] }` - everything else optional. Schema is zod in `scripts/lib/schema.ts`; every field except `id/category/label` has a default.

### privacy [#privacy]

Declared once per module, composed by `resolvePlan` (`composePrivacy`): `dataTypes` dedupe by type (`linked`/`tracking` OR-ed, purposes unioned), `accessedApis` dedupe by category (reasons unioned), `tracking` OR-ed, domains unioned. The result is patched into `app.expo.ios.privacyManifests` (so `app.config.ts` ships an Apple privacy manifest without a static block) and the `playDataSafety` rows are stored in `.readynative.json` → `modules.privacy.dataSafety`, which `bun run doctor --store` prints as the Play Data safety draft - a finalized tree has no `modules/` to read. Storage modules declare the `UserDefaults` required-reason API (they are the callers); service modules declare their data types and a Data safety row; `none` options declare nothing.

### app patch [#app-patch]

`app.config.ts` reads `.readynative.json` → `modules.app` (merged patch of every selected module's `app.expo`) and applies it: `plugins` append-unique by plugin id (string or `[id, opts]`), other keys deep-merged. So app.config.ts stays hand-written and modules never edit it.

## Generated files (owned by setup, never by modules) [#generated-files-owned-by-setup-never-by-modules]

* `src/ui/index.ts`:
  ```ts
  /**
   * THE swap point: `bun setup` rewrites this file to re-export the active stack.
   * Screens, components and routes import UI only from `@/ui`.
   */
  export * from "./contract";
  export * from "./theme-mode";

  export * from "./<ui option>";
  ```
* `src/providers.tsx`: header comment (the 10..90 order table as today), then imports sorted by `order` then `import` name, one `import { X } from "from";` line each (`ThemeProvider as UiThemeProvider` for the ui provider - the ui module declares `{ "import": "ThemeProvider", "as": "UiThemeProvider", "from": "@/ui", "order": 50 }` - `as` is an optional field), and `ToastHost` from `@/ui` (always, order 90, rendered after children). Body: nested JSX from lowest order outward, `{children}` innermost, `<ToastHost />` right after `{children}` inside the innermost provider. Prettier-formatted (run prettier on the output string via its API).
* `src/lib/env.ts`: same structure as today; one `z.string().optional()` line per public (non-`server`) env key across selected modules (`APP_VARIANT` always first; `required` is doctor-only, see "env"), `raw` object listing `optional(process.env.EXPO_PUBLIC_<KEY>)` per key. Keys sorted, deduped.
* `.env.example`: header, `APP_VARIANT=dev`, `EXPO_PUBLIC_APP_VARIANT=dev`, then per module a `# <label>` comment + `KEY=example` lines (+ `# docs: url`) for its public keys (a key shared by two modules appears once, first wins), then one `# server (never EXPO_PUBLIC)` section with the `server: true` keys grouped per module.
* `.readynative.json`: `{ "version": 1, "preset": "default" | null, "selection": { "<category>": "<option>" }, "applied": true, "modules": { "app": {...merged app patch...}, "postSetup": [...] , "doctor": [...] }, "keepModules": true|false }`.
* `package.json` patches: add module `dependencies`/`devDependencies` (remove deps that belong ONLY to non-selected modules and are not in `CORE_DEPENDENCIES`), merge `package` block; sub-keys of object blocks (e.g. `scripts.test`) and `tsconfig.include` entries that belong ONLY to non-selected modules are removed the same way. Keys sorted like bun does. Top-level scalar `package` keys (e.g. `main`) are set by the selected module that declares them; when only non-selected modules declare one, the core default from `PACKAGE_CORE_DEFAULTS` (`main: "expo-router/entry"`) is restored, or the key is deleted if it has no core default. JSON rewrites (package.json, tsconfig.json) are prettier-formatted and only happen when the parsed value changes.
* Core tooling deps stay in the root `package.json` even when a module would also bring them (e.g. `@types/node`, needed by `app.config.ts` and `scripts/**`; with TS 6 the tsconfig lists `"types": ["node"]` explicitly). Engine unit tests (`scripts/__tests__/**`, `scripts/test-utils/**`) and `jest.config.js` are owned by `testing/jest`.

## Ownership [#ownership]

Core (never removed): everything not listed in any `module.json.files`. A file listed by several modules is removed only if none of its owners is selected. A selected module's `removeFiles` beats every owner, selected or not - the path is not copied and is deleted. Copy order: `ui` first, then category order above.

### Tests and mocks [#tests-and-mocks]

* **Module-owned tests live in the module's `files/`** (e.g. `modules/storage/mmkv/files/src/lib/__tests__/storage-mmkv.test.ts`, `modules/data/swr/files/src/hooks/__tests__/use-example-query.test.tsx`). Two options of one category may own the same test path (`src/stores/__tests__/example-store.test.ts` is owned by both `state/zustand` and `state/jotai`); the selected one's copy wins.
* **Every shared test path must also be listed in `testing/none.removeFiles`** (the per-stack `src/ui/<stack>/jest-setup.ts` included), so `--testing none` leaves no `__tests__` behind regardless of which options own them - selected owners too, since `removeFiles` wins over `files`. When you add a test to a module, add its path there too (`bunx jest scripts` - `registry.test.ts` - checks `files[]` entries exist; the `--testing none` verify run is what catches a missing `removeFiles` entry).
* **Storage modules mock their native package with jest's `__mocks__/` auto-mock convention**: a root-level `__mocks__/<package-name>.ts` (`modules/storage/mmkv/files/__mocks__/react-native-nitro-modules.ts`, `modules/storage/async-storage/files/__mocks__/@react-native-async-storage/async-storage.ts`) is picked up automatically for that node module - no `jest.mock()` call in `jest.setup.ts`. The core `jest.setup.ts` mocks `expo-sqlite/kv-store` with `{ virtual: true }` so it stays valid when `expo-sqlite` is not installed (`storage=mmkv|async-storage`). Core tests never import a storage package directly; they go through `@/lib/storage` (`storage.getItem/setItem`, async) so they pass on every adapter.

## Scripts (`bun run scripts/<x>.ts`) [#scripts-bun-run-scriptsxts]

* `setup [--preset p] [--<category> <option>]… [--yes] [--dry-run] [--no-install] [--keep-modules] [--with-examples] [--root <dir>]` - interactive via @clack/prompts when a TTY and not `--yes`. Idempotent: same selection → no diff, exit 0. When `modules/` is gone (a previous run without `--keep-modules`) and `.readynative.json.applied` is set: same selection → "Already applied", exit 0; different selection → error pointing at `--keep-modules`.
* `gen-theme [--check] [--root <dir>]` - tokens (+ brand) → one artefact set per ui module `gen` target, written under `modules/ui/<stack>/files/` and, for the active ui (`.readynative.json`, default nativewind4), at the root: `nativewind5` → `src/global.css`; `nativewind4` → `src/global.css` + `tailwind.config.js`; `tamagui` → `tamagui.config.ts`. Output is prettier-formatted. `--check` exits 1 on drift in any target.
* `doctor [--root <dir>]` - reads `.readynative.json`; checks env keys (`doctor` entries + every `required: true` key, `.env` then process env, with docsUrl), placeholders in `readynative.config.ts` (`com.acme.app`, empty urls/store ids), `eas whoami` (skip if eas-cli absent), Xcode (`xcode-select -p`) / Android SDK (`ANDROID_HOME`) when any selected module is `expoGo:false`, bun/node versions. Non-zero on failures, checklist output.
* `gen screen <name>` | `gen module <category> <option>` - scaffolders.
* `clean [--no-examples]` - the same strip `setup` runs: the examples tab (`src/app/examples`, `src/screens/examples`, `src/examples.ts`, the example hook/store and their tests) and its Settings row, `_catalog` and its Settings row, the weather demo (the Cities tab and its `<NativeTabs.Trigger>` in `src/app/(tabs)/_layout.tsx`, `src/screens/weather`, `src/lib/weather`, `src/stores/weather.ts`, `src/hooks/use-forecast.ts`), sample locales (keeps `en`, rewrites `src/lib/i18n.ts`), placeholder assets, `tools/`; the home screen becomes a plain welcome and the Weather tab turns back into Home. Every anchored edit is a no-op once applied and warns (never fails) when it cannot find its anchor. `--no-examples` keeps the weather demo and the examples tab.
  All scripts take `--root` so unit tests run them against a fixture tree in a temp dir. Logic lives in `scripts/lib/*.ts`; `scripts/<x>.ts` are thin CLIs.

## Service modules (auth · payments · analytics · crash · push · backend) [#service-modules-auth--payments--analytics--crash--push--backend]

* **Shim ownership.** `src/lib/{auth,analytics,crash,payments,push,location,widgets}.ts` are owned by the `<category>/none` module and are one-line re-exports of `src/lib/shims/<category>.ts` (same pattern as `i18n/none`). A real module lists the same `src/lib/<category>.ts` in `files[]` and ships its own implementation of the shim's exported interface (`Auth`, `Payments`, `Analytics`, `Crash`, `Push`, `Location`, `Widgets`) with the same export names - core only ever imports `@/lib/<category>`. `backend/none` owns nothing (`src/app/api/**` and `src/server/**` are `api-routes` files).
* **`src/hooks/use-auth-redirect.ts`** is owned by `auth/none` (no-op) and by every auth module. The root layout calls `useOnboardingRedirect()` then `useAuthRedirect()`; the contract (gate on `useRootNavigationState().key`, no-op while `loading`, `unauthenticated` outside `(auth)` → `router.replace("/(auth)/sign-in")`, `authenticated` inside `(auth)` → `router.replace("/")`, onboarding wins first) is documented in the hook itself. Auth modules ship the `src/app/(auth)/` group (sign-in/up/reset).
* **Core hooks already wired**: `_layout.tsx` calls `analytics.screen(pathname)` on every pathname change; the Settings screen renders an "Account" card with `auth.signOut()` only when `auth.useSession().status === "authenticated"`.
* **Examples slugs reserved** in `src/examples.ts` (the module owns `src/app/examples/<slug>.tsx`): `auth` (auth), `paywall` (payments), `analytics` (analytics), `crash` (crash), `push` (push), `api` (backend). Without the module the `[slug]` fallback renders "Module not installed".
* **`module.json` requirements** for every service module: every `env[]` entry has a non-empty `docsUrl`; the keys the module cannot work without are `required: true` (doctor checks them implicitly; an explicit `{ "type": "env", "keys": [...] }` entry is for optional keys still worth flagging, e.g. `EXPO_PUBLIC_API_URL`); server secrets are `server: true`; `{ "type": "devBuild" }` when `expoGo: false`; `postSetup` names the dashboard steps (create the project, paste keys, register bundle ids / webhooks); `docs.md&#x60; contains a &#x2A;*"Manual E2E checklist"** section (sandbox account → real device flow), since CI only proves the module builds.


# No ios/ or android/ folders (/docs/native-without-native-folders)



Hey - open the repo and you won't find `ios/` or `android/`. That's on purpose. ReadyNative uses
Expo's [Continuous Native Generation](https://docs.expo.dev/workflow/continuous-native-generation/)
(CNG): the Xcode and Gradle projects are build output, generated from your config every time you
build, the same way `dist/` is generated from `src/`.

## Why it matters [#why-it-matters]

* **Upgrades are a version bump.** Moving to the next Expo SDK is `bunx expo install expo@latest --fix` and a rebuild - there's no hand-merged Podfile, AppDelegate or `build.gradle` to reconcile.
* **Native config is reviewable.** Bundle ids, permissions, entitlements and plugins are a few lines
  of TypeScript in a pull request, not a 3,000-line `project.pbxproj` diff.
* **Modules can't drift.** Picking `--widgets expo-widgets` adds a widget extension target, an App
  Group and `NSSupportsLiveActivities`; picking `none` removes them. Nobody edits Xcode by hand, so
  nothing is left behind.
* **No Mac required.** EAS generates and builds the native projects in the cloud.

## Where native config lives [#where-native-config-lives]

| What                                                   | Where                                                                                                                |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| App name, bundle id, scheme, brand colours, store ids  | `readynative.config.ts` - the one file you edit                                                                      |
| Everything else in the Expo config                     | `app.config.ts`, which reads `readynative.config.ts`                                                                 |
| What each module needs (plugins, permissions, privacy) | the module's app patch, merged by `setup` into `.readynative.json` and applied by `app.config.ts`                    |
| Anything the Expo config can't express                 | a [config plugin](https://docs.expo.dev/config-plugins/introduction/) in `plugins/` (e.g. `with-scene-lifecycle.js`) |
| Apple privacy manifest                                 | composed from every selected module's `privacy` block - see [Privacy](https://readynative.app/docs/privacy)                                 |

Want to see the result? Generate the projects locally and look - they're gitignored:

<Cmd>
  bunx expo prebuild --clean
</Cmd>

`bun run ios` / `bun run android` (and every `eas build`) do that for you before compiling.

## Adding a native library [#adding-a-native-library]

1. Install it with `bunx expo install <package>` so you get the version that matches the SDK.
2. If it ships a config plugin, add it to `plugins` in `app.config.ts` with its options.
3. Rebuild the dev build (`bun run ios`) - JavaScript reloads can't add native code.

That's the whole flow; there's no `pod install` to run or Xcode setting to flip.

## Pairs with over-the-air updates [#pairs-with-over-the-air-updates]

Because the native layer is generated from config, it's clear what needs a store release and what
doesn't. `runtimeVersion` follows the app version (`policy: "appVersion"`), and every EAS build
profile publishes to its own channel (`development`, `preview`, `production` in `eas.json`), so:

* **JavaScript, assets, translations, screens** - ship with `eas update`; installed apps show the
  built-in **Update ready** banner and restart into it. [Your first update](https://readynative.app/docs/your-first-update)
  walks through it.
* **Anything in the table above, or a new native library** - bump the version and ship a store
  build; an update can never reach a binary it doesn't match.

## When you'd commit native folders [#when-youd-commit-native-folders]

Rarely. If you must hand-edit native code that no config plugin covers, you can run
`bunx expo prebuild`, commit `ios/` and `android/`, and maintain them yourself from then on - but
you give up regenerated upgrades and module switching. Writing a small config plugin in `plugins/`
is almost always the better trade.


# Package managers (/docs/package-managers)



Every command in these docs is written as a bun command and rendered for four package
managers. Switch with the tab strip above each block; your choice sticks across the whole site.
Nothing in ReadyNative requires bun.

## bun is the default, not a requirement [#bun-is-the-default-not-a-requirement]

I recommend bun because it's the fastest of the four here and doubles as a TypeScript runtime.
But `setup`, `doctor` and the generators are plain `node scripts/*.ts` files, so they run under
whichever package manager you use:

<Cmd>
  bun install
</Cmd>

<Cmd>
  bun run setup
</Cmd>

<Callout type="info" title="npm needs a double dash">
  npm hands flags to itself unless you separate them: `npm run setup -- --preset saas --yes`. The
  tabs above already do this for you; pnpm, yarn and bun pass flags straight through.
</Callout>

## Node version [#node-version]

`scripts/*.ts` run under plain `node`, which strips TypeScript types natively from **22.18**
onwards - that's what `engines.node` in `package.json` asks for, and **Node 24 LTS** is what I
run. `setup` and `doctor` run `scripts/check-node.cjs` first, a plain CommonJS check that works
on any Node, so an older one gets "ReadyNative needs Node ≥ 22.18 (you have vX)" instead of a
syntax error. `doctor` also fails its Node row below 22.18.

## pnpm needs a hoisted `node_modules` [#pnpm-needs-a-hoisted-node_modules]

pnpm's default layout is a tree of symlinks, and Metro doesn't resolve the app's dependencies
through it reliably. Put this `.npmrc` at the root before the first `pnpm install`:

```ini title=".npmrc"
node-linker=hoisted
```

That's the configuration I test pnpm trees with. npm, yarn and bun need nothing.

## How `setup` picks your package manager [#how-setup-picks-your-package-manager]

`setup`, `finalize` and `doctor` all resolve it the same way, first match wins:

| Order | Source                                                                                           |
| ----- | ------------------------------------------------------------------------------------------------ |
| 1     | The `--pm <name>` flag                                                                           |
| 2     | `npm_config_user_agent` - the package manager that launched the script                           |
| 3     | The `packageManager` field in `package.json` (what corepack reads)                               |
| 4     | A lockfile on disk: `bun.lock` / `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json` |
| 5     | `bun` if it is on your PATH, otherwise `npm`                                                     |

In practice step 2 is enough: run `pnpm install && pnpm run setup` and the whole tree is a
pnpm tree. To force it explicitly:

<Cmd>
  bun run setup --pm pnpm
</Cmd>

`--pm` only accepts `bun`, `pnpm`, `yarn` or `npm`; anything else is an error rather than a
silent fallback. `setup` prints the answer in its plan (`package manager: pnpm
(pnpm-lock.yaml)`), writes the name into `.readynative.json`, and `bun run doctor` shows it as its
own row.

## What each one runs [#what-each-one-runs]

Here's how the everyday commands map across the four:

| Package manager | install        | CI install                       | run a script                 | run a binary             |
| --------------- | -------------- | -------------------------------- | ---------------------------- | ------------------------ |
| bun             | `bun install`  | `bun install --frozen-lockfile`  | `bun run <script>`           | `bunx <bin>`             |
| pnpm            | `pnpm install` | `pnpm install --frozen-lockfile` | `pnpm run <script>`          | `pnpm exec <bin>`        |
| yarn            | `yarn install` | `yarn install --immutable`       | `yarn run <script>`          | `yarn run <bin>`         |
| npm             | `npm install`  | `npm ci`                         | `npm run <script> -- <args>` | `npx --no-install <bin>` |

The "run a binary" column never reaches out to a registry: `pnpm exec` and `npx --no-install`
fail loudly instead of downloading something, and `bunx` prefers `node_modules/.bin`. That's
what `expo install`, `expo start` and `eas-cli` go through.

## Lockfiles [#lockfiles]

The repo you clone ships `bun.lock`. When `setup` finalizes the tree with another package
manager it deletes the lockfiles that don't belong to it - a stale `bun.lock` next to
`package-lock.json` is exactly the kind of thing that makes CI install the wrong versions.

It also drops a `"packageManager": "bun@…"` field from `package.json` when you pick npm, pnpm or
yarn: they read that field through corepack and would refuse to run if it named a different tool.
`setup` never adds the field, so the lockfile is the declaration.

## CI [#ci]

Your tree ships no CI workflows. If you add your own, use the frozen/immutable install command
from the table above, and your package manager's script syntax (`--` included where npm needs
it). Expo's [GitHub Actions guide](https://docs.expo.dev/eas-update/github-actions/) covers the
EAS side.

## Switching later [#switching-later]

A finalized tree switches by hand, because `setup` is a stub by then:

1. Delete the old lockfile (and a `"packageManager"` field in `package.json`, if you're leaving
   bun).
2. Install with the new package manager so it writes its own lockfile.
3. If you added your own CI, update its setup and install steps - the table above has the
   commands.

In a tree kept with `--keep-modules`, `bun run setup --pm npm --yes --keep-modules` removes the
other lockfiles and installs with npm; edit any CI you added the same way.


# Pass App Review (/docs/pass-app-review)



<Badge>
  Pro
</Badge>

Hey - by the end of this page you'll have a build that passed `bun run doctor --store`, a
report from the `store-review` skill with every finding tied to a guideline id, and the store
metadata filled in from that report. Then you submit.

Nobody can promise approval - reviewers are people and the guidelines move. What this page
does is take the rejections that are predictable off the table before you wait a week to
hear about them.

## 1. Run the check ✅ [#1-run-the-check-]

From your app's root:

<Cmd>
  bun run doctor --store
</Cmd>

It reads `readynative.config.ts`, `app.config.ts`, `.readynative.json` and your `package.json`, and
prints one finding per problem - blocking, warning or info - with its id, platform, guideline
citation, the file and line, and the fix:

```
Store review check
Blocking - fix before you submit (1)
✗ Missing usage string for expo-location  [ios-usage-string-missing · ios · App Store Review 5.1.1(i)]
    app.config.ts:41
    expo-location is installed but ios.infoPlist has no NSLocationWhenInUseUsageDescription
    fix: Add the "expo-location" config plugin to plugins (with its *Permission prop) or set ios.infoPlist.NSLocationWhenInUseUsageDescription.
```

It also prints a Data safety draft - one row per SDK you selected, with what it collects and
the vendor's disclosure page. Keep that output open; you'll paste from it in step 3.

In a Starter tree the command prints that the check is part of Pro and exits.

## 2. Fix the blocks [#2-fix-the-blocks]

Work top to bottom. The findings that come up most:

* **Account deletion** (App Store Review 5.1.1(v), Play Account deletion) - if you picked any
  [auth](https://readynative.app/docs/features/auth) option, users can create an account, so the app has to let them
  delete it from inside the app. The finding points at the settings screen; wire a "Delete
  account" row to `deleteAccount()` in `src/lib/auth.ts`, and if you offer Sign in with Apple,
  revoke the token server-side.
* **Sign in with Apple** (App Store Review 4.8) - a Google or other social button on the sign-in
  screen means Apple's button has to be there too, with the same prominence.
* **Paywall copy** (App Store Review 3.1.2(c), Play Subscriptions) - price, billing period and
  renewal terms on the paywall itself, plus a Restore Purchases action. The
  [payments](https://readynative.app/docs/features/payments) module ships these; the finding fires if you removed one
  or if `urls.terms` / `urls.privacy` in `readynative.config.ts` are still empty.
* **Digital goods through in-app purchase** (App Store Review 3.1.1, Play Payments policy) -
  subscriptions or unlocks used inside the app must be sold through StoreKit / Play Billing
  (the RevenueCat or Adapty option). Stripe Checkout alone is fine for physical goods and
  services; for digital Pro it is allowed as a link-out on the US App Store storefront, and
  elsewhere only with Apple's external purchase entitlement. Offering both rails, as the Snap
  Recipe example does, is the safe shape.
* **Purpose strings** (App Store Review 5.1.1(ii)) - every permission-bearing dependency needs its
  `NS*UsageDescription` in `app.config.ts`, and the string names the feature, not the
  permission.
* **Tracking** (App Store Review 5.1.2(i)) - analytics or ads SDKs that link your data with other
  companies' data need the App Tracking Transparency prompt. The analytics modules ship
  `expo-tracking-transparency` with a purpose string; set `features.tracking: true` in
  `readynative.config.ts` and `app.config.ts` adds its plugin and `NSPrivacyTracking: true`,
  and `AnalyticsProvider` asks once the app is active, with `analytics.identify` waiting for
  consent. Off (the default), Android's `AD_ID` permission is blocked and `doctor --store`
  reminds you to answer "No" to tracking in App Store Connect.
* **Privacy manifest** (ITMS-91053) - setup composes `ios.privacyManifests` from the selected
  modules' declarations; the finding fires if it is missing or declares tracking while
  `features.tracking` is off. The [Privacy and consent](https://readynative.app/docs/privacy) page has the full picture.
* **Placeholders** - `com.acme.app`, an empty `urls.support`, the default app name. Reviewers
  read them as an unfinished app (App Store Review 2.1(a)). [Config](https://readynative.app/docs/config) lists every field.

Re-run the command until it is green.

## 3. Fill in the metadata 📋 [#3-fill-in-the-metadata-]

The stores ask for things no file in your tree can prove. Go through these in App Store
Connect and the Play Console before you upload:

* Screenshots that show the app in use - not the splash or sign-in screen - for every device
  class you support: iPhone, iPad if `supportsTablet` is on, phone plus 7" and 10" tablets on
  Play.
* The age rating questionnaire, answered from what the app actually contains.
* Export compliance: `ITSAppUsesNonExemptEncryption` in `app.config.ts` matches your answer.
* A demo account in the App Review notes when anything sits behind sign-in, and a backend that
  stays up while the reviewer is in.
* The Data safety form on Play and the App Privacy answers in App Store Connect, filled from
  the draft table `doctor --store` printed - every SDK in `.readynative.json` accounted for.
* A privacy policy URL and a support URL that are live, public and reachable from Settings.
* On Play, the account-deletion web link in the Data safety form.

<Callout type="warn" title="The draft table is a starting point, not an answer">
  `doctor --store` knows which SDKs you selected and what their vendors say they collect. It does
  not know what your own backend stores. Add your own data types before you submit the form - an
  inaccurate Data safety form gets updates blocked.
</Callout>

## 4. Run the skill with your agent 🤖 [#4-run-the-skill-with-your-agent-]

The mechanical check cannot judge copy, flows, or whether a permission prompt reads as a
reason. That is the [store-review skill](https://readynative.app/docs/for-agents/store-review). In Claude Code, Cursor
or any agent that reads `.agents/skills/`:

```
Run the store-review skill on this app and give me the report.
```

It runs `doctor --store`, reads the paywall, onboarding, sign-in and settings screens against
the distilled App Store and Play checklists, optionally screenshots them on the simulator, and
returns a table of findings - likely rejection, fix before submit, fine - each with the
guideline id and `file:line`. Fix the first two groups, then ask it to run again.

## 5. Submit [#5-submit]

Build and submit the way [Ship to TestFlight](https://readynative.app/docs/ship-to-testflight) set up:

```bash
bunx eas-cli build --profile production --platform all
bunx eas-cli submit --platform all
```

Paste the demo account and a specific description of what is new into the review notes
(App Store Review 2.3.1 rejects generic ones), then submit for review.

## Congrats 🎉 [#congrats-]

You submitted with every predictable rejection already handled and a report you can hand to
whoever asks why a screen looks the way it does. If a reviewer still comes back with
something, the reply cites the guideline they name - run the skill again with their message
and it will tell you which finding it maps to. Next: keep users current without another
review with [Your first update](https://readynative.app/docs/your-first-update).


# Pick your stack (/docs/pick-your-stack)



Hey - this is the page I'd read before running `bun run setup`. Seventeen categories, one
answer each. By the end you'll know which answers matter for your app and which you can leave
on the default.

Two questions decide a category more often than taste:

* **Does it need a dev build?** `storage=mmkv`, `ui=unistyles`, `payments=revenuecat|adapty`,
  `widgets=expo-widgets` and remote push ship native code, so Expo Go can't run them. Everything else can - see
  [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build).
* **Does it need keys?** The service categories (auth, payments, analytics, crash, push,
  backend) need a dashboard and a `.env` entry before they do anything.

Choose carefully: unless you pass `--keep-modules`, `setup` finalizes the tree and you can't
re-run it with another answer ([How setup works](https://readynative.app/docs/how-setup-works)).

## Set your stack in the sidebar [#set-your-stack-in-the-sidebar]

Pick an option in the **Your stack** panel at the top of the sidebar and every page on this
site switches to it: tutorial code samples change, the Features tree hides the options you
didn't pick, and the option pages of a category outside your stack tell you so.

Two shortcuts:

* `bun run setup` and `bun run doctor` both print
  `https://readynative.app/docs/?stack=ui:tamagui,auth:supabase,…`. Open that link and the docs
  already match your tree.
* The panel's &#x2A;*Import `.readynative.json`** button reads the file `setup` wrote and does the
  same from a local checkout.

## The categories [#the-categories]

Each heading links to the category's Features page, where every option has its own
Setup / Usage / Gotchas guide. [Stack comparison](https://readynative.app/docs/choose-your-stack) puts every option of
every category in one generated table, with Expo Go verdicts, `requires` / `conflicts` rules and
the env keys each one needs.

### [UI](https://readynative.app/docs/features/ui) [#ui]

NativeWind 4 (stable, Tailwind 3) is the default and what I'd keep. NativeWind 5 is one flag
away - `--ui nativewind5`, labelled "RC · Tailwind 4" in the picker because it is still a
release candidate (`5.0.0-rc.0`); pick it if you want Tailwind 4 today. Pick Tamagui for its
compiler and theme system, Unistyles for a C++ StyleSheet with themes and breakpoints (dev
build), `stylesheet` for no style engine at all. Whichever you pick, screens use the same
primitives from `@/components/ui` - see [Styling](https://readynative.app/docs/styling).

### [Data](https://readynative.app/docs/features/data) [#data]

TanStack Query for REST, Apollo if your backend is GraphQL, SWR if you want the smallest
stale-while-revalidate hook, `none` for plain `fetch`. With `none` you can still add any of
them by hand later with `bunx expo install`.

### [State](https://readynative.app/docs/features/state) [#state]

Zustand by default, Jotai if you think in atoms, `none` for `useSyncExternalStore` stores
only. Both libraries persist through the storage adapter, so they require a real `storage`
option.

### [Storage](https://readynative.app/docs/features/storage) [#storage]

`expo-sqlite/kv-store` gives you sync and async key/value on SQLite in Expo Go. MMKV is
faster but native (dev build). AsyncStorage is the async-only community standard. Auth
sessions, i18n and persisted stores all sit on top of this choice.

### [Forms](https://readynative.app/docs/features/forms) [#forms]

React Hook Form with a zod resolver, wrapped as `Form` + `Field` over the kit's `Input`; or
`none` and controlled inputs with `useState`.

### [i18n](https://readynative.app/docs/features/i18n) [#i18n]

i18next or Lingui, with English, Spanish, Russian, Chinese (Simplified), Portuguese and Arabic
bundled either way. Arabic is right-to-left: picking it mirrors the whole layout and restarts
the app (in a dev build - Expo Go resets the direction). With `none`, `i18n.t` and `useT` return
the English key, so screens keep compiling.

### [Auth](https://readynative.app/docs/features/auth) [#auth]

<Badge>
  Pro
</Badge>

Supabase gives you accounts plus a Postgres database behind them; Clerk gives you a hosted
user system with email-code verification; Better Auth runs on your own API routes (so it
requires `backend=api-routes`). `@/lib/auth` is the same API in all three - `auth.useSession()`,
`auth.signOut()` - and with `none` it reports signed-out forever.

### [Payments](https://readynative.app/docs/features/payments) [#payments]

<Badge>
  Pro
</Badge>

RevenueCat and Adapty handle StoreKit and Play Billing for you but need a dev build. Stripe
Checkout runs in Expo Go because the purchase happens on the web, through your API routes.
`payments.useEntitlements()` is the shim in all three cases.

### [Analytics](https://readynative.app/docs/features/analytics) [#analytics]

<Badge>
  Pro
</Badge>

PostHog (analytics plus feature flags) or Amplitude. With `none`, `analytics.track` /
`identify` / `screen` are no-ops you can leave in your code.

### [Crash reporting](https://readynative.app/docs/features/crash) [#crash-reporting]

<Badge>
  Pro
</Badge>

Sentry, or nothing. In Expo Go you get JS errors only; native crashes need a dev build.

### [Push](https://readynative.app/docs/features/push) [#push]

<Badge>
  Pro
</Badge>

`expo-notifications` covers local notifications in Expo Go and remote push in a dev build.
It requires a real `storage` option to keep the token.

### [Backend](https://readynative.app/docs/features/backend) [#backend]

<Badge>
  Pro
</Badge>

Expo Router `+api.ts` routes with `src/server` helpers, deployable to EAS Hosting - and the
prerequisite for Better Auth and Stripe. Or `none` if your backend lives elsewhere. Not sure
whether you need one at all? Read [Do I need a backend?](https://readynative.app/docs/backend) first.

### [Onboarding](https://readynative.app/docs/features/onboarding) [#onboarding]

`on` adds a three-slide intro at `/onboarding` that redirects until it is completed; `off`
opens straight into the tabs.

### [Location](https://readynative.app/docs/features/location) [#location]

`expo-location` gives screens the user's position and a place name, asking for "while using
the app" permission only; it runs in Expo Go. `location.getCurrentPosition()` resolves `null`
instead of throwing, whichever option you pick. Pick `none` if no screen needs it: no permission
prompt and no purpose string for App Review to question.

### [Widgets](https://readynative.app/docs/features/widgets) [#widgets]

`expo-widgets` adds an iOS home-screen widget written in TypeScript with `@expo/ui` SwiftUI
views, fed with `widgets.update({ title, value, subtitle, symbol })`. It needs a dev build.
`none` keeps the same call as a no-op, so you can wire it now and turn it on later.

### [Consent](https://readynative.app/docs/features/consent) [#consent]

`consent` shows a sheet in the EU/EEA, UK, Switzerland, Canada and Brazil (or everywhere, with
`privacy.askEverywhere`) that asks before analytics and crash reporting start; `none` treats
everyone as consented. You rarely pick it by hand: setup selects `consent` whenever an analytics
or crash module is in, and `none` when neither is. Pass `--consent none` only if you never ship
to those regions.

### [Testing](https://readynative.app/docs/features/testing) [#testing]

Jest with `jest-expo` and React Native Testing Library, including tests for the stores, the
theme and the UI kit. `none` removes the runner and every `__tests__` folder - including the
ones modules would have brought.

## Not sure? Start from a preset [#not-sure-start-from-a-preset]

`minimal`, `default` and `saas` are three complete answers; override single categories on top
of them. The table is in [Quickstart](https://readynative.app/docs/ship-in-5-minutes#the-presets), and
`bun run setup --dry-run` prints the full plan - selection, Expo Go verdict, dependency delta,
files touched - without changing anything.


# Privacy and consent (/docs/privacy)



Hey - by the end of this page you'll know which privacy work the tree does for you, where each
piece lives, and what you still have to do before you ship to the EU, the UK or California.
None of this is legal advice; it is the mechanism, so the lawyer's hour is spent on your words,
not on plumbing.

## What ships [#what-ships]

| Requirement                                                                        | What the tree does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Where                                                                                                                        |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Consent before analytics / crash reporting (GDPR, ePrivacy, UK GDPR, PIPEDA, LGPD) | Setup selects `consent/consent` whenever an analytics or crash module is in. It asks once, after onboarding, when a device locale region or a `Europe/*` time zone points to the EU/EEA, UK, Switzerland, Canada or Brazil, when the device has no region, or everywhere with `privacy.askEverywhere`. Undecided reads as **off** there and **on** elsewhere. PostHog, Amplitude and Sentry create **no client** until their category is consented to: no event, no feature-flag or remote-config request, no JS or native crash report, no session. | `src/lib/consent.ts`, `src/components/consent-sheet.tsx`, [consent](https://readynative.app/docs/features/consent/consent)                          |
| Proof of consent                                                                   | The stored record is `{ analytics, crash, doNotSell, version, decidedAt, updatedAt, source }`. Raising `CONSENT_VERSION` asks everyone in the ask group again.                                                                                                                                                                                                                                                                                                                                                                                       | `src/stores/consent.ts`                                                                                                      |
| Withdraw consent any time                                                          | Settings → Privacy has one switch per category the build has; turning one off stops that SDK right away (PostHog `optOut()`, Amplitude `setOptOut(true)`, `Sentry.close()`). No analytics or crash module, no switches.                                                                                                                                                                                                                                                                                                                              | `src/screens/settings/settings-screen.tsx`, `src/lib/privacy-categories.ts`                                                  |
| "Do not sell or share" (CCPA/CPRA)                                                 | A persisted switch in Settings → Privacy whenever an analytics module is selected; while it is on, analytics reads as off under either consent option. California is not detectable from the device, so it gets this opt-out rather than the sheet.                                                                                                                                                                                                                                                                                                  | same                                                                                                                         |
| Access / portability (GDPR Art. 15, 20)                                            | Settings → Privacy → "Export my data" writes `my-data-<date>.json` (expo-file-system) and opens the share sheet (expo-sharing): everything the storage adapter holds, minus credentials (keys such as Supabase's `sb-*-auth-token` are skipped, token and password fields redacted), plus the signed-in user's profile. Web gets the JSON as text.                                                                                                                                                                                                   | `src/lib/privacy.ts`                                                                                                         |
| Erasure (GDPR Art. 17, App Store Review 5.1.1(v), Play Account deletion)           | On Pro with an auth module, Settings → Account → "Delete account": with `backend=api-routes` it first asks `POST /api/privacy/delete` to erase the user at PostHog, Amplitude and RevenueCat (whichever have server keys), then calls `auth.deleteAccount()` - Supabase also deletes the user's Storage files, Better Auth asks for the password when the session is too old.                                                                                                                                                                        | `src/lib/account-data.ts`, `src/app/api/privacy/delete+api.ts` (only with `backend=api-routes`), [auth](https://readynative.app/docs/features/auth) |
| Local data on sign-out                                                             | Every sign-out (button, account deletion, expired session) wipes local data except theme, language, consent and onboarding, resets the analytics identity (new anonymous and device id; the opt-out survives) and clears the query cache.                                                                                                                                                                                                                                                                                                            | `src/hooks/use-sign-out-cleanup.ts`, `src/lib/privacy.ts`                                                                    |
| Data minimisation                                                                  | Sentry: `sendDefaultPii: false`; `beforeSend` and `beforeBreadcrumb` drop IP, email, username, headers, cookies and query strings and mask emails and tokens in messages, exception values, `extra` and breadcrumbs. Amplitude: no IP, ad id or carrier. Adapty: no IDFA, GAID or IP unless `features.tracking`. PostHog: no touch/screen autocapture.                                                                                                                                                                                               | the analytics / crash / payments modules                                                                                     |
| App Tracking Transparency (App Store Review 5.1.2(i))                              | Off by default (`features.tracking: false`): first-party analytics is not tracking. `app.config.ts` then drops the ATT plugin, blocks Android's `AD_ID` permission and writes `NSPrivacyTracking: false`. Flip it when you link data across companies: the plugin comes back, the manifest says `true`, the prompt runs once the app is active and `analytics.identify` waits for it.                                                                                                                                                                | `readynative.config.ts`, `app.config.ts`, `src/lib/tracking.ts`                                                              |
| Apple privacy manifest (ITMS-91053)                                                | Every module declares its collected data types and required-reason APIs; setup composes them into `ios.privacyManifests`, and `app.config.ts` sets `NSPrivacyTracking` from `features.tracking`. Analytics declares user id, device id, product interaction and coarse location, all linked.                                                                                                                                                                                                                                                         | `.readynative.json` → `modules.app.expo.ios.privacyManifests`                                                                |
| Play Data safety form                                                              | `bun run doctor --store` prints a draft row per selected SDK, from the modules' declarations.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `.readynative.json` → `modules.privacy.dataSafety`                                                                           |
| Privacy policy                                                                     | `bun run gen:privacy` writes `docs/privacy-policy.md` from the selection and the same declarations: what is collected and why, legal basis, processors, transfers, retention, and only the Settings controls this build actually has. Anything it cannot know is a `[CONFIRM: …]` placeholder.                                                                                                                                                                                                                                                       | `scripts/gen-privacy.ts`                                                                                                     |

`bun run doctor --store` ties it together: it warns when the manifest is missing, when the ATT
flag and the manifest disagree, when a privacy URL is empty, and when account deletion is gone.

## What is still yours [#what-is-still-yours]

1. **Host the privacy policy.** Run `bun run gen:privacy --owner "Your Company"`, read it, fill in
   every `[…]` placeholder (retention periods, transfer mechanism, what your server keeps), have a
   lawyer look at it, publish it, and put the URL in `readynative.config.ts` → `urls.privacy`.
   Re-run after you add or remove a module.
2. **Answer the store questionnaires** from the same facts: App Store Connect → App Privacy (the
   manifest's data types are the answer), Play Console → Data safety (the `doctor --store` draft).
   Say "No" to tracking unless `features.tracking` is on.
3. **Vendor deletion keys** (`backend=api-routes`). Set the server keys the delete route uses:
   `POSTHOG_PERSONAL_API_KEY` + `POSTHOG_PROJECT_ID` (+ `POSTHOG_API_HOST` for EU),
   `AMPLITUDE_API_KEY` + `AMPLITUDE_SECRET_KEY` (+ `AMPLITUDE_REGION=eu`), `REVENUECAT_SECRET_KEY`.
   Analytics vendors can only find the user when you call `analytics.identify(session.user.id)`.
   With Clerk, add a `user.deleted` webhook pointing at `/api/webhooks/clerk` and set
   `CLERK_WEBHOOK_SIGNING_SECRET`. Without API routes, vendor data is deleted on request - say so
   in the policy.
4. **Your own tables.** `deleteAccount()` removes the user at Supabase / Clerk / Better Auth; rows
   in *your* tables need `on delete cascade` (the Supabase migration shows how) or a hook. Apply
   both Supabase migrations (`supabase db push`) - deletion refuses to run without them and says
   which one is missing. "Export my data" covers the device; add an endpoint that returns the
   user's rows if you store anything server-side.
5. **Sentry dashboard.** Turn on Project Settings → Security & Privacy → "Prevent Storing of IP
   Addresses": the SDK sends no IP, but the connection itself reveals it.
6. **Sign the DPAs** of the processors you selected (they are linked from each module's docs
   page and from `doctor --store`).
7. **Write the consent copy in your voice.** `src/components/consent-sheet.tsx` is yours; keep
   "Only necessary" as prominent as "Accept all" - that is what regulators check - and raise
   `CONSENT_VERSION` when you change what you ask for.
8. **Age.** The template is not directed at children. If yours is, COPPA / Art. 8 need a parental
   flow the tree does not ship.

## How consent flows [#how-consent-flows]

```
consentStore (src/stores/consent.ts, key readynative:consent, loaded when @/lib/consent is imported)
   │  { analytics, crash, doNotSell, version, decidedAt, updatedAt, source }
   ▼
consent.get()  ─ resolves undecided by region, doNotSell turns analytics off ─►  { analytics, crash }
   │                                                                              ▲
   ├─► PostHog   no client until yes → new PostHog + optIn / optOut                │  Settings → Privacy switches
   ├─► Amplitude no init until yes → init / setOptOut                              │  "Do not sell or share"
   └─► Sentry    no init until yes → Sentry.init / Sentry.close, beforeSend gate   │  ConsentSheet (by region, per CONSENT_VERSION)
```

The SDK modules subscribe to the store at import time, before the first screen renders, so the
first `analytics.screen()` already sees the stored answer. With `consent/none`, undecided reads as
consented, "Do not sell or share" still turns analytics off, and the store and the Settings card
stay, so switching later changes nothing outside the module.

## Gotchas [#gotchas]

* Region comes from the device (locales and time zone), not IP. A user in Paris with a US region
  and a US time zone sees no sheet; the Settings switches are always there, and
  `privacy.askEverywhere: true` asks everyone.
* With AsyncStorage the consent store loads asynchronously; anything tracked before it has loaded
  is dropped rather than sent without a known answer.
* `app.config.ts` deep-merges arrays by replacement: a hand-written `ios.privacyManifests` in your
  base config is overwritten by the composed one. Add declarations to a module's `privacy` instead.
* The ATT purpose string stays in `Info.plist` even with `features.tracking: false`: the library
  is still linked, and App Store Connect flags a linked ATT framework without one. Nothing shows it.
* Keep `crash.capture(err, ctx)` contexts free of personal data; the scrubber masks emails and
  tokens it recognises, not everything personal.


# Scripts (/docs/scripts)



All CLIs are thin files in `scripts/`; the logic lives in `scripts/lib/*.ts`. They run under
plain `node` (Node 22.18+ strips TypeScript types natively), so `bun run`, `npm run`, `pnpm run`
and `yarn run` are interchangeable - see [Package managers](https://readynative.app/docs/package-managers). Every script
accepts `--root <dir>` (default: cwd), which is how the unit tests run them against fixture
trees.

Scripts fall into two groups. &#x2A;*Stays after `setup`** - what lives in the tree you ship:
`doctor`, `gen`, `gen:theme`, `gen:links`, `gen:privacy`, `gen:assets`, `gen:graph`,
`test:e2e`, plus `typecheck` / `lint` / `format` / `test`. **Module system** - leaves with
`modules/` unless you pass `--keep-modules`: `setup` itself (it stays as a one-line stub that
says it already ran) and `clean`.

## Setup and health [#setup-and-health]

### `bun run setup` [#bun-run-setup]

This is the one that assembles your tree.

```
bun run setup [--preset minimal|default|saas] [--<category> <option>]…
              [--yes] [--dry-run] [--no-install] [--keep-modules]
              [--with-examples] [--pm bun|pnpm|yarn|npm] [--root <dir>]
```

It copies the selected modules into the tree, generates the providers, env and
`.readynative.json`, patches `package.json` / `tsconfig.json`, strips the demo content (unless
`--with-examples`) and, unless `--keep-modules`, finalizes the tree: the kit moves to
`src/components/ui` and `scripts/` is trimmed to the ones marked "stays" above. Every step is in
[How setup works](https://readynative.app/docs/how-setup-works). On the Free tier none of this exists: the tree ships
already set up, without `scripts/`.

| Flag                 | Effect                                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `--preset <name>`    | Start from `minimal`, `default` or `saas`                                                                |
| `--<category> <opt>` | Override one category, e.g. `--data none`, `--ui tamagui`, `--auth supabase`                             |
| `--yes`              | No prompts; take preset/flags (or the previous `.readynative.json`)                                      |
| `--dry-run`          | Print the plan (selection, package manager, Expo Go verdict, dependency delta, files) and change nothing |
| `--no-install`       | Skip the install and `expo install` after applying                                                       |
| `--keep-modules`     | Do not delete `modules/` afterwards - required to run `setup` again with another selection               |
| `--with-examples`    | Keep the weather demo, the example screens and the UI catalog (default: strip them)                      |
| `--pm <name>`        | Force `bun`, `pnpm`, `yarn` or `npm` instead of the detected one                                         |
| `--help`             | Usage plus every category and option                                                                     |

It's idempotent: the same selection twice produces no diff. Unknown options, unmet `requires`
and `conflicts` are errors raised before anything is written. When it finishes, it prints the
post-setup steps of every selected service, one guide link each, and a
`https://readynative.app/docs/?stack=…` URL that opens these docs pre-filtered to your
selection.

### `bun run doctor` [#bun-run-doctor]

The post-setup checklist, with a non-zero exit on failures: `.readynative.json`, the env keys
your modules need, placeholders in `readynative.config.ts`, `eas whoami`, the native toolchains
when a module needs them, your package manager, and the bun and Node versions. `--store` turns
the "Before you ship" warnings into failures. It closes with the `?stack=` docs link for your
selection. Row by row: [Doctor](https://readynative.app/docs/doctor).

## Generators [#generators]

All of these stay in your tree after `setup`. `gen module` is the exception in practice: it
scaffolds into `modules/`, so it's useful only while that folder exists.

| Script                                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bun run gen:theme [--check]`              | `src/theme/tokens.ts` → `src/global.css` (nativewind5), `src/global.css` + `tailwind.config.js` (nativewind4), `tamagui.config.ts`; writes the active stack's file at the root (and, while `modules/` exists, every stack's copy under `modules/ui/<stack>/files/`). `--check` exits 1 on drift. See [Styling → Theme tokens and gen:theme](https://readynative.app/docs/styling#theme-tokens-and-gentheme)                                                                                                                                                                                                                                            |
| `bun run gen:links [--check]`              | `links` in `readynative.config.ts` → `public/.well-known/apple-app-site-association` + `assetlinks.json` for the prod/preview/dev ids                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `bun run gen:privacy [--owner "<entity>"]` | `readynative.config.ts` + `.readynative.json` (the selected modules' privacy declarations) → `docs/privacy-policy.md`, a privacy-policy draft matching what the build ships. `--stdout` prints instead. Re-run after `setup` changes a module; not legal advice.                                                                                                                                                                                                                                                                                                                                                                |
| `bun run gen:assets [--source <png>]`      | `assets/brand/icon.png` + `brand.primary` → icon, adaptive icon layers, splash icon, favicon (runs under Node)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `bun run gen:graph [--check]`              | The tree → `docs/graph.json` + `docs/ARCHITECTURE.md`: modules, providers, lib shims, routes, screens, features, stores, hooks, env keys, services and scripts, with the `imports` / `provides` / `reads` / `renders` / `configures` edges between them. `--check` exits 1 when the committed files are stale - run it before you commit, or add it to your own CI                                                                                                                                                                                                                                                              |
| `bun run gen screen <name>`                | `src/screens/<name>/<name>-screen.tsx` + the `src/app/<name>.tsx` route. `--tab [--icon <sf-symbol>] [--icon-fallback <material>] [--title "<Title>"]` routes it under `src/app/(tabs)/` and inserts a `<NativeTabs.Trigger>` entry (SF Symbol + Material icon, localised label) at the `{/* gen:tabs */}` marker in `src/app/(tabs)/_layout.tsx` (plus the title key in `src/locales/en.json`); `--modal` writes `src/app/<name>/{_layout,index}.tsx` with `presentation: "modal"` and registers it at the `{/* gen:stack */}` marker in `src/app/_layout.tsx`. Mutually exclusive; a missing marker prints the block to paste |
| `bun run gen module <category> <option>`   | `modules/<category>/<option>/{module.json,files/,docs.md}` scaffold - then fill `module.json` and `docs.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

Run `gen:graph` whenever you add a route, a lib shim, a provider or an env key - it's how
agents working in your repo find their way around. To extend it without touching the script, see
[Conventions → Extending the graph](https://readynative.app/docs/for-agents/conventions#extending-the-graph).

## Housekeeping [#housekeeping]

This one exists only while `modules/` does: before setup, or after `setup --keep-modules`.
Finalizing removes it, and the two example apps never had it. In a finalized tree, delete the
files it lists by hand.

| Script                                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bun run clean [--no-examples] [--yes]` | Remove demo content - what `setup` already does unless `--with-examples`: `src/app/_catalog.tsx` and its Settings row, placeholder assets, plus the weather demo (`src/app/(tabs)/cities/`, `src/screens/weather/`, `src/lib/weather/`, `src/stores/weather.ts`, `src/hooks/use-forecast.ts`, its tab), `src/app/examples/`, `src/screens/examples/`, `src/examples.ts`, the example hook/store (and their tests) and the Examples row in Settings. The home screen becomes a plain welcome and the Weather tab turns back into Home. `--no-examples` keeps the weather demo and the examples tab |

## Checks [#checks]

The four I run before every commit, plus the end-to-end runner.

| Script              | Command                                                                                                                                                                                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bun run typecheck` | `tsc --noEmit`                                                                                                                                                                                                                                                          |
| `bun run lint`      | `expo lint` (ESLint flat config)                                                                                                                                                                                                                                        |
| `bun run lint:fix`  | `expo lint --fix` (auto-fixable rules + Prettier formatting)                                                                                                                                                                                                            |
| `bun run format`    | `prettier --write .`                                                                                                                                                                                                                                                    |
| `bun run test`      | `jest` - present only with `testing=jest`; `testing=none` removes the script and every `__tests__`                                                                                                                                                                      |
| `bun run test:e2e`  | `node scripts/e2e.ts` - runs the Maestro flows in `.maestro/flows` against an installed dev build, with `APP_ID` / `APP_NAME` read from `readynative.config.ts`. `--variant dev\|preview\|prod` picks the ids (default `dev`), `--dry-run` prints the `maestro` command |

Your tree ships no git hooks and no CI: nothing runs on `git commit` or push. Run
`bun run typecheck`, `bun run lint`, `bun run test` and `bun run gen:graph --check` yourself, or
wire them into your own CI. For checks before each commit, add a hook runner
yourself - for example `bun add -d lefthook`, a `lefthook.yml` with a `pre-commit` job, then
`bunx lefthook install`.

## Expo [#expo]

`bun run start` / `ios` / `android` / `web` wrap `expo start`, `expo run:ios`, `expo run:android`
and `expo start --web`. `start` is `expo start --go` when every selected module runs in Expo Go
and `expo start --dev-client` otherwise (the tree always carries `expo-dev-client`, so a bare
`expo start` would wait for a dev build); `bun run start:dev` always targets the dev build.

There's no release script in your tree: a release is `npm version <patch|minor|major>` plus
`git push --follow-tags`, then an EAS production build - see
[Ship to TestFlight → Automate it](https://readynative.app/docs/ship-to-testflight#8-automate-it).

## Module-provided scripts [#module-provided-scripts]

A module may add scripts through `package.scripts` in its `module.json`; they disappear when the
module isn't selected (`test` from `testing/jest` and `i18n:extract` from `i18n/lingui` are two).
The one with its own file is `push:test`, from `push/expo-notifications` <Badge>Pro</Badge>: a
tree without that module has no `push:test` and no `scripts/push-test.ts`. It sends one
notification through the Expo push service to a device token (read it from
`push.usePushToken().token`, or from `/examples/push` when you kept the examples):

<Cmd>
  bun run push:test "ExponentPushToken[…]" "Title" "Body"
</Cmd>

It runs `scripts/push-test.ts` on plain `node`, so it works with any package manager
(`npm run push:test -- …` on npm), and it survives finalizing: any `scripts/` file a
`package.json` script runs is kept. The notification deep-links to `/examples/push`, which only
exists with `--with-examples`; without the examples, pass `--url /` (or any route you have).
Remote push needs a dev build on a physical device - see
[Add push notifications](https://readynative.app/docs/add-push).


# Quickstart (/docs/ship-in-5-minutes)



Hey - by the end of this page the app runs on a simulator or on your phone, `bun run doctor` is
green, and the tree contains only the modules you picked.

You start from a cloned Starter or Pro repo - [Get access](https://readynative.app/docs/after-you-buy) gets you there.
The Free tier (`ready-native-free`) ships with its stack already picked and no `setup` or
`doctor`: run `bun install`, then skip to [step 3](#3-run-it).

## Before you start [#before-you-start]

You need two tools; the rest is optional.

| Tool                   | Version  | Why                                                                                                                                                                     |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [bun](https://bun.sh)  | >= 1.2   | The recommended package manager and script runner. npm, pnpm and yarn work too - see [Package managers](https://readynative.app/docs/package-managers)                                         |
| Node                   | >= 22.18 | `scripts/*.ts` and `app.config.ts` run under plain `node`, which strips TypeScript types natively from 22.18; `setup` and `doctor` check it first. 24 LTS is what I run |
| Xcode / Android Studio | optional | Only to compile a dev build locally - see [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build) for the options that need one                                            |

`bun run doctor` checks the bun and Node versions, and checks the Xcode / Android SDK toolchains
only when a selected module has `expoGo: false`.

## 1. Install [#1-install]

<Cmd>
  bun install
</Cmd>

This installs the committed tree, which equals the `default` preset - a working app before you
choose anything. Run `bun run ios` (or `bun run start` for Expo Go) now if you want to see it:
it opens on the [weather demo](https://readynative.app/docs/examples#the-weather-demo), which shows the modules working
together - location, the offline cache, six languages with right-to-left Arabic, the native tab
bar - before `setup` swaps it for a clean home screen.

**You should see:** the install finish without errors and a `node_modules/` folder at the root.

## 2. Pick your stack [#2-pick-your-stack]

<Callout type="warn" title="setup is one-way">
  Unless you pass `--keep-modules`, `setup` deletes `modules/`, finalizes the tree and leaves a stub
  that prints "Already applied". Pick with [Pick your stack](https://readynative.app/docs/pick-your-stack) open, or run
  `bun run setup --keep-modules` to keep the tree switchable. [How setup
  works](https://readynative.app/docs/how-setup-works) has what finalizing does.
</Callout>

<Cmd>
  bun run setup
</Cmd>

In a terminal, `setup` asks one question per category. To skip the prompts, pass
`--preset <name>` and/or `--<category> <option>` plus `--yes`:

<Cmd>
  bun run setup --preset saas --ui tamagui --yes
</Cmd>

`bun run setup --help` lists every category and option, and `--dry-run` prints the plan without
changing anything. Every flag is in [Scripts](https://readynative.app/docs/scripts#bun-run-setup).

**You should see:** `src/providers.tsx`, `src/lib/env.ts`, `.env.example` and
`.readynative.json` written for your selection, the kit in `src/components/ui`, and a "Start:"
line saying whether your stack runs in Expo Go.

### The presets [#the-presets]

A preset is a complete answer for every category:

| Preset    | data        | state   | forms           | i18n    | onboarding | location      | widgets      | consent | testing | services                                                |
| --------- | ----------- | ------- | --------------- | ------- | ---------- | ------------- | ------------ | ------- | ------- | ------------------------------------------------------- |
| `minimal` | none        | none    | none            | none    | off        | none          | none         | none    | none    | none                                                    |
| `default` | react-query | zustand | react-hook-form | i18next | on         | expo-location | none         | none    | jest    | none                                                    |
| `saas`    | react-query | zustand | react-hook-form | i18next | on         | expo-location | expo-widgets | consent | jest    | supabase, revenuecat, posthog, sentry, push, api-routes |

All presets use `ui=nativewind4` (stable NativeWind 4.2 on Tailwind 3; NativeWind 5 is
`--ui nativewind5`, still a release candidate) and `storage=kv-store`. The committed tree equals
`setup --preset default`. `saas` is `default` plus every service category turned on
(supabase, revenuecat, posthog, sentry, expo-notifications, api-routes) <Badge>Pro</Badge> and
the iOS home-screen widget; I verify it before every release, and it needs a dev build because
RevenueCat, remote push and the widget are native. The Starter repo has no service modules, so it offers `minimal` and `default` only.

Override any preset per category:

<Cmd>
  bun run setup --preset minimal --data swr --yes
</Cmd>

## 3. Run it [#3-run-it]

<Cmd>
  bun run start
</Cmd>

Press `i` or `a` for a simulator, or scan the QR code with Expo Go. `start` is
`expo start --go` when every module you picked runs in Expo Go (the `default` preset does) and
`expo start --dev-client` otherwise.

If your stack needs a dev build, install it once, then start against it:

<Cmd>
  bun run ios
</Cmd>

<Cmd>
  bun run start:dev
</Cmd>

`bun run android` is the Android twin, and `bunx eas-cli build --profile development` builds it in
the cloud instead. [Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build) explains which stacks need
one and how to make it.

**You should see:** the app open on the Home tab - after the onboarding slides, if your stack has
them. Before `setup` (or with `--with-examples`), the Home tab is the
[weather demo](https://readynative.app/docs/examples#the-weather-demo): it asks for your location, shows the forecast
and has a Cities tab; after `setup` it is a plain welcome screen.

### Developer tools [#developer-tools]

While the app runs from the dev server - in Expo Go or a dev build - **Settings → Developer
tools** has shortcuts for checking what your stack does. Release builds never show it, and the
Free tier doesn't have it. Rows tied to a module appear only when you picked that module:

* **Page map** - Expo Router's `/_sitemap`: every route, tap one to open it.
* **Replay onboarding** - runs the onboarding slides again.
* **Show consent sheet** - in any region, through `consent.reprompt()`.
* **Preview paywall** - `payments.presentPaywall()`.
* **Open sign-in** - `auth.openSignIn()`. Sign out first, or the redirect sends you straight
  back.
* **Send test notification** - `push.sendTestNotification()`, delivered 3 seconds later.
* **Trigger a crash** - throws during render, to test the error screen and your crash reporter.

Below the rows, **Environment** lists which `EXPO_PUBLIC_*` keys the build reads as set or
missing (never their values), and **App info** shows the version, build, variant, runtime version
and update id.

## 4. Check yourself [#4-check-yourself]

<Cmd>
  bun run doctor
</Cmd>

`doctor` checks `.readynative.json`, every env key your modules need (with links to the
dashboard that issues it and to the guide here), the placeholders in `readynative.config.ts`,
your EAS login, your package manager and the toolchains. Placeholders such as `com.acme.app` or
the default icon are listed under "Before you ship" as warnings, so a fresh setup exits 0;
`doctor --store` turns them into failures. Row by row: [Doctor](https://readynative.app/docs/doctor).

**You should see:** a checklist with no red rows, and the "Before you ship" warnings you'll clear
in the next tutorial.

## Congrats 🎉 [#congrats-]

You have a running Expo app with exactly the modules you chose and nothing else. Next, give it
your name, colours and icon: [Make it yours](https://readynative.app/docs/make-it-yours).


# Ship to Google Play (/docs/ship-to-google-play)



Hey - by the end of this page your app is on the Play internal testing track, installable by
the testers you invite, and every build goes up with one `eas submit`.

## Before you start [#before-you-start]

* **Tier:** Starter or Pro. The Free tier ships without `eas.json` - run
  `bunx eas-cli build:configure` once to create one, and skip the `bun run doctor` checks.
* **Time:** 1-2 hours of your own work, plus 20-40 minutes per cloud build. A new Play developer
  account has to pass Google's identity verification first, which can take a few days.
* **Accounts:** a [Google Play developer account](https://play.google.com/console/signup) (a
  one-time fee), a free [Expo account](https://expo.dev/signup), and a Google Cloud project for
  the service account (step 5).
* **Previous tutorial:** [Ship to TestFlight](https://readynative.app/docs/ship-to-testflight). If you skipped it, do
  its steps 1-3 first: branding, `bunx eas-cli init` with the id pasted into `app.easProjectId`
  in `readynative.config.ts`, and your keys on EAS.

## 1. Set the package name for good [#1-set-the-package-name-for-good]

`app.android.package` in `readynative.config.ts` is your Play application id, for example
`com.yourcompany.trailmix`. The production profile uses it as is (dev and preview append
`.dev` / `.preview`). Once the first bundle is uploaded, Play locks the app to this id, so
change it now or never. `bun run doctor` warns while it's still `com.acme.app`.

<Cmd>
  bun run doctor
</Cmd>

**You should see:** no warning for `app.android.package`.

## 2. Check your keys are on EAS [#2-check-your-keys-are-on-eas]

`.env` is gitignored and never uploaded, so the build sees only the keys stored in its EAS
environment - `production` for this profile. If you set them up for iOS, they're already there:
Android uses the same environment. Check:

```bash
bunx eas-cli env:list --environment production
```

**You should see:** every key from your `.env`, with production values. Missing one? Add it with
`bunx eas-cli env:set --name <KEY> --value <value> --environment production --visibility
plaintext` (`sensitive` for keys without the `EXPO_PUBLIC_` prefix) - see
[Environment variables → On EAS](https://readynative.app/docs/environment-variables#on-eas).

## 3. Build the production bundle [#3-build-the-production-bundle]

```bash
bunx eas-cli build --profile production --platform android
```

The `production` profile in `eas.json` sets `APP_VARIANT=prod`, builds an Android App Bundle
(`.aab`) and auto-increments the version code. On the first Android build, EAS offers to
generate an upload keystore; say yes. EAS keeps it, and `bunx eas-cli credentials` shows it and
its SHA-256 fingerprint.

Using App Links? `links.androidCertFingerprints` needs the fingerprint of the key that signs what
users install. New apps always use Play App Signing, so Google signs the installed app with its
own app signing key: copy that key's SHA-256 from Play Console → **Protected with Play → Play
Store distribution → Play app signing** and add it next to the upload key's.

**You should see:** the build marked **Finished** on expo.dev, with an `.aab` artifact.

## 4. Create the app in Play Console [#4-create-the-app-in-play-console]

In [Play Console](https://play.google.com/console) → **Create app**, pick the app name, the
default language, App vs Game and Free vs Paid, and accept the declarations. Play doesn't ask
for the package name here - it takes it from the first bundle that reaches Play.

**You should see:** the app's dashboard in Play Console, with a "Set up your app" task list.

## 5. Create a service account for `eas submit` [#5-create-a-service-account-for-eas-submit]

EAS submits with a Google service account key. Expo's
[service account guide](https://expo.fyi/creating-google-service-account) has screenshots of
every click; the short version:

1. In [Google Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts), pick
   (or create) a project and create a service account. Copy its email, then **Manage keys →
   Create new key → JSON** and download the file.
2. Enable the [Google Play Android Developer
   API](https://console.cloud.google.com/apis/library/androidpublisher.googleapis.com) for that
   project.
3. In Play Console → **Users and permissions → Invite new users**, invite the service
   account's email. On **App permissions**, pick your app and tick: view app information,
   edit and delete draft apps, release to production (with Play App Signing), release to
   testing tracks, manage testing tracks and tester lists, and manage store presence. It
   doesn't need admin or financial permissions.

Then either upload the key to EAS (expo.dev → your project → **Credentials** → Android → your
application id → **Add a Google Service Account Key**, or `bunx eas-cli credentials --platform
android` → **Google Service Account**), or keep it next to the project and point `eas.json` at
it:

```json title="eas.json"
"submit": {
  "production": {
    "android": {
      "serviceAccountKeyPath": "./google-service-account.json",
      "track": "internal",
      "releaseStatus": "draft"
    }
  }
}
```

The key can publish your app, so add `google-service-account.json` to `.gitignore` before you
commit anything. With the key uploaded to EAS instead, leave `serviceAccountKeyPath` out.

`track` is `internal` (the default), `alpha` (closed testing), `beta` (open testing) or
`production`. `releaseStatus` is `completed` (the default: rolled out), `draft`, `inProgress`
(a staged rollout, with `rollout` between 0 and 1) or `halted`. While the app has never been
published - Play Console still calls it a draft app - Google's API only accepts `draft`
releases and rejects anything else with "Only releases with status draft may be created on
draft app". Keep `releaseStatus: "draft"` until the app has gone through review, then drop it,
or every later release also waits in draft for you to roll it out by hand.

**You should see:** the service account listed under **Users and permissions**, and the key
under your project's **Credentials** on expo.dev (or the JSON file next to `eas.json`, ignored by
git).

## 6. Upload the first bundle (optional) [#6-upload-the-first-bundle-optional]

`eas submit` can create the app's first release itself, so you can go straight to step 7. To
do the first upload in the browser instead
([Expo's manual guide](https://docs.expo.dev/submit/android-manual/) walks through it):

1. **Test and release → Testing → Internal testing → Create new release.**
2. Accept Play App Signing when asked (Google holds the app signing key; your EAS keystore
   becomes the upload key).
3. Upload the `.aab` from step 3 (download it from the build page on expo.dev), add release
   notes and roll it out.

Either way, under **Internal testing → Testers**, create an email list, add yourself, and open
the opt-in link on your phone. After that the build installs from the Play Store app on every
tester's device.

**You should see:** the opt-in page on your phone saying you're a tester.

## 7. Submit [#7-submit]

```bash
bunx eas-cli build --profile production --platform android --auto-submit
```

Or submit a build you already have:

```bash
bunx eas-cli submit --profile production --platform android
```

The release lands on the internal testing track. With `releaseStatus: "draft"`, open it in
Play Console (**Internal testing → Releases**) and roll it out; otherwise testers get it within
minutes. For later releases and wiring this into your own CI, see
[Ship to TestFlight → Automate it](https://readynative.app/docs/ship-to-testflight#8-automate-it).

**You should see:** the release under **Internal testing → Releases**, and after rollout, the
app installable from the Play Store app on your phone.

<Callout type="warn" title="New personal accounts need a closed test first">
  Personal developer accounts created after November 13, 2023 can't publish to production until a
  closed test has run with at least 12 testers opted in continuously for at least 14 days; then you
  apply for production access on the Play Console dashboard. Internal testing doesn't count. Start
  the closed test early (`track: "alpha"` submits to it). The rule is for personal accounts;
  organisation accounts don't have it. Google's [testing requirements
  page](https://support.google.com/googleplay/android-developer/answer/14151465) has the details.
</Callout>

## Check it [#check-it]

<Cmd>
  bun run doctor
</Cmd>

Every EAS row should be green. Before production, `bun run doctor --store` (Pro) checks what Play
review looks at.

## If it doesn't work [#if-it-doesnt-work]

* **"Only releases with status draft may be created on draft app"** - set
  `"releaseStatus": "draft"` in `submit.production.android` until the app has passed its first
  review.
* **`eas submit` says the service account has no permission** - the invite in Play Console is
  missing an app permission from step 5, or the Google Play Android Developer API isn't enabled
  for its Cloud project. Permission changes can take a few minutes to apply.
* **"Package name … already exists"** - another app on Play uses that id. Change
  `app.android.package` and build again.
* **The app works locally but shows "Configure …" from Play** - a key is missing from the EAS
  `production` environment. See
  [A key works locally but not in an EAS build](https://readynative.app/docs/troubleshooting#a-key-works-locally-but-not-in-an-eas-build).
* **The build fails on the keystore or credentials** - see
  [EAS build or credentials fail](https://readynative.app/docs/troubleshooting#eas-build-or-credentials-fail).

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

Your app is on Google Play internal testing, and the next build goes up with one command.
Before you move to production, fill in the store listing, content rating and Data safety form
in Play Console - [Pass app review](https://readynative.app/docs/pass-app-review) covers what reviewers check.

Next, ship a fix without a rebuild: [Your first update](https://readynative.app/docs/your-first-update).


# Ship to TestFlight (/docs/ship-to-testflight)



Hey - by the end of this page your iOS app is on TestFlight, built and uploaded by EAS, and the
people you invite can install it from the TestFlight app. This page is iOS only; the Android side
is [Ship to Google Play](https://readynative.app/docs/ship-to-google-play), and it reuses the EAS project you link here.

EAS builds everything native in the cloud ([EAS docs](https://docs.expo.dev/eas/)). Run the CLI
as `bunx eas-cli <command>` - substitute that for bare `eas` in Expo's docs.

## Before you start [#before-you-start]

* **Tier:** Starter or Pro. The Free tier ships without `eas.json` - run
  `bunx eas-cli build:configure` once to create one, and skip the `bun run doctor` checks.
* **Time:** about an hour of your own work, plus 20-40 minutes per cloud build, 5-15 minutes of
  Apple processing, and - if you're not enrolled yet - a day or two for Apple to approve your
  developer account.
* **Accounts:** the [Apple Developer Program](https://developer.apple.com/programs/) (paid,
  yearly) and a free [Expo account](https://expo.dev/signup).
* **Previous tutorial:** [Deploy your API routes](https://readynative.app/docs/deploy-api-routes) if your app has a
  backend - otherwise [Make it yours](https://readynative.app/docs/make-it-yours) is the one that matters here.

## 1. Finish your branding first [#1-finish-your-branding-first]

The name, bundle id, icon and splash are baked into the binary, and the bundle id can't change
once the app is on App Store Connect. Work through [Make it yours](https://readynative.app/docs/make-it-yours) before
the first store build, then:

<Cmd>
  bun run doctor
</Cmd>

**You should see:** no warnings for `app.name`, the `com.acme.app` ids, or empty `urls` - the
Settings screen links to `urls.privacy`, `urls.terms` and `urls.support`, and App Review opens
them. Using universal links? Set `links` and run `bun run gen:links` now too - the associated
domains are native as well ([Config → Universal links](https://readynative.app/docs/config#universal-links)).

## 2. Link the EAS project [#2-link-the-eas-project]

```bash
bunx eas-cli login
bunx eas-cli init
bunx eas-cli update:configure
```

`eas init` can't write into a dynamic `app.config.ts`, so it only **prints** the project id.
Paste it into `app.easProjectId` in `readynative.config.ts` (in CI you can set `EAS_PROJECT_ID`
instead; the env var wins). If you did this in [Add push notifications](https://readynative.app/docs/add-push), the id
is already there. `app.config.ts` derives `extra.eas.projectId` and `updates.url`
(`https://u.expo.dev/<projectId>`) from it. If the project belongs to an organisation rather
than your personal account, also set `app.owner` to its slug.

<Callout type="warn" title="Set the project id before the first production build">
  `app.config.ts` omits `updates` entirely while the project id is empty. A build made that way
  never receives an over-the-air update, and the only fix is shipping a new build.
</Callout>

<Cmd>
  bun run doctor
</Cmd>

**You should see:** green rows for `eas whoami`, "EAS project linked" and
"app.config.ts updates.url".

## 3. Put your keys on EAS [#3-put-your-keys-on-eas]

`.env` is gitignored and never uploaded, so an EAS build doesn't see a single key from it. Store
each one in the EAS environment the build uses - `production` for the store build, `preview`
for preview builds. `EXPO_PUBLIC_*` keys are public by design (they're compiled into the app),
so `plaintext` is fine; anything without the prefix is a server or build secret and gets
`sensitive`:

```bash
bunx eas-cli env:set --name EXPO_PUBLIC_SUPABASE_URL --value https://xxxx.supabase.co --environment production --visibility plaintext
bunx eas-cli env:set --name EXPO_PUBLIC_SUPABASE_ANON_KEY --value eyJ... --environment production --visibility plaintext
bunx eas-cli env:set --name SENTRY_AUTH_TOKEN --value sntrys_... --environment production --visibility sensitive
```

Those are examples - set every key your `.env` has, with production values where they differ
(the production Supabase project, `pk_live_…`, and so on). `APP_VARIANT` and
`EXPO_PUBLIC_APP_VARIANT` are already set per profile in `eas.json`. The details are in
[Environment variables → On EAS](https://readynative.app/docs/environment-variables#on-eas).

```bash
bunx eas-cli env:list --environment production
```

**You should see:** every key from your `.env`, with production values.

## 4. Try a preview build on your phone (optional) [#4-try-a-preview-build-on-your-phone-optional]

`eas.json` ships three profiles. Each sets `APP_VARIANT`, which is how `app.config.ts` picks
the name and bundle-id suffix ([Config](https://readynative.app/docs/config#appconfigts-and-variants)):

| Profile       | Installs as             | Distribution         | Channel       |
| ------------- | ----------------------- | -------------------- | ------------- |
| `development` | `.dev`, "(Dev)"         | internal (dev build) | `development` |
| `preview`     | `.preview`, "(Preview)" | internal (ad hoc)    | `preview`     |
| `production`  | your id, your name      | store                | `production`  |

A preview build is a release build you install from a link - the quickest way to see the real
thing before App Review. Internal iOS builds install only on registered devices, so register
your phone first (the command shows a page to scan with the phone):

```bash
bunx eas-cli device:create
bunx eas-cli build --profile preview --platform ios
```

The first iOS build asks you to sign in with your Apple Developer account and lets EAS create
the certificates and provisioning profile. A device you register later needs a rebuild.

**You should see:** a QR code and install link when the build finishes; the app installs as
"YourApp (Preview)" next to any other variant.

## 5. Build for the App Store [#5-build-for-the-app-store]

```bash
bunx eas-cli build --profile production --platform ios
```

`production` uses your bundle id as is and bumps the build number on every build
(`autoIncrement`, with `cli.appVersionSource: "remote"`, so EAS owns the number). The export
compliance question is pre-answered: `app.config.ts` sets `ITSAppUsesNonExemptEncryption: false`.

**You should see:** the build marked **Finished** on expo.dev, with an `.ipa` artifact.

## 6. Submit it [#6-submit-it]

```bash
bunx eas-cli submit --profile production --platform ios --latest
```

That uploads the latest production build to App Store Connect. On the first run, EAS asks for
your Apple ID and creates the app record if it doesn't exist. To skip the prompts next time,
fill in `appleId`, `ascAppId` and `appleTeamId` in `submit.production.ios` in `eas.json` (it's
empty on purpose). `store.appStoreId` in `readynative.config.ts` is something else - it feeds
the in-app review prompt and store links, not the submission.

**You should see:** after 5-15 minutes of Apple processing, the build under **App Store Connect
→ your app → TestFlight → iOS Builds**, and an email from Apple saying it's ready.

## 7. Invite testers [#7-invite-testers]

TestFlight has two kinds of groups:

* **Internal testing** - people on your App Store Connect team, up to 100. No review: they get
  the build as soon as it's processed. In **TestFlight*&#x2A;, click &#x2A;*+** next to **Internal
  Testing**, name the group, and add testers.
* **External testing** - anyone with an email or a public link, up to 10,000. The first build of
  each version goes through Beta App Review (usually about a day), and you need a beta
  description and a feedback email. App Store Connect lets you create an external group only
  once an internal one exists.

Once a group exists, submit straight to it next time:

```bash
bunx eas-cli submit --profile production --platform ios --latest --groups "QA Team" --what-to-test "New onboarding"
```

**You should see:** testers get an email invite, install the TestFlight app, and your app
appears there with an **Install** button.

## 8. Automate it [#8-automate-it]

A release is a version bump plus a `v*` tag. `npm version` does both - it needs a clean git tree,
bumps `version` in `package.json`, commits and tags `v<version>`:

```bash
npm version patch
git push --follow-tags
```

`app.config.ts` takes the app version from `package.json`, and the runtime version follows it
(`runtimeVersion.policy: "appVersion"`), so over-the-air updates published after a bump reach
only builds with the new version. Then build and submit in one command, which submits through
`eas.json` → `submit.production`:

```bash
bunx eas-cli build --profile production --platform ios --auto-submit
```

Your tree ships no CI workflows. To run this on every `v*` tag (or a preview build on every pull
request), add your own - see [Expo's GitHub Actions guide](https://docs.expo.dev/eas-update/github-actions/).

**You should see:** a production build on expo.dev that submits itself when it finishes.

## Check it [#check-it]

<Cmd>
  bun run doctor
</Cmd>

Every EAS row should be green. Before you go from TestFlight to the App Store, run
`bun run doctor --store` (Pro) and read [Pass app review](https://readynative.app/docs/pass-app-review).

## If it doesn't work [#if-it-doesnt-work]

* **The build fails on credentials or provisioning** - see
  [EAS build or credentials fail](https://readynative.app/docs/troubleshooting#eas-build-or-credentials-fail).
* **The app works locally but shows "Configure …" on TestFlight** (or no prices) - a key is
  missing from the EAS environment. See
  [A key works locally but not in an EAS build](https://readynative.app/docs/troubleshooting#a-key-works-locally-but-not-in-an-eas-build).
* **The preview build won't install on a phone** - that device wasn't registered when the build
  ran. `bunx eas-cli device:create`, then build again.
* **`eas submit` says the bundle id is taken** - someone else's app already uses it. Change
  `app.ios.bundleId` in `readynative.config.ts` and build again.
* **The build never shows up in TestFlight** - check the email Apple sends after processing; a
  missing usage description or an invalid icon is reported there, not in EAS.

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

Your app is on TestFlight, built in the cloud with production keys, and the next release is a
tag away. Next, the Android side: [Ship to Google Play](https://readynative.app/docs/ship-to-google-play).


# Styling (/docs/styling)



Hey - here's how I style screens in ReadyNative. By the end you'll know the one pattern every
screen uses, the tokens behind it, and how to write your own component in your stack. Dark
mode isn't a step: every colour token already has a light and a dark value.

Pick your UI option in the **Your stack** panel and the snippets below change with it.

## The pattern [#the-pattern]

Screens compose primitives from `@/components/ui` and pass **tokens**, not values:

```tsx title="src/screens/profile/profile-screen.tsx"
import { Box, Button, Card, Screen, Text } from "@/components/ui";

export function ProfileScreen() {
  return (
    <Screen scroll>
      <Box gap={4}>
        <Text variant="title">Profile</Text>
        <Card p={4}>
          <Text color="mutedForeground">Signed in as ada@example.com</Text>
        </Card>
        <Button onPress={signOut} variant="outline">
          Sign out
        </Button>
      </Box>
    </Screen>
  );
}
```

`gap={4}` is 16px, `p={4}` is 16px, `mutedForeground` is grey in light and lighter grey in
dark. That's the whole idea: you never type a number or a hex string in a screen.

The snippets here are for the finalized tree `bun run setup` leaves you, with the kit in
`src/components/ui`. Before setup, or after `setup --keep-modules`, it's in `src/ui` and the
import is `@/ui`; everything else on this page is identical.

<Callout type="warn" title="Never hardcode a colour or a spacing">
  `style={{ padding: 16, color: "#000" }}` looks right today and breaks the moment someone flips
  dark mode or you change `brand.primary`. Reach for a token prop first, `useTheme()` second,
  `style` last.
</Callout>

## The primitives [#the-primitives]

The kit exports the same primitives on every UI stack:

| Primitive                                | Purpose                                                                                                                                                                                                                                       |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ThemeProvider`, `useTheme()`            | Resolved mode + `colors` / `space` / `radius` for the current theme                                                                                                                                                                           |
| `Screen`                                 | Safe-area aware page (`scroll`, `padded`, `safe: "top" \| "bottom" \| "both" \| "none"`, `bg`); `scroll` keeps the focused input above the keyboard ([keyboard-controller](https://kirillzyusko.github.io/react-native-keyboard-controller/)) |
| `Box`                                    | Layout: `p/px/py/pt/pb/pl/pr`, `m/…`, `gap`, `bg`, `row`, `align`, `justify`, `flex`, `radius`, `border`                                                                                                                                      |
| `Text`                                   | `variant` (`body`, `title`, `heading`, `subtitle`, `caption`, `label`, `code`), `color`, `weight`, `align`                                                                                                                                    |
| `Button`                                 | `variant` (`primary`, `secondary`, `outline`, `ghost`, `destructive`, `link`), `size`, `loading`, icons                                                                                                                                       |
| `Pressable`                              | Tap target with optional haptic and pressed-state `scale`, animated on the UI thread by [Pressto](https://github.com/enzomanuelmangano/pressto)                                                                                               |
| `Card`                                   | Bordered surface, optionally pressable                                                                                                                                                                                                        |
| `Row`                                    | One settings-style line: `leading` icon/node, `title`/`subtitle`, `trailing` or chevron, `destructive`                                                                                                                                        |
| `List`                                   | Virtualised list of rows: `data`, `renderItem`, `separator`, `header`/`footer`, `empty`, `onRefresh`, `inset`                                                                                                                                 |
| `Input`, `Switch`                        | Form controls with `label` / `error`                                                                                                                                                                                                          |
| `Divider`, `Icon`, `Skeleton`, `Loading` | Chrome; `Icon` takes an SF Symbol `name` plus a Material `fallback`                                                                                                                                                                           |
| `EmptyState`, `ErrorState`               | Full-screen states with an optional action / `retry`                                                                                                                                                                                          |
| `Sheet`                                  | Native bottom sheet (`visible`, `onClose`, `detents: ["half", "full"]`): SwiftUI / Material 3 via `@expo/ui`, works in Expo Go                                                                                                                |
| `ToastHost`, `toast.show()`              | `toast.show({ title, kind, duration })` anywhere: a native iOS toast ([Burnt](https://github.com/nandorojo/burnt)) in dev and store builds, the themed card from `ToastHost` in Expo Go, on Android and web                                   |

Their prop types live in `src/components/ui/types.ts`. Theme mode (`useThemeMode`,
`setThemeMode`, `useResolvedMode`) is exported from the kit too, so screens never touch the store
directly - see [Dark mode](#dark-mode).

`Box`'s `align` and `justify` take the flexbox names **and** short aliases: `start`, `center`,
`end`, `between`, `around`, `evenly`, `stretch`, `baseline`. An alias that means nothing on its
axis (`between` on `align`, `baseline` on `justify`) falls back to that axis' default.

### Native by default [#native-by-default]

The primitives reach for the platform wherever it has something better than a drawn view:

* `toast.show()` is Burnt's system toast on iOS (with haptics, above native modals); the kit's
  own card renders in Expo Go, on Android and on web, so screens never branch.
* `Pressable` (and so `Button`, `Card` and pressable `Row`s) runs its press on a gesture-handler
  button with the scale animated on the UI thread - it tracks the finger while JS is busy and
  cancels cleanly when a list scrolls.
* `<Screen scroll>` is a `KeyboardAwareScrollView`: the focused field scrolls into view above the
  keyboard, and dragging the content dismisses it interactively, the way iOS apps do.
* `Sheet` is a real native sheet: detents, the grabber, Liquid Glass on iOS 26.

The root layout mounts `GestureHandlerRootView` and `KeyboardProvider` once for all of it. The
tab bar is `NativeTabs` - see [Your first feature](https://readynative.app/docs/first-feature).

```tsx
const [open, setOpen] = useState(false);

<Button onPress={() => setOpen(true)}>Details</Button>
<Sheet visible={open} onClose={() => setOpen(false)} detents={["half", "full"]}>
  <Text variant="heading">Details</Text>
</Sheet>
```

### List screens [#list-screens]

A list screen is a **non-scroll** `<Screen>` plus a `<List>`: `Screen` owns the safe-area
insets and `List` scrolls inside them, so neither fights the other over the bottom inset.
`List` is virtualised (RN `FlatList`) and sets `contentInsetAdjustmentBehavior="automatic"`
on iOS; nesting one inside `<Screen scroll>` gives up virtualisation and is only for a
handful of static rows. A `Row` draws no divider - `List` (or a `Divider` between Rows in a
`Card`) owns the separators.

```tsx title="src/screens/history/history-screen.tsx"
export function HistoryScreen() {
  const { data = [] } = useHistory();
  return (
    <Screen padded={false}>
      <List
        data={data}
        empty={<EmptyState title="Nothing yet" />}
        renderItem={(h) => (
          <Row title={h.title} subtitle={h.at} leading="clock" onPress={() => open(h.id)} />
        )}
      />
    </Screen>
  );
}
```

## Tokens [#tokens]

Every prop on a primitive takes a token from `src/theme/tokens.ts`:

| You want    | Prop / token                                                                                                                                                                |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spacing     | `p`, `px`, `m`, `gap`, … take `0 1 2 3 4 5 6 8 10 12 16` (= 0 4 8 12 16 20 24 32 40 48 64 px)                                                                               |
| Colour      | `bg`, `color` take `background`, `foreground`, `card`, `primary`, `muted`, `mutedForeground`, `destructive`, `destructiveForeground`, `success`, `border`, `brandAccent`, … |
| Radius      | `radius` takes `sm`, `md`, `lg`, `xl`, `full` - derived from `brand.radius`                                                                                                 |
| Text style  | `variant` takes `title`, `heading`, `subtitle`, `body`, `caption`, `label`, `code`; `weight` takes `normal` … `extrabold`                                                   |
| Button look | `variant` takes `primary`, `secondary`, `outline`, `ghost`, `destructive`, `link`; `size` takes `sm`, `md`, `lg`, `icon`                                                    |

The colour names are shadcn's, so anything you copy from that ecosystem maps one to one.
`style` is the only escape hatch: every primitive accepts it, and there's deliberately no
`className` on the kit ([why](https://readynative.app/docs/faq#why-is-there-no-classname-on-the-kits-primitives)).

## Theme tokens and `gen:theme` [#theme-tokens-and-gentheme]

`src/theme/tokens.ts` is the design-token source of truth. It's plain data importable from
Node (unit tests, `scripts/gen-theme.ts`) and reads `brand` from `readynative.config.ts`:

| Token set                 | Values                                                                                                                                                                                                                                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `colors.light` / `.dark`  | `background`, `foreground`, `card`, `cardForeground`, `popover`, `popoverForeground`, `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `muted`, `mutedForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, `success`, `border`, `input`, `ring`, `brandAccent` |
| `space`                   | `0:0, 1:4, 2:8, 3:12, 4:16, 5:20, 6:24, 8:32, 10:40, 12:48, 16:64` (px, Tailwind steps)                                                                                                                                                                                                                         |
| `radius`                  | `sm`, `md`, `lg`, `xl`, `full` - derived from `brand.radius` (= `lg`; `sm = lg - 4`, `md = lg - 2`, `xl = lg + 4`)                                                                                                                                                                                              |
| `fontSize` / `lineHeight` | `xs` 12/16, `sm` 14/20, `base` 16/24, `lg` 18/28, `xl` 20/28, `2xl` 24/32, `3xl` 30/36, `4xl` 36/40                                                                                                                                                                                                             |
| `fontWeight`              | `normal` 400, `medium` 500, `semibold` 600, `bold` 700, `extrabold` 800                                                                                                                                                                                                                                         |
| `fontFamily`              | `brand.font` - a name only; load the file yourself ([Config → Brand font](https://readynative.app/docs/config#brand-font))                                                                                                                                                                                                             |

To change the brand, edit `brand` in `readynative.config.ts` and regenerate
([Make it yours](https://readynative.app/docs/make-it-yours) walks through it, dark mode included):

```ts title="readynative.config.ts"
brand: { primary: "#7c3aed", accent: "#f59e0b", radius: 16, font: "Inter" },
```

<Cmd>
  bun run gen:theme
</Cmd>

`primary` overrides the light-mode `primary` colour, `accent` is exposed as `brandAccent` in both
modes, and `radius` is `lg`. For the full palette, edit `src/theme/tokens.ts` directly: it's
plain data with a `light` and a `dark` object. `cssColorVariables(mode)` returns the `--color-*`
map NativeWind consumes.

`bun run gen:theme` renders the tokens into your stack's theme file. StyleSheet and Unistyles
read `tokens.ts` directly, so they have nothing to generate:

| Stack         | Generated file(s)                                     |
| ------------- | ----------------------------------------------------- |
| `nativewind5` | `src/global.css`                                      |
| `nativewind4` | `src/global.css` + `tailwind.config.js` (HSL triples) |
| `tamagui`     | `tamagui.config.ts` (static values, no `@/` imports)  |

It writes the active stack's file (from `.readynative.json`) at the root and, while `modules/`
exists, every stack's copy under `modules/ui/<stack>/files/`. `bun run gen:theme --check` exits
1 on drift, so you can gate CI on it. Edit tokens, never the generated files.

## Dark mode [#dark-mode]

There's nothing to do. Every colour token resolves per mode, so a screen written with tokens
is already correct in both. The user's preference lives in Settings → Appearance, and you can
read or set it from anywhere:

```tsx
import { setThemeMode, useResolvedMode } from "@/components/ui";

const mode = useResolvedMode(); // "light" | "dark" - what's on screen right now
setThemeMode("dark"); // "system" | "light" | "dark" - persisted
```

For the rare inline style that needs a real colour, `useTheme()` gives you the resolved
palette:

```tsx
import { useTheme } from "@/components/ui";

const { colors, space, radius } = useTheme();
<MapView style={{ borderRadius: radius.lg, borderColor: colors.border }} />;
```

## Your own components [#your-own-components]

When a screen needs something the kit doesn't have, put it in `src/components/` and style it
the way your stack does.

<If cat="ui" is="nativewind5|nativewind4">
  Tailwind classes, with the token names as colours:

  ```tsx title="src/components/badge.tsx"
  import { Text, View } from "react-native";

  export function Badge({ children }: { children: string }) {
    return (
      <View className="self-start rounded-full bg-primary px-3 py-1">
        <Text className="text-xs font-medium text-primary-foreground">{children}</Text>
      </View>
    );
  }
  ```

  `bg-primary`, `text-muted-foreground`, `border-border` and friends come from `src/global.css`,
  which `bun run gen:theme` writes from the tokens - don't edit the CSS. Class names can't be
  built at runtime (`p-${n}` never compiles), so read `useTheme()` for anything dynamic.
</If>

<If cat="ui" is="stylesheet">
  `useStyles` is `StyleSheet.create` bound to the current theme. Declare the factory at module
  scope so it runs once per mode:

  ```tsx title="src/components/badge.tsx"
  import { Text, View } from "react-native";

  import { useStyles } from "@/components/ui";
  import type { Theme } from "@/components/ui";

  const badgeStyles = (t: Theme) => ({
    root: {
      alignSelf: "flex-start" as const,
      backgroundColor: t.colors.primary,
      borderRadius: t.radius.full,
      paddingHorizontal: t.space[3],
      paddingVertical: t.space[1],
    },
    label: { color: t.colors.primaryForeground, fontSize: 12, fontWeight: "500" as const },
  });

  export function Badge({ children }: { children: string }) {
    const styles = useStyles(badgeStyles);
    return (
      <View style={styles.root}>
        <Text style={styles.label}>{children}</Text>
      </View>
    );
  }
  ```

  Styles that never read the theme can use `StyleSheet.create` directly.
</If>

<If cat="ui" is="tamagui">
  `styled` with `$token` keys - every colour, space and radius token is registered in
  `tamagui.config.ts`:

  ```tsx title="src/components/badge.tsx"
  import { styled, Text, YStack } from "tamagui";

  export const Badge = styled(YStack, {
    alignSelf: "flex-start",
    backgroundColor: "$primary",
    borderRadius: "$full",
    paddingHorizontal: "$3",
    paddingVertical: "$1",
    variants: { tone: { danger: { backgroundColor: "$destructive" } } } as const,
  });

  export const BadgeText = styled(Text, { color: "$primaryForeground", fontSize: 12 });
  ```

  The `as const` on `variants` is what types the `tone` prop. `bun run gen:theme` rewrites
  `tamagui.config.ts` from the tokens, so edit tokens, not the config.
</If>

<If cat="ui" is="unistyles">
  Styles are theme functions; Unistyles re-themes them without a React re-render:

  ```tsx title="src/components/badge.tsx"
  import { Text, View } from "react-native";
  import { StyleSheet } from "react-native-unistyles";

  type BadgeProps = { tone?: "default" | "danger"; children: string };

  export function Badge({ tone = "default", children }: BadgeProps) {
    styles.useVariants({ tone });
    return (
      <View style={styles.root}>
        <Text style={styles.label}>{children}</Text>
      </View>
    );
  }

  const styles = StyleSheet.create((theme) => ({
    root: {
      alignSelf: "flex-start",
      borderRadius: theme.radius.full,
      paddingHorizontal: theme.space[3],
      paddingVertical: theme.space[1],
      variants: {
        tone: {
          default: { backgroundColor: theme.colors.primary },
          danger: { backgroundColor: theme.colors.destructive },
        },
      },
    },
    label: { color: theme.colors.primaryForeground, fontSize: theme.fontSize.xs },
  }));
  ```

  Breakpoints (`xs` `sm` `md` `lg` `xl`) are registered in `src/unistyles.ts`; use them as a
  `breakpoint` variant for tablet layouts.
</If>

## See every primitive [#see-every-primitive]

The app ships a catalog route with every primitive, every variant and both modes side by side:
Settings → **UI catalog**, or open `/_catalog`. It's demo content, so `setup` removes it
unless you pass `--with-examples`.

## Common mistakes [#common-mistakes]

Each of these looks fine at first and costs you later. Here's what to write instead:

| Mistake                                                   | Do this instead                                                             |
| --------------------------------------------------------- | --------------------------------------------------------------------------- |
| `style={{ padding: 16 }}`                                 | `p={4}`                                                                     |
| `style={{ color: "#737373" }}`                            | `color="mutedForeground"`                                                   |
| Importing `View` / `Text` from `react-native` in a screen | `Box` / `Text` from `@/components/ui` - they carry the tokens and dark mode |
| `data.map()` inside `<Screen scroll>`                     | `<Screen>` + `<List>` - virtualised, and the safe-area insets don't fight   |
| Editing `src/global.css` / `tamagui.config.ts`            | Edit `src/theme/tokens.ts`, run `bun run gen:theme`                         |
| Checking `useColorScheme()` yourself                      | `useResolvedMode()` - it respects the stored preference                     |

## Where to go next [#where-to-go-next]

* [UI contract](https://readynative.app/docs/ui-contract) - the adapter contract behind the kit, for `--keep-modules` trees
* [Your UI option](https://readynative.app/docs/features/ui) - setup, usage and gotchas for the stack you picked
* [Add your first feature](https://readynative.app/docs/first-feature) - a whole tab built from these primitives


# Troubleshooting (/docs/troubleshooting)



Something broke? Here are the failures I see most, each with its fix. Start with
`bun run doctor` (Starter and Pro): it checks the versions, your keys, the config placeholders
and the EAS link in one go, and names what to fix.

## `setup` prints "Already applied" [#setup-prints-already-applied]

**Symptom:** `bun run setup --ui tamagui` (or any other flag) prints
`Already applied - setup is one-way and removed itself` and nothing changes.

Your tree is finalized: the first `setup` run deleted `modules/` and left this one-line stub in
its place, so there's nothing to apply a new selection from. `.readynative.json` records what
you picked. To switch an option, start from a fresh clone of your tier repo -
[Can I change a module after setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup) has the steps.
Next time, `bun run setup --keep-modules` keeps the tree switchable.

## Wrong bun or Node version [#wrong-bun-or-node-version]

**Symptom:** `bun install` or a script fails early, `doctor` shows a red `bun >=` or `node >=`
line, or a script dies with an error about the `.ts` file extension.

`scripts/*.ts` run under plain `node`, which strips TypeScript natively only from 22.18 on, and
`app.config.ts` imports `readynative.config.ts` the same way. Update both:

```bash
bun upgrade
node --version
```

Install Node 22.18 or newer (24 LTS is what I run) with your version manager of choice, then
run `bun run doctor` again. With npm, pnpm or yarn instead of bun, see
[Package managers](https://readynative.app/docs/package-managers).

## A native module is missing in Expo Go [#a-native-module-is-missing-in-expo-go]

**Symptom:** the app crashes on launch in Expo Go with something like
`TurboModuleRegistry.getEnforcing(...): 'X' could not be found` or "Cannot find native
module", usually right after picking MMKV, Unistyles, RevenueCat, Adapty or push.

Expo Go contains only its own bundled native modules. Those options ship native code, so they
need a dev build: your own build of the app that works like Expo Go afterwards.

```bash
bunx expo run:ios
bunx expo run:android
```

Or build it in the cloud and install from the link:

```bash
bunx eas-cli build --profile development --platform ios
```

Then start Metro with `bun run start:dev` and open the `(Dev)` app, not Expo Go. Rebuild whenever
you add a library with native code or change native config (`readynative.config.ts` ids,
icons, plugins). `bun run setup` prints whether your selection runs in Expo Go;
[Expo Go or a dev build](https://readynative.app/docs/expo-go-vs-dev-build) lists every module that doesn't.

## A key is missing or ignored [#a-key-is-missing-or-ignored]

**Symptom:** a screen says "Configure Supabase" (or the matching service), `doctor` reports
`missing in .env`, or you added a key and nothing changed.

* Put keys in `.env` at the repo root. `.env.example` lists every key your selection needs,
  each with a link to the dashboard that issues it.

* `EXPO_PUBLIC_*` values are inlined into the bundle when Metro builds it, so restart with a
  clear cache after editing `.env`:

  ```bash
  bun run start -- -c
  ```

* Read them as `process.env.EXPO_PUBLIC_X` written out in full. Expo inlines only static
  references; `process.env[name]` stays `undefined`.

* Works locally but not in an EAS build? See the next section.

* Server keys (`STRIPE_SECRET_KEY` and friends) never get the `EXPO_PUBLIC_` prefix. The app
  can't read them; only `src/app/api/**` and `src/server/**` can.

## A key works locally but not in an EAS build [#a-key-works-locally-but-not-in-an-eas-build]

**Symptom:** the app works with `bun run start`, but a build from EAS (TestFlight, Play internal
testing, a preview build) shows "Configure Supabase" or its service's equivalent, or an update
from `eas update` loses a key.

`.env` is gitignored, so EAS never uploads it. Set each key in the EAS environment the build
uses, with `plaintext` for `EXPO_PUBLIC_*` keys and `sensitive` for server keys:

```bash
bunx eas-cli env:set --environment production --name EXPO_PUBLIC_SUPABASE_URL --value https://xyz.supabase.co --visibility plaintext
```

Then rebuild, or republish the update with `--environment`.
[Environment variables → On EAS](https://readynative.app/docs/environment-variables#on-eas) says which profile reads
which environment.

## Supabase sign-in never comes back in Expo Go [#supabase-sign-in-never-comes-back-in-expo-go]

**Symptom:** Google sign-in or a password-reset link opens the browser, you finish there, and the
app never receives the session - you land on a Supabase error page or the site URL instead.

Supabase redirects only to URLs on its allow list. In a dev build the app's links start with
your scheme (`readynative://`), but in Expo Go they start with `exp://<lan-ip>:8081/--/`. In
Supabase, open Authentication → URL Configuration → Redirect URLs and add `exp://**` to your
development project (never production), next to your scheme's entries. The
[Supabase page](https://readynative.app/docs/features/auth/supabase#setup) lists them all.

## RevenueCat shows no offerings or no prices [#revenuecat-shows-no-offerings-or-no-prices]

**Symptom:** the paywall is empty, `offerings.current` is `null`, or packages load without a
price.

RevenueCat can show only what the store hands it. Work down this list:

* **Paid Apps Agreement:** App Store Connect → Business must show the Paid Apps Agreement as
  active, with banking and tax forms complete. Until then StoreKit returns no products at all.
* **Product status:** each subscription in App Store Connect needs its metadata filled in so it
  reaches "Ready to Submit" (a price, a localized name, a review screenshot). On Play, the
  product must be active.
* **Offering:** in RevenueCat, the products are attached to a package in an offering marked
  **current**.
* **Tester:** purchases and prices come through on a real device signed into a sandbox Apple ID
  (or a Play license tester). A RevenueCat Test Store key (`test_…`) skips all of this in
  development.

The [RevenueCat page](https://readynative.app/docs/features/payments/revenuecat#setup) walks the dashboards.

## The push token is null [#the-push-token-is-null]

**Symptom:** `push.usePushToken()` stays at `token: null` with status `unsupported`, and the dev
console warns "remote push needs a physical device".

Simulators and emulators never get a remote push token, and Expo Go doesn't receive remote push
since SDK 53. Install a dev build on a physical phone (`bunx eas-cli build --profile development`,
or `bunx expo run:ios --device`) and open that. If the status is `unsupported` on a real phone,
`app.easProjectId` in `readynative.config.ts` is empty - run `bunx eas-cli init` and paste the id.
Local notifications work everywhere except the web. See
[Add push notifications](https://readynative.app/docs/add-push) and the [Push](https://readynative.app/docs/features/push/expo-notifications)
module page.

## EAS build or credentials fail [#eas-build-or-credentials-fail]

**Symptom:** `eas build` stops before the build starts, or the build fails at signing.

* **Not logged in / wrong account:** `bunx eas-cli whoami`, then `bunx eas-cli login`.
* **No project id:** `eas init` can't write into `app.config.ts`; it only prints the id. Paste
  it into `app.easProjectId` in `readynative.config.ts` (or set `EAS_PROJECT_ID` in CI).
* **The project belongs to an organisation:** set `app.owner` to the organisation slug, or CI
  builds with an org `EXPO_TOKEN` are rejected.
* **iOS signing:** run the first iOS build interactively so EAS can sign in to your Apple
  Developer account and create the certificate and provisioning profile. A paid Apple
  Developer membership is required; a free Apple ID can't build for the store. "Bundle
  identifier is not available" means someone already registered that id - change
  `app.ios.bundleId`.
* **Inspect or reset stored credentials:** `bunx eas-cli credentials` shows the iOS
  certificates, the Android keystore and the service account keys for each platform. Don't
  delete an Android keystore that has already uploaded to Play - you'd lose the upload key.
* **`--non-interactive` in CI fails on credentials:** run one build interactively first so
  the credentials exist on EAS.

## `git apply` says "does not exist in index" [#git-apply-says-does-not-exist-in-index]

**Symptom:** piping a diff between two release tags into `git apply` stops with
`error: <path>: does not exist in index` and applies nothing.

`git apply` is all-or-nothing, and the upstream diff touches paths your finalized tree doesn't
have: module files live under `modules/<category>/<option>/files/` upstream but at the root in
your tree, the UI kit moved to `src/components/ui`, and `setup` removed the demo screens and its
own scripts. Map the paths, and let git merge around your edits:

* For a module, add `--relative=modules/<category>/<option>/files` to `git diff`.
* For the UI kit, add `--relative=modules/ui/<your-stack>/files/src/ui/<your-stack>` to
  `git diff` and `--directory=src/components/ui` to `git apply`.
* Always pass `--3way` to `git apply`, and add `--exclude=<path>` for every path the error still
  names.

[Update from upstream](https://readynative.app/docs/update-from-upstream#finalized-tree) has the full commands.

## Metro serves stale code [#metro-serves-stale-code]

**Symptom:** a change doesn't show up, an import you deleted still errors, or the app shows
"Unable to resolve module" for a file that exists - typically after `bun run setup`, switching
branches or editing `babel.config.js` / `metro.config.js`.

```bash
bun run start -- -c
```

If that doesn't do it, reinstall and clear Expo's local cache:

```bash
rm -rf node_modules .expo
bun install
bun run start -- -c
```

For a dev build that still misbehaves after native changes, rebuild it: `bunx expo run:ios`
(or `run:android`) regenerates the native projects from config.

## Still stuck? [#still-stuck]

`bunx expo-doctor` checks dependency versions against your Expo SDK, and
`bunx expo install --fix` aligns them. If that's clean too, send the command, the full error
and your `bun run doctor` output through the [support form](https://readynative.app/support/).


# UI contract (/docs/ui-contract)



This is the reference for `src/ui/contract.ts`, the one contract every UI stack implements. If you
want to *style a screen* rather than read the spec, start with [Styling](https://readynative.app/docs/styling).

It applies to the tree before `bun run setup`, or after `bun run setup --keep-modules`. A finalized
tree has no contract: the kit sits in `src/components/ui`, its prop types in
`src/components/ui/types.ts`, and there's no `UiKit` left to satisfy.

Screens, components and routes import UI &#x2A;*only from `@/ui`**, so switching from NativeWind to
Tamagui (or to plain `StyleSheet`) changes the adapter under `src/ui/<stack>/`, not the app.

```ts title="src/ui/index.ts (generated by setup)"
export * from "./contract";
export * from "./theme-mode";

export * from "./nativewind4"; // the active stack
```

## Primitives [#primitives]

`UiKit` is the runtime export list every `src/ui/<stack>/index.ts` must provide: the primitives
in [Styling → The primitives](https://readynative.app/docs/styling#the-primitives), which also covers list screens.
Theme mode (`useThemeMode`, `setThemeMode`, `useResolvedMode`) is re-exported from
`src/ui/theme-mode.ts`, and `Box`'s short `align` / `justify` aliases are `FlexAlias` in the
contract - adapters map them.

## Rules [#rules]

* **Props are token-typed.** Spacing props take `SpaceToken` (`0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16`),
  colours take `ColorToken`, radii take `RadiusToken` - never raw numbers or hex strings.
* **`style` is the only escape hatch.** Every primitive accepts `style?: StyleProp<ViewStyle>`
  (or `TextStyle`). There is deliberately &#x2A;*no `className`** on the contract; Tailwind classes
  are an implementation detail of the NativeWind adapters and do not exist for Tamagui,
  Unistyles or `StyleSheet`.
* **The contract file imports nothing from a stack.** Only React and react-native *types*.
* **ESLint enforces it** (`eslint.config.js`, for `src/screens/**` and `src/app/**`):
  `View`, `Text`, `StyleSheet`, `Pressable`, `TextInput`, `Switch` from `react-native` are
  restricted; so are `@/components/ui/*`, `@/ui/<adapter>` (only `@/ui` and `@/ui/contract`
  are public), `@/theme/*`, `nativewind`, `react-native-css`, `react-native-reanimated`, and
  importing `readynative.config` directly (use `@/lib/readynative`).

## Tokens [#tokens]

The token sets and `bun run gen:theme` work the same in every tree - see
[Styling → Theme tokens and gen:theme](https://readynative.app/docs/styling#theme-tokens-and-gentheme).

## Adding a UI stack adapter [#adding-a-ui-stack-adapter]

This needs `modules/`, so it works in a tree set up with `--keep-modules`.

1. `bun run gen module ui <stack>` scaffolds `modules/ui/<stack>/{module.json,files/,docs.md}`.

2. Implement every primitive under `files/src/ui/<stack>/` and finish `index.ts` with:

   ```ts title="src/ui/<stack>/index.ts"
   const kit = {
     ThemeProvider,
     useTheme,
     Screen,
     Box,
     Text,
     Button,
     Pressable,
     Card,
     Row,
     List,
     Input,
     Switch,
     Divider,
     Icon,
     Skeleton,
     Loading,
     EmptyState,
     ErrorState,
     ToastHost,
     toast,
   } satisfies UiKit;

   export default kit;
   ```

   `satisfies UiKit` is what makes a missing or mistyped primitive a compile error.

3. Declare the theme provider in `module.json` so `setup` nests it at order 50:
   `{ "import": "ThemeProvider", "as": "UiThemeProvider", "from": "@/ui", "order": 50 }`,
   and list every file under `files[]`.

4. If the stack needs a generated theme file, add a renderer in `scripts/lib/gen-theme*.ts`
   and put its id in `module.json.gen`.

5. Apply it with `bun run setup --ui <stack> --yes --keep-modules`, then run
   `bun run typecheck`, `bun run lint`, `bun run test` and `bunx expo export -p ios -p android`.
   Run `setup` a second time: it should change nothing. The `stylesheet` adapter is the
   reference implementation of the contract - copy its structure.


# Update from upstream (/docs/update-from-upstream)



ReadyNative is a template you clone, not a dependency you install, so updates arrive through
git. Every release is one commit on `main` of your tier repo (`ready-native-free`,
`ready-native-starter` or `ready-native-pro`), tagged `v<x.y.z>-sdk57`. In the Starter and Pro
repos, each of those commits is the tree before `setup`: `modules/` present, the `default` preset
applied at the root.

How you take an update depends on what `setup` left you with. Check once:

```bash
ls modules
```

* **`modules/` is there** - you ran `setup --keep-modules`. Merge the release, then re-apply your
  selection: [With modules kept](#with-modules-kept).
* **`modules/` is gone** - the tree is finalized, the default. A merge would fight you on every
  moved file, so you port the diff instead: [Finalized tree](#finalized-tree).
* **Free tier** - the release is already finalized the same way yours is, so a plain merge works:
  [Free tier](#free-tier).

## Hear about releases [#hear-about-releases]

On GitHub, open your tier repo, click **Watch** → **Custom**, tick **Releases** and apply. You
get a notification for every release and nothing else. Each release has GitHub Release notes on
what changed - read them before you pull.

## Set up the remote once [#set-up-the-remote-once]

```bash
git remote add upstream https://github.com/ReadyNative/ready-native-pro.git
git fetch upstream --tags
```

Swap `pro` for your tier. If you cloned the tier repo and never repointed `origin`, it already
is the upstream - use `origin` below instead. The fetch uses your GitHub access to the tier repo,
which comes with [lifetime updates](#lifetime-updates).

List the releases to find the one you're on and the one you want:

```bash
git tag --list 'v*' --sort=-v:refname
```

## With modules kept [#with-modules-kept]

The release and your tree have the same layout, so git can merge it:

```bash
git fetch upstream --tags
git merge v1.2.0-sdk57
```

Expect conflicts in three kinds of file:

* **Files owned by a module you didn't pick** show up as modify/delete conflicts: upstream changed
  them, you don't have them. Keep them deleted with `git rm <file>`.
* **Generated files** (`src/providers.tsx`, `src/lib/env.ts`, `src/ui/index.ts`, `.env.example`,
  `.readynative.json`, `package.json`) - take either side; `setup` rewrites them next.
* **Files you edited** (`readynative.config.ts`, your screens) - resolve them the usual way.

Then re-apply your selection against the merged module sources and re-check:

<Cmd>
  bun run setup --yes --keep-modules
</Cmd>

<Cmd>
  bun run typecheck
</Cmd>

<Cmd>
  bun run lint
</Cmd>

<Cmd>
  bun run doctor
</Cmd>

`setup` is idempotent: with the same selection it rewrites only files whose content changed, so
the diff you commit is the update and nothing else.

## Finalized tree [#finalized-tree]

Finalizing moved files (`modules/<category>/<option>/files/src/lib/auth.ts` became
`src/lib/auth.ts`, `src/ui/<stack>/*` became `src/components/ui/*`) and deleted `modules/`, so
`git merge` would report every upstream change to a module as a modify/delete conflict. Take the
diff between the two release tags instead and apply it at the paths your tree uses.
`git apply --3way` falls back to a three-way merge when your copy of a file has drifted from the
release, so edits you made survive.

Start by looking at what changed:

```bash
git diff --stat v1.1.0-sdk57 v1.2.0-sdk57
```

**A module you use.** `--relative` strips the module folder from the paths, so the patch lands at
the root where `setup` copied the files:

```bash
git diff v1.1.0-sdk57 v1.2.0-sdk57 --relative=modules/auth/supabase/files | git apply --3way
```

Repeat it for each module you picked (`selection` in `.readynative.json` lists them). Changes to
a module's `module.json` - a new dependency, env key or config plugin - don't apply themselves:
read that part of the diff and add them to `package.json`, `.env.example` / `src/lib/env.ts` or
`modules.app` in `.readynative.json` by hand.

**Your UI kit.** Upstream keeps it at `modules/ui/<your-stack>/files/src/ui/<your-stack>`; strip
that and point `--directory` at where the kit lives now. For `nativewind4` (swap both occurrences
for your stack):

```bash
git diff v1.1.0-sdk57 v1.2.0-sdk57 --relative=modules/ui/nativewind4/files/src/ui/nativewind4 | git apply --3way --directory=src/components/ui
```

Upstream imports read `@/ui`; yours read `@/components/ui`. A hunk that touches an import line
may conflict - resolve it to `@/components/ui`.

**Core files** - everything outside `modules/`:

```bash
git diff v1.1.0-sdk57 v1.2.0-sdk57 -- . ':(exclude)modules' | git apply --3way --exclude='src/ui/*'
```

`git apply` is all-or-nothing: when the patch touches a file `setup` removed from your tree
(the demo screens, `scripts/setup.ts`, generated files), it prints
`<path>: does not exist in index` and changes nothing. Add an `--exclude=<path>` for each path
it names and run it again. Then re-install and re-check:

<Cmd>
  bun install
</Cmd>

<Cmd>
  bun run typecheck
</Cmd>

<Cmd>
  bun run lint
</Cmd>

<Callout type="info" title="Switching a module is not an update">
  Restoring `modules/` from upstream doesn't bring the module system back to a finalized tree. To
  move to another option, see [Can I change a module after
  setup?](https://readynative.app/docs/faq#can-i-change-a-module-after-setup).
</Callout>

## Free tier [#free-tier]

`ready-native-free` is finalized before it's published, with the same stack every time, so its
releases and your clone share one layout:

```bash
git remote add upstream https://github.com/ReadyNative/ready-native-free.git
git fetch upstream --tags
git merge v1.2.0-sdk57
```

Conflicts only show up in files you both changed.

## Lifetime updates [#lifetime-updates]

A paid license includes lifetime updates (section 5 of `LICENSE`), and your GitHub access to
the repo stays, so clone, fetch and the diffs above keep working for every future release.
[License → Lifetime updates](https://readynative.app/docs/license#lifetime-updates) says what "lifetime" means.

## SDK upgrades [#sdk-upgrades]

The tag suffix is the Expo SDK: `-sdk57` releases target SDK 57. When upstream moves to a new
SDK, take the last `-sdk57` release first, then the first `-sdk58` one as its own step. Run
`bunx expo install --fix` and `bunx expo-doctor` after it, then typecheck and lint as usual.


# Your first update (/docs/your-first-update)



Hey - by the end of this page a change you make lands on an installed build without a new build
and without App Review, you've watched the "Update ready" banner pick it up, and you know how to
take it back.

EAS Update ships your JavaScript bundle and assets. Anything native - a library with native
code, a config plugin, a change in `app.config.ts` or the `app` ids in `readynative.config.ts`, a
new icon - still needs a build.

## Before you start [#before-you-start]

* **Tier:** Starter or Pro. The Free tier ships without `expo-updates`.
* **Time:** about 15 minutes.
* **Runs in:** a **preview or production build** installed on a phone, made after the EAS
  project was linked. Expo Go and dev builds don't take channel updates - they run whatever your
  dev server serves - and the updates banner is off in dev.
* **Accounts:** the Expo account your EAS project lives in.
* **Previous tutorial:** [Ship to Google Play](https://readynative.app/docs/ship-to-google-play) or
  [Ship to TestFlight](https://readynative.app/docs/ship-to-testflight) - you need a build from one of them.

## 1. Check updates are wired [#1-check-updates-are-wired]

`app.config.ts` turns `app.easProjectId` into `updates.url` (`https://u.expo.dev/<projectId>`)
and leaves `updates` out entirely while the id is empty.

<Cmd>
  bun run doctor
</Cmd>

**You should see:** green rows for "EAS project linked" and "app.config.ts updates.url". If the
build on your phone was made before the id was set, it can never receive an update - make a new
build first.

## 2. Make a change [#2-make-a-change]

Pick something you'll recognise on sight. After `setup`, the Home tab is a plain welcome - change
its "Edit src/screens/home/home-screen.tsx to start building." line (or any visible string, if
you've replaced Home):

```tsx title="src/screens/home/home-screen.tsx"
<Text>Shipped over the air</Text>
```

**You should see:** the new line in your dev build or Expo Go. The installed preview or
production build still shows the old one.

## 3. Publish it [#3-publish-it]

Every `eas.json` profile has a channel - `development`, `preview`, `production` - and each update
goes to one channel. Send it to the channel of the build on your phone:

```bash
bunx eas-cli update --channel preview --environment preview --message "Home heading"
```

For a production build, `--channel production --environment production`.

`--environment` is required. It picks the EAS environment whose `EXPO_PUBLIC_*` values are
inlined into the update - the same set the matching build used - and ignores your local `.env`,
so the keys must be on EAS ([Environment variables → On EAS](https://readynative.app/docs/environment-variables#on-eas)).
`secret` variables aren't available to an update. Using Sentry? Upload the update's source maps
right after with `bunx sentry-expo-upload-sourcemaps dist`, or its stack traces stay minified.

**You should see:** the CLI export the bundle, upload it, and print the update group id and a
link to it on expo.dev.

## 4. Confirm it's published [#4-confirm-its-published]

```bash
bunx eas-cli update:list --branch preview
```

A channel points at the branch of the same name, which the first `eas update --channel`
created.

**You should see:** your update at the top, with your message and the runtime version (your app
version, since `runtimeVersion.policy` is `appVersion`).

## 5. Watch it arrive [#5-watch-it-arrive]

Open the app on your phone. It checks for an update on launch and downloads it in the
background without blocking startup, so the launch you're looking at still runs the old
bundle.

* **With the updates banner** (`features.updatesBanner: true` in `readynative.config.ts`, the
  default): an **Update ready** banner appears once the download finishes, with **Later** and
  **Restart**. Tap **Restart**. The banner also re-checks when the app comes back to the
  foreground, at most every five minutes.
* **Without it**: close the app completely and open it again. The downloaded update applies on
  that cold start.

**You should see:** the new line on the installed build, with no store involved.

<Callout type="info" title="Updates follow the app version">
  An update only reaches builds with the same runtime version - here, the `version` in
  `package.json`. Bump it whenever native code changes (`npm version minor`, then a new build), and
  older builds keep getting only the updates published for their version.
</Callout>

## 6. Roll it back [#6-roll-it-back]

If an update misbehaves, take it back:

```bash
bunx eas-cli update:rollback
```

The CLI asks which kind: back to the **previously published update** (it's republished), or
back to the **update embedded in the build** (the JavaScript the binary shipped with). Apps pick
up the rollback the same way they picked up the update - on the next launch, or through the
banner.

**You should see:** after a restart, the old line back on the installed build.

## Check it [#check-it]

```bash
bunx eas-cli update:list --branch preview
```

The rollback shows up as the newest entry. The next update you publish reaches every build on
that channel as usual.

## If it doesn't work [#if-it-doesnt-work]

* **The update never arrives** - the channel doesn't match the build (a preview build listens to
  `preview`), or the runtime versions differ (the build's app version isn't the one in
  `package.json` now). Compare them with `bunx eas-cli update:list`.
* **No banner** - you're in Expo Go or a dev build, `features.updatesBanner` is off, or the build
  was made without `app.easProjectId`. Close and reopen the app twice instead.
* **The update arrived but a service says "Configure …"** - the key isn't in the EAS environment
  you passed to `--environment`. See
  [A key works locally but not in an EAS build](https://readynative.app/docs/troubleshooting#a-key-works-locally-but-not-in-an-eas-build).
* **The app crashes after an update** - the change probably needs native code the build doesn't
  have. Roll back (step 6), then ship the change as a new build with a bumped version.

More in [Troubleshooting](https://readynative.app/docs/troubleshooting).

## Congrats 🎉 [#congrats-]

You shipped a fix in minutes instead of days, watched it land, and know how to undo it. That
closes the loop: build once, update often, rebuild only when something native changes.

That's the last tutorial. Before your first store release, read
[Pass app review](https://readynative.app/docs/pass-app-review).