> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipnative.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start building in 2 minutes

## Prerequisites

Before you start, install these tools:

<AccordionGroup>
  <Accordion title="Node.js 20 (required)" icon="node-js">
    **Recommended: Use Volta** (automatically manages Node versions)

    ```bash theme={null}
    curl https://get.volta.sh | bash   # macOS/Linux
    volta install node@20.19.0 yarn@4.9.1
    ```

    **Alternative: Use nvm**

    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
    nvm install 20
    nvm use 20
    ```

    **Verify installation:**

    ```bash theme={null}
    node -v   # Should show v20.x.x
    ```
  </Accordion>

  <Accordion title="Yarn (required)" icon="yarn">
    If you used Volta above, Yarn is already installed. Otherwise:

    ```bash theme={null}
    corepack enable          # Enables Yarn (included with Node)
    ```

    **Verify installation:**

    ```bash theme={null}
    yarn -v   # Should show 4.x.x
    ```
  </Accordion>

  <Accordion title="Git (required)" icon="git-alt">
    **macOS:** Install Xcode Command Line Tools

    ```bash theme={null}
    xcode-select --install
    ```

    **Windows:** Download from [git-scm.com](https://git-scm.com/download/win)

    **Linux:**

    ```bash theme={null}
    sudo apt install git   # Ubuntu/Debian
    ```
  </Accordion>

  <Accordion title="Xcode (iOS development)" icon="apple">
    1. Install [Xcode from the Mac App Store](https://apps.apple.com/app/xcode/id497799835)
    2. Open Xcode once and accept the license agreement
    3. Install iOS Simulator (Xcode → Settings → Platforms → iOS)

    <Note>Xcode is \~12GB and only available on macOS.</Note>
  </Accordion>

  <Accordion title="Android Studio (Android development)" icon="android">
    1. Download [Android Studio](https://developer.android.com/studio)
    2. During setup, install the Android SDK
    3. Create an emulator: Tools → Device Manager → Create Device

    <Note>Works on macOS, Windows, and Linux.</Note>
  </Accordion>
</AccordionGroup>

***

## Setup

```bash theme={null}
git clone https://github.com/shipnativeapp/shipnative.git
cd shipnative
yarn install
yarn setup   # Optional: configure app name and services
cd apps/app
yarn ios     # or: yarn android, yarn web
```

<Note>
  **Mock mode is enabled by default.** You can skip `yarn setup` entirely and start building immediately. All services (auth, database, payments, analytics) work with simulated data. Configure real services when you're ready for production.
</Note>

***

## Development Workflow

<Warning>
  **Important:** `yarn ios` / `yarn android` compiles native code, which takes several minutes. You only need to run this once (or when native dependencies change).
</Warning>

**For daily development, use this workflow:**

```bash theme={null}
# First time only (builds native app)
cd apps/app
yarn ios     # Takes 3-5 minutes

# Daily development (fast refresh)
yarn start   # or: yarn dev
```

The dev server provides instant hot reload for JavaScript/TypeScript changes. You only need to rebuild with `yarn ios` when:

* Adding/removing native dependencies
* Changing `app.json` configuration
* Modifying native code (Swift/Kotlin)
* The app gets uninstalled from the simulator

***

## Backend Choice

During `yarn setup`, you'll choose between:

| Backend      | Best For                                                     |
| ------------ | ------------------------------------------------------------ |
| **Supabase** | SQL apps, PostgreSQL experience, RLS-based security          |
| **Convex**   | TypeScript-first apps, reactive queries, function-level auth |

Both work identically in mock mode. Choose based on your preference.

<Tip>
  After you choose, setup automatically removes the other backend's code and packages. You'll have a clean codebase with only your chosen backend.
</Tip>

***

## What's Included

The app ships with working screens:

* **Welcome/Login/Signup** - Full auth flow (Supabase or Convex)
* **Home** - Main app screen
* **Profile** - User settings and account deletion
* **Paywall** - Subscription UI with mock purchases
* **Dev Menu** - `Cmd+D` (iOS) / `Cmd+M` (Android) for debugging

***

## AI-Assisted Development

Open your project in [Cursor](https://cursor.sh/) or Claude Code. To build features:

```
Read AGENTS.md.
I want to build [describe your feature].
```

The AI reads the `vibe/` context files and follows project patterns automatically.

***

## Key Directories

| Location                   | Contents                                                |
| -------------------------- | ------------------------------------------------------- |
| `apps/app/app/screens/`    | Screen components                                       |
| `apps/app/app/components/` | Reusable UI components                                  |
| `apps/app/app/stores/`     | Zustand stores (auth, subscriptions)                    |
| `apps/app/app/services/`   | Service clients (Supabase, Convex, RevenueCat, PostHog) |
| `apps/app/app/hooks/`      | Auth hooks (backend-specific after setup)               |
| `apps/app/app/theme/`      | Unistyles theme tokens                                  |
| `convex/`                  | Convex backend functions (only if using Convex)         |
| `vibe/`                    | AI context files                                        |

***

## Dev Menu

Access via `Cmd+D` (iOS) / `Cmd+M` (Android):

* Toggle free/pro subscription
* Switch light/dark mode
* View component showcase
* Check which services are mocked

***

## Before Production

1. Configure backend credentials (Supabase or Convex)
2. Generate Android release keystore
3. Update bundle identifiers in `app.json`

See [Full Setup Guide](/getting-started/installation).

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Mock Services" icon="flask" href="/development/mock-services">
    How mock services work
  </Card>

  <Card title="Backend & Database" icon="database" href="/core-features/backend">
    Choose and configure your backend
  </Card>

  <Card title="Full Setup" icon="gear" href="/getting-started/installation">
    Configure all services
  </Card>

  <Card title="Deploy" icon="rocket" href="/deployment/index">
    Ship to app stores
  </Card>
</CardGroup>