# Installation

> Pick the stack you are building on and follow the guide for it — plain Expo, or Expo with a Convex, Supabase or Firebase backend, with or without authentication.

**BNA UI** — a React Native / Expo component library.
These components render through `react-native`, not the DOM: there are no HTML
elements, no Tailwind classes and no Radix primitives. Source is copied into your
project and imported through `@/components/ui/*`, `@/components/charts/*`,
`@/hooks/*` and `@/theme/*`. Colours come from the `useColor` hook rather than
hardcoded hex; sizing tokens (`HEIGHT`, `FONT_SIZE`, `BORDER_RADIUS`, `CORNERS`)
come from `@/theme/globals`.

- Docs: https://ui.ahmedbna.com/docs/installation
- Markdown: https://ui.ahmedbna.com/docs/installation.md

---

> The CLI scaffolds a complete app — routing, theming, a tab layout and thirteen
> components already wired up. Pick a starting point below and copy one command.

Choose the setup that matches what you are building.

[Expo](/docs/installation/expo) — The components, theming and a tab layout. No backend.

[Manual installation](/docs/installation/manual) — Add BNA UI to an Expo app you already created.

[Expo + Convex](/docs/installation/convex) — A real-time backend with a schema and a live query. No sign-in.

[Expo + Convex + Auth](/docs/installation/convex-auth) — Google, Apple, password and email OTP sign-in, pre-wired.

[Expo + Supabase](/docs/installation/supabase) — Postgres with row level security, realtime and storage. No sign-in.

[Expo + Supabase + Auth](/docs/installation/supabase-auth) — Password, magic links, OTP, Google, Apple and GitHub, pre-wired.

[Expo + Firebase](/docs/installation/firebase) — Firestore, Cloud Storage and security rules with tests. No sign-in.

[Expo + Firebase + Auth](/docs/installation/firebase-auth) — Password, Google and Apple sign-in, with owner-scoped rules.

## Which one should I pick?

| You want to…                                            | Start with                                                                                                                                                  |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Build a UI and ship it, no server                       | [Expo](/docs/installation/expo)                                                                                                                             |
| Store data and sync it live across devices, no accounts | [Convex](/docs/installation/convex), [Supabase](/docs/installation/supabase) or [Firebase](/docs/installation/firebase)                                     |
| Have users sign in on day one                           | [Convex + Auth](/docs/installation/convex-auth), [Supabase + Auth](/docs/installation/supabase-auth) or [Firebase + Auth](/docs/installation/firebase-auth) |

### Convex, Supabase or Firebase?

All three are real-time backends and all three starters give you the same app.
They differ in where your logic lives and how authorization works.

|                   | Convex                                    | Supabase                                       | Firebase                                      |
| ----------------- | ----------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
| Data model        | Documents, schema in TypeScript           | Postgres, schema in SQL migrations             | Documents, no schema                          |
| Queries           | TypeScript functions on the server        | Direct from the client, plus edge functions    | Direct from the client                        |
| Authorization     | Checked inside each function              | Row level security, enforced by Postgres       | Security rules, evaluated against the _query_ |
| Realtime          | Every query is a live subscription        | Opt in per table                               | Every listener is live                        |
| Search            | Built-in full-text index                  | `ilike`, or a `tsvector` column                | Whole-word tokens, or an extension            |
| Offline cache     | In-memory                                 | In-memory                                      | In-memory (no IndexedDB on RN)                |
| Local dev         | Cloud dev deployment                      | Cloud, or the whole stack in Docker            | Emulator suite (needs a JDK)                  |
| Reach for it when | You want end-to-end TypeScript and no SQL | You want Postgres, SQL and a relational schema | You are already in the Google ecosystem       |

> Firestore evaluates a read rule against the **query**, not the documents it
> would return — it refuses any query it cannot prove is scoped to rows you are
> allowed to read. Postgres row level security does the opposite and silently
> narrows the result. Code that moves between the Supabase and Firebase starters
> has to account for that.

The Firebase auth starter also has no email OTP and no GitHub provider, and its
Google and Apple buttons need a development build.
[The details are here.](/docs/installation/firebase-auth)

Nothing in the component library depends on either, so you can start on the plain
Expo path and add a backend later.

## Existing project

Already have an Expo app? Don't run `init` over it. The manual guide adds the
theme system and hooks to a project you already have, then leaves you to pull in
components one at a time with `bna-ui add`.

[Manual installation](/docs/installation/manual) — Add BNA UI to an Expo app you already created.

[Browse components](/docs/components) — Every component, with a preview and its source.