> ## 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](https://docs.shipnative.app/getting-started/quickstart.md). This guide covers full production configuration.

> [!NOTE]
>
> **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.

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

> [!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.

## 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](https://docs.shipnative.app/core-features/backend.md) for detailed comparison.

### Service Configuration

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

> [tab] 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] 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](https://docs.shipnative.app/core-features/convex.md#2-set-up-authentication-keys) for manual setup if needed.
>
> 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)

See individual feature guides for detailed setup:

* [Authentication](https://docs.shipnative.app/core-features/authentication.md)
* [Social Login](https://docs.shipnative.app/core-features/social-login.md)
* [Payments](https://docs.shipnative.app/core-features/payments.md)
* [Analytics](https://docs.shipnative.app/core-features/analytics.md)
* [Error Tracking](https://docs.shipnative.app/core-features/error-tracking.md)

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

> [tab] 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] 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
> ```

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](https://docs.shipnative.app/development/mock-services.md) 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](https://docs.shipnative.app/troubleshooting.md) for more.

***

## Next Steps

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

> [card] [Authentication](https://docs.shipnative.app/core-features/authentication.md)
>
> Set up user auth

> [card] [Payments](https://docs.shipnative.app/core-features/payments.md)
>
> Set up RevenueCat

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