Skip to main content
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:
ToolHow to InstallVerify
Node.js 20Volta (recommended): curl https://get.volta.sh | bash && volta install node@20.19.0 yarn@4.9.1node -v → v20.x.x
YarnIncluded with Volta, or: corepack enableyarn -v → 4.x.x
GitmacOS: xcode-select --install / Windows: git-scm.comgit --version
Xcode (iOS)Mac App Store - open once to accept licenseN/A
Android Studio (Android)developer.android.com/studio - install SDK during setupN/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:
BackendBest For
SupabaseSQL apps, PostgreSQL experience, RLS-based security
ConvexTypeScript-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.
ServiceWhere to Find Credentials
SupabaseDashboard → Settings → API → Publishable key
Google OAuthGoogle Cloud Console → APIs & Services → Credentials
Apple Sign InApple Developer Portal → Certificates, IDs & Profiles
RevenueCatDashboard → Your App → API Keys
PostHogDashboard → Project Settings → API Keys
SentryDashboard → Settings → Client Keys (DSN)
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: 
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
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:
ServiceMock Behavior
Supabase/ConvexIn-memory auth/database, login always succeeds
RevenueCatPurchases succeed instantly, dev menu toggle
PostHogEvents logged to console
SentryErrors 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