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
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 |
- 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.
| 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) |
# 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.
AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRETAUTH_APPLE_ID, AUTH_APPLE_SECRETRESEND_API_KEY (for magic link emails)
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
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
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
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 |
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
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
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
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
