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

# Full Setup

> Configure backend services for production

For quick start, see [Quickstart](/getting-started/quickstart). This guide covers full production configuration.

<Info>
  **You can skip all service configuration initially.** The app runs in mock mode by default with simulated auth, database, and payments. Configure real services when you're ready for production.
</Info>

## Requirements

**For development:** Nothing extra. Mock services work out of the box.

**For production:**

* Backend (Supabase or Convex) - **required**
* Android release keystore - **required**
* Bundle identifiers in `app.json` - **required**
* RevenueCat, PostHog, Sentry - optional but recommended

## Prerequisites

Install these tools before proceeding:

| Tool                         | How to Install                                                                                                        | Verify              |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------- |
| **Node.js 20**               | [Volta](https://volta.sh) (recommended): `curl https://get.volta.sh \| bash && volta install node@20.19.0 yarn@4.9.1` | `node -v` → v20.x.x |
| **Yarn**                     | Included with Volta, or: `corepack enable`                                                                            | `yarn -v` → 4.x.x   |
| **Git**                      | macOS: `xcode-select --install` / Windows: [git-scm.com](https://git-scm.com)                                         | `git --version`     |
| **Xcode** (iOS)              | [Mac App Store](https://apps.apple.com/app/xcode/id497799835) - open once to accept license                           | N/A                 |
| **Android Studio** (Android) | [developer.android.com/studio](https://developer.android.com/studio) - install SDK during setup                       | N/A                 |

<Tip>
  **New to JavaScript/Node?** We recommend [Volta](https://volta.sh) - it automatically manages Node versions so you don't have to think about it. Just run the install command above and you're set.
</Tip>

<Warning>
  **Node version matters.** The project requires Node 20 specifically. Node 22+ causes build failures with some native dependencies. Run `node -v` to check your version before proceeding.
</Warning>

## Step 1: Clone and Install

```bash theme={null}
git clone https://github.com/shipnativeapp/shipnative.git
cd shipnative
yarn install
```

## Step 2: Run Setup Wizard

```bash theme={null}
yarn setup
```

The wizard configures:

* App name and bundle identifier
* Backend provider (Supabase or Convex)
* Backend credentials
* OAuth providers (Google, Apple)
* RevenueCat API keys
* PostHog analytics
* Sentry error tracking

**Options:**

```bash theme={null}
yarn setup --help           # Show all options
yarn setup --dry-run        # Preview changes
yarn setup --non-interactive # For CI/CD
```

### Backend Selection

The wizard prompts you to choose a backend:

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

**After you choose**, the setup wizard automatically:

* Removes the unused backend's code (folders, hooks, services)
* Updates `.env.example` to only show your chosen backend's variables
* Removes the unused backend's packages from `package.json`
* Runs `yarn install` to update the lockfile

This gives you a clean codebase with only the backend you selected.

See [Backend & Database](/core-features/backend) for detailed comparison.

### Service Configuration

Each service is optional. Skip any to use mock mode.

<Tabs>
  <Tab title="Supabase">
    | Service       | Where to Find Credentials                                                                 |
    | ------------- | ----------------------------------------------------------------------------------------- |
    | Supabase      | Dashboard → Settings → API → Publishable key                                              |
    | Google OAuth  | [Google Cloud Console](https://console.cloud.google.com/) → APIs & Services → Credentials |
    | Apple Sign In | [Apple Developer Portal](https://developer.apple.com/) → Certificates, IDs & Profiles     |
    | RevenueCat    | Dashboard → Your App → API Keys                                                           |
    | PostHog       | Dashboard → Project Settings → API Keys                                                   |
    | Sentry        | Dashboard → Settings → Client Keys (DSN)                                                  |
  </Tab>

  <Tab title="Convex">
    | Service       | Where to Find Credentials                           |
    | ------------- | --------------------------------------------------- |
    | Convex        | Run `npx convex dev` from project root              |
    | Google OAuth  | Convex Dashboard → Settings → Environment Variables |
    | Apple Sign In | Convex Dashboard → Settings → Environment Variables |
    | RevenueCat    | Dashboard → Your App → API Keys                     |
    | PostHog       | Dashboard → Project Settings → API Keys             |
    | Sentry        | Dashboard → Settings → Client Keys (DSN)            |

    **Convex Quick Setup:**

    ```bash theme={null}
    # From project root
    npx convex dev          # Creates project, saves URL to .env.local

    # Required: Set up auth keys (JWT_PRIVATE_KEY + JWKS)
    npx @convex-dev/auth

    npx convex run seed:run # Add demo data
    ```

    <Warning>
      **Both `JWT_PRIVATE_KEY` and `JWKS` are required.** Without them, sign-in will fail. See [Convex Setup](/core-features/convex#2-set-up-authentication-keys) for manual setup if needed.
    </Warning>

    OAuth secrets go in Convex Dashboard → Settings → Environment Variables:

    * `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`
    * `AUTH_APPLE_ID`, `AUTH_APPLE_SECRET`
    * `RESEND_API_KEY` (for magic link emails)
  </Tab>
</Tabs>

See individual feature guides for detailed setup:

* [Authentication](/core-features/authentication)
* [Social Login](/core-features/social-login)
* [Payments](/core-features/payments)
* [Analytics](/core-features/analytics)
* [Error Tracking](/core-features/error-tracking)

### Security Note

`EXPO_PUBLIC_*` variables are bundled into your app. Only use:

* Supabase publishable key (protected by RLS)
* Convex deployment URL (protected by function-level auth)
* RevenueCat public keys
* PostHog project API key

Never expose `service_role` keys or secrets in your app.

## Step 3: Run Your App

```bash theme={null}
cd apps/app
yarn ios     # or: yarn android, yarn web
```

***

## Manual Configuration

If you prefer manual configuration:

```bash theme={null}
cp apps/app/.env.example apps/app/.env
```

Edit `apps/app/.env`:

<Tabs>
  <Tab title="Supabase">
    ```bash theme={null}
    EXPO_PUBLIC_BACKEND_PROVIDER=supabase
    EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
    EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-key
    EXPO_PUBLIC_POSTHOG_API_KEY=your-key
    EXPO_PUBLIC_POSTHOG_HOST=https://app.posthog.com
    EXPO_PUBLIC_REVENUECAT_IOS_KEY=your-key
    EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=your-key
    EXPO_PUBLIC_SENTRY_DSN=your-dsn
    ```
  </Tab>

  <Tab title="Convex">
    ```bash theme={null}
    EXPO_PUBLIC_BACKEND_PROVIDER=convex
    EXPO_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
    EXPO_PUBLIC_POSTHOG_API_KEY=your-key
    EXPO_PUBLIC_POSTHOG_HOST=https://app.posthog.com
    EXPO_PUBLIC_REVENUECAT_IOS_KEY=your-key
    EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=your-key
    EXPO_PUBLIC_SENTRY_DSN=your-dsn
    ```
  </Tab>
</Tabs>

Edit `apps/app/app.json`:

```json theme={null}
{
  "expo": {
    "name": "Your App Name",
    "slug": "your-app-slug",
    "ios": { "bundleIdentifier": "com.yourcompany.yourapp" },
    "android": { "package": "com.yourcompany.yourapp" },
    "scheme": "yourapp"
  }
}
```

## Mock Mode

Without credentials, services run in mock mode:

| Service         | Mock Behavior                                  |
| --------------- | ---------------------------------------------- |
| Supabase/Convex | In-memory auth/database, login always succeeds |
| RevenueCat      | Purchases succeed instantly, dev menu toggle   |
| PostHog         | Events logged to console                       |
| Sentry          | Errors logged to console                       |

See [Mock Services](/development/mock-services) for details.

***

## Troubleshooting

### Setup wizard fails?

* Ensure Node.js 20+ and Yarn are installed
* Delete partial `.env`: `rm apps/app/.env`
* Try again: `yarn setup`

### "Package not found in project" error?

If you see an error like:

```
Internal Error: Package for myapp@workspace:apps/app not found in the project
```

This happens when `yarn.lock` is out of sync after renaming your app. Fix it:

```bash theme={null}
yarn install   # Regenerates yarn.lock with new package name
```

### iOS build fails with Swift errors?

If you see errors like `missing argument for parameter 'logHandlers'` in expo-widgets:

```bash theme={null}
# Ensure patches are applied
yarn install
cd apps/app
yarn prebuild:clean
yarn ios
```

The `postinstall` script applies patches automatically. If issues persist, manually verify patches exist in `/patches/` directory.

### App won't start?

```bash theme={null}
cd apps/app
yarn start --clear
```

### Builds are slow?

`yarn ios` / `yarn android` compile native code (3-5 minutes). For daily development:

```bash theme={null}
# Build once
yarn ios

# Then use the dev server (instant refresh)
yarn start
```

Only rebuild when native dependencies change.

### API keys not working?

* Keys must be in `apps/app/.env`
* All keys need `EXPO_PUBLIC_` prefix
* Restart Metro after adding keys

See [Troubleshooting](/troubleshooting) for more.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Backend & Database" icon="database" href="/core-features/backend">
    Configure your chosen backend
  </Card>

  <Card title="Authentication" icon="lock" href="/core-features/authentication">
    Set up user auth
  </Card>

  <Card title="Payments" icon="credit-card" href="/core-features/payments">
    Set up RevenueCat
  </Card>

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