Full Setup

For quick start, see Quickstart. This guide covers full production configuration.

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 (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	`git --version`
Xcode (iOS)	Mac App Store - open once to accept license	N/A
Android Studio (Android)	developer.android.com/studio - install SDK during setup	N/A

New to JavaScript/Node? We recommend Volta - it automatically manages Node versions so you don’t have to think about it. Just run the install command above and you’re set.

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

git clone https://github.com/shipnativeapp/shipnative.git
cd shipnative
yarn install

Step 2: Run Setup Wizard

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:

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 for detailed comparison.

Service Configuration

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

Supabase
Convex

Service	Where to Find Credentials
Supabase	Dashboard → Settings → API → Publishable key
Google OAuth	Google Cloud Console → APIs & Services → Credentials
Apple Sign In	Apple Developer Portal → Certificates, IDs & Profiles
RevenueCat	Dashboard → Your App → API Keys
PostHog	Dashboard → Project Settings → API Keys
Sentry	Dashboard → Settings → Client Keys (DSN)

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:

# 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

Both JWT_PRIVATE_KEY and JWKS are required. Without them, sign-in will fail. See Convex Setup 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:

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

cd apps/app
yarn ios     # or: yarn android, yarn web

Manual Configuration

If you prefer manual configuration:

cp apps/app/.env.example apps/app/.env

Edit apps/app/.env:

Supabase
Convex

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

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:

{
  "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 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:

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:

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

cd apps/app
yarn start --clear

Builds are slow?

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

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

Next Steps

Backend & Database

Configure your chosen backend

Authentication

Set up user auth

Payments

Set up RevenueCat

Deploy

Ship to app stores

Introduction

Getting Started

Core Features

Development

Deployment

Support

Requirements

Prerequisites

Step 1: Clone and Install

Step 2: Run Setup Wizard

Backend Selection

Service Configuration

Security Note

Step 3: Run Your App

Manual Configuration

Mock Mode

Troubleshooting

Setup wizard fails?

”Package not found in project” error?

iOS build fails with Swift errors?

App won’t start?

Builds are slow?

API keys not working?

Next Steps

Backend & Database

Authentication

Payments

Deploy

​Requirements

​Prerequisites

​Step 1: Clone and Install

​Step 2: Run Setup Wizard

​Backend Selection

​Service Configuration

​Security Note

​Step 3: Run Your App

​Manual Configuration

​Mock Mode

​Troubleshooting

​Setup wizard fails?

​”Package not found in project” error?

​iOS build fails with Swift errors?

​App won’t start?

​Builds are slow?

​API keys not working?

​Next Steps

Backend & Database

Authentication

Payments

Deploy

Requirements

Prerequisites

Step 1: Clone and Install

Step 2: Run Setup Wizard

Backend Selection

Service Configuration

Security Note

Step 3: Run Your App

Manual Configuration

Mock Mode

Troubleshooting

Setup wizard fails?

”Package not found in project” error?

iOS build fails with Swift errors?

App won’t start?

Builds are slow?

API keys not working?

Next Steps