> ## 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:

> [accordion] Node.js 20 (required)
>
> **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] Yarn (required)
>
> 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] Git (required)
>
> **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] Xcode (iOS development)
>
> 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.

> [accordion] Android Studio (Android development)
>
> 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.

***

## 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.

***

## 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).

**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.

***

## 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](https://docs.shipnative.app/getting-started/installation.md).

***

## Next Steps

> [card] [Mock Services](https://docs.shipnative.app/development/mock-services.md)
>
> How mock services work

> [card] [Backend & Database](https://docs.shipnative.app/core-features/backend.md)
>
> Choose and configure your backend

> [card] [Full Setup](https://docs.shipnative.app/getting-started/installation.md)
>
> Configure all services

> [card] [Deploy](https://docs.shipnative.app/deployment/index.md)
>
> Ship to app stores


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.