⚙️ Full Installation & Setup

This guide is for developers who want to configure all backend services, understand the full stack, and customize their Shipnative project from the ground up.

Just want to start building? Check out the Quickstart for Vibecoders instead. This guide is for those who want to configure real backend services from the start.

What You Actually Need to Do

For Development (Start Building Now)

Nothing! Just clone, install, and run. Mock services work out of the box.

For Production (Before App Store Release)

These are REQUIRED:

✅ Generate Android release keystore (CRITICAL - see below)
✅ Configure bundle identifiers in app.json
✅ Set up Supabase (minimum for auth + database)
⚠️ Configure certificate pinning (security - recommended)

These are OPTIONAL:

RevenueCat (for payments - can use mock mode)
PostHog (for analytics - can use mock mode)
Sentry (for error tracking - can use mock mode)

Prerequisites

Before you begin, make sure you have:

Node.js 20+ installed (download here)
Yarn installed (npm install -g yarn)
Xcode (for iOS development) or Android Studio (for Android development)
Git installed

Optional but recommended: Create accounts for the services you want to use:

Supabase - Authentication & database (REQUIRED for production)
RevenueCat - In-app purchases
PostHog - Analytics
Sentry - Error tracking

Step 1: Clone the Repository

After purchasing Shipnative, you will receive access to the private GitHub repository:

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

Step 2: Run the Setup Wizard

Shipnative includes an interactive setup wizard that configures your project’s metadata and integrates backend services.

yarn setup

Setup Wizard Features

The setup wizard includes several powerful features:

New in this version: The setup wizard now includes automatic backups, progress indicators, input masking for secrets, and support for CI/CD environments.

Prerequisites Check

The wizard automatically checks that you have:

Node.js 20+ installed
Yarn 4+ installed

If prerequisites are missing, you’ll see clear error messages with installation instructions. You can skip this check with --skip-prereqs if needed.

Automatic Backups

Before modifying any files, the wizard creates timestamped backups in .setup-backups/:

app.json backups
package.json backups
.env file backups

This allows you to easily revert changes if needed.

Progress Indicators

Long-running operations (like dependency installation) show progress spinners so you know the wizard is working.

Input Masking

When entering secrets (API keys, passwords), your input is automatically masked with * characters for security.

Skip Options

In wizard mode, you can skip remaining services at any time to speed up the setup process.

Setup Modes

The wizard offers three setup modes:

Guided Setup Wizard - Full walkthrough of metadata + all services
Service Configurator - Pick and configure services individually
Metadata Only - Update app metadata without configuring services

Command-Line Options

The setup script supports several command-line options:

# Show help and available options
yarn setup --help

# Non-interactive mode (for CI/CD)
yarn setup --non-interactive

# Preview changes without applying them
yarn setup --dry-run

# Validate service connections after configuration
yarn setup --validate-services

# Skip prerequisite checks
yarn setup --skip-prereqs

# Skip creating backups
yarn setup --skip-backup

Non-Interactive Mode: When using --non-interactive, the wizard reads configuration from environment variables. Set variables like WHAT_IS_YOUR_APP_S_DISPLAY_NAME to provide answers automatically.

What the Setup Wizard Does

The wizard will walk you through:

Project Metadata

App display name - What users see on their home screen
Bundle identifier - Unique ID for app stores (e.g., com.yourcompany.yourapp)
URL scheme - For deep linking (e.g., myapp://)

Backend Services (Optional)

You’ll be prompted to configure each service. You can skip any service to use mock mode instead.

Supabase - Authentication & Database

Required information:

Supabase project URL (e.g., https://your-project.supabase.co)
Supabase publishable key (starts with sb_publishable_...)

Where to find: Your Supabase project dashboard → Settings → API → Project API keys → anon / public key

Use the publishable key, not the service role key! The publishable key is safe to embed in your app and is protected by Row Level Security (RLS).

View detailed Supabase setup guide

Google OAuth (Optional)

Required information:

Google OAuth Web Client ID
Google OAuth iOS Client ID

Where to find: Google Cloud Console → APIs & Services → CredentialsView social login setup guide

Apple Sign In (Optional)

PostHog - Analytics

Required information:

PostHog API key
PostHog host URL

Where to find: PostHog dashboard → Project Settings → API KeysView analytics setup guide

RevenueCat - In-App Purchases

Required information:

RevenueCat iOS API key
RevenueCat Android API key

Where to find: RevenueCat dashboard → Your App → API KeysView payments setup guide

Sentry - Error Tracking

Required information:

Sentry DSN

Where to find: Sentry project dashboard → Settings → Client Keys (DSN)View error tracking guide

Firebase Cloud Messaging (Android Push)

Required information:

Firebase Server Key

Where to find: Firebase Console → Project Settings → Cloud MessagingView push notifications guide

Keep your API keys secure! The setup wizard creates an .env file in apps/app/.env which is git-ignored. Never commit API keys to version control.

⚠️ Important: Environment Variable Security

Critical: All EXPO_PUBLIC_* variables are bundled into your app and visible to anyone who inspects the app bundle. ✅ Safe to expose (these are designed to be public):

EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY - Protected by Row Level Security (RLS)
EXPO_PUBLIC_POSTHOG_API_KEY - Public analytics key
EXPO_PUBLIC_REVENUECAT_*_KEY - Public RevenueCat keys

❌ NEVER expose:

Supabase service_role key (server-side only)
Any secret keys or passwords
Private API keys that grant write access

Action Required:

Always configure RLS - Supabase Row Level Security is your primary defense. Never rely on hiding API keys.
Keep sensitive operations server-side - Use Supabase Edge Functions or your own backend for admin actions, payment processing, etc.
Use the publishable key - It’s designed to be public and is protected by RLS policies.

Security is your responsibility. If a key is compromised, rotate it immediately in your service dashboard and update your .env file.

Security Features in Setup Wizard

The setup wizard includes several security features:

Input Masking - Secrets are masked while typing (shown as *)
Git Ignore Check - Warns if .env files aren’t in .gitignore
Security Warnings - Reminds you about public key exposure
Automatic Backups - Creates backups before modifying files

The wizard will warn you if your .env file might be tracked in git.

Step 3: Install Dependencies

The setup wizard will offer to install dependencies automatically after configuration. If you skipped this or need to reinstall:

yarn install

This installs all packages for the monorepo workspace. The wizard shows a progress indicator during installation.

Step 4: Verify Setup

Setup Summary

After running the wizard, a setup summary is automatically generated at .setup-summary.json. This file contains:

Timestamp of setup
Metadata configuration
Services configured
Files modified

You can review this file to see what was configured:

cat .setup-summary.json

Verify Configuration Files

Check that everything is configured correctly:

# Check that .env file was created
cat apps/app/.env

# Check that app.json was updated with your bundle ID
cat apps/app/app.json

# View setup summary
cat .setup-summary.json

Check Backups

If you need to revert changes, backups are stored in .setup-backups/:

ls -la .setup-backups/

Each backup is timestamped, so you can identify when it was created.

Step 5: Run Your App

Navigate to the app directory and start development:

cd apps/app

# For iOS
yarn ios

# For Android
yarn android

Manual Configuration

If you prefer to configure services manually instead of using the setup wizard:

1. Copy Environment Template

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

2. Edit `.env` File

Open apps/app/.env and add your API keys:

# Supabase
EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_your-key-here

# PostHog
EXPO_PUBLIC_POSTHOG_API_KEY=your-api-key
EXPO_PUBLIC_POSTHOG_HOST=https://app.posthog.com

# RevenueCat
EXPO_PUBLIC_REVENUECAT_IOS_KEY=your-ios-key
EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=your-android-key

# Sentry
EXPO_PUBLIC_SENTRY_DSN=your-dsn

# OAuth (Optional)
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=your-web-client-id
EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=your-ios-client-id
EXPO_PUBLIC_APPLE_SERVICE_ID=your-service-id

# Firebase (Android Push)
FIREBASE_SERVER_KEY=your-server-key

3. Update `app.json`

Edit apps/app/app.json to set your bundle ID and app name:

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

Understanding Mock Mode

If you skip configuring a service, Shipnative automatically uses mock mode for that service:

Service	Mock Behavior
Supabase	In-memory auth & database. Login always succeeds.
RevenueCat	All purchases succeed instantly. Free ↔ Pro toggle in dev menu.
PostHog	Events logged to console. Feature flags always return `false`.
Sentry	Errors logged to console. No remote tracking.

This allows you to:

Build your entire frontend without backend dependencies
Test features offline
Develop without incurring API costs
Add real services only when ready to deploy

Mock mode is for development only! Before deploying to production:

You MUST set up Supabase (auth + database)
You MUST generate Android release keystore
You SHOULD configure certificate pinning for security

Learn more about mock services →

Next Steps

Project Structure

Understand how the codebase is organized

Configure Database

Set up your Supabase database schema

Set Up Payments

Configure RevenueCat products and subscriptions

Deploy Your App

Ship to app stores when you’re ready

Advanced Usage

CI/CD Integration

For automated setups in CI/CD pipelines, use non-interactive mode:

# Set environment variables
export WHAT_IS_YOUR_APP_S_DISPLAY_NAME="My App"
export WHAT_IS_YOUR_PROJECT_NAME="my-app"
export WHAT_IS_YOUR_BUNDLE_IDENTIFIER="com.company.app"
export WHAT_IS_YOUR_APP_SCHEME="myapp"
export DO_YOU_WANT_TO_SET_UP_SUPABASE_NOW="true"
export ENTER_YOUR_SUPABASE_PROJECT_URL="https://your-project.supabase.co"
export ENTER_YOUR_SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."

# Run in non-interactive mode
yarn setup --non-interactive

Dry Run Mode

Preview changes before applying them:

yarn setup --dry-run

This shows what would be changed without actually modifying any files.

Service Validation

Test service connections after configuration:

yarn setup --validate-services

This will attempt to connect to configured services (like Supabase) to verify your credentials are correct.

Restoring from Backup

If you need to revert changes:

# List available backups
ls -la .setup-backups/

# Restore a specific backup (example)
cp .setup-backups/app.json.2024-01-15T10-30-00-000Z.backup apps/app/app.json
cp .setup-backups/.env.2024-01-15T10-30-00-000Z.backup apps/app/.env

Troubleshooting

Setup wizard fails or crashes

If the setup wizard encounters errors:

Check prerequisites: Ensure Node.js 20+ and Yarn 4+ are installed
Delete any partial .env file: rm apps/app/.env
Run setup again: yarn setup
Check error messages - they now include context and suggestions
If still failing, configure manually (see “Manual Configuration” above)
Restore from backup if needed: ls .setup-backups/

Prerequisites check fails

The wizard checks for Node.js 20+ and Yarn 4+. If you have different versions:

Update to required versions, or
Run with --skip-prereqs to continue anyway (not recommended)

App won't start after setup

Common fixes:

# Clear Metro bundler cache
cd apps/app
yarn start --clear

# Reinstall dependencies
cd ../..
rm -rf node_modules apps/app/node_modules
yarn install

API keys aren't working

Verify:

Keys are in apps/app/.env (not root .env)
All keys are prefixed with EXPO_PUBLIC_ (except FIREBASE_SERVER_KEY)
No extra spaces or quotes around values
You restarted the Metro bundler after adding keys

Getting 'Supabase URL is undefined' error

This means the app is using mock mode because env variables aren’t loaded. Make sure:

.env file exists in apps/app/.env
You’re running from apps/app/ directory
Metro bundler was restarted after creating .env
Variable names use EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY (not EXPO_PUBLIC_SUPABASE_ANON_KEY)

Setup wizard shows 'Invalid input' errors

The wizard now includes improved validation:

URLs must start with https://
Bundle IDs must match format: com.company.app
Supabase keys must start with sb_publishable_ or be valid JWT tokens
Sentry DSNs must match the format: https://key@host/project-id

Check the error message for specific validation requirements.

Backups taking up space

Backups are stored in .setup-backups/. To clean up old backups:

# Remove backups older than 30 days
find .setup-backups -name "*.backup" -mtime +30 -delete

Or disable backups entirely with --skip-backup flag.

For more troubleshooting help, see the Troubleshooting Guide.

Introduction

🚀 Getting Started

🌟 Core Features

🧑‍💻 Development

🚀 Deployment

Support

​⚙️ Full Installation & Setup

​What You Actually Need to Do

​For Development (Start Building Now)

​For Production (Before App Store Release)

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Run the Setup Wizard

​Setup Wizard Features

​Prerequisites Check

​Automatic Backups

​Progress Indicators

​Input Masking

​Skip Options

​Setup Modes

​Command-Line Options

​What the Setup Wizard Does

​Project Metadata

​Backend Services (Optional)

​⚠️ Important: Environment Variable Security

​Security Features in Setup Wizard

​Step 3: Install Dependencies

​Step 4: Verify Setup

​Setup Summary

​Verify Configuration Files

​Check Backups

​Step 5: Run Your App

​Manual Configuration

​1. Copy Environment Template

​2. Edit .env File

​3. Update app.json

​Understanding Mock Mode

​Next Steps

Project Structure

Configure Database

Set Up Payments

Deploy Your App

​Advanced Usage

​CI/CD Integration

​Dry Run Mode

​Service Validation

​Restoring from Backup

​Troubleshooting

⚙️ Full Installation & Setup

What You Actually Need to Do

For Development (Start Building Now)

For Production (Before App Store Release)

Prerequisites

Step 1: Clone the Repository

Step 2: Run the Setup Wizard

Setup Wizard Features

Prerequisites Check

Automatic Backups

Progress Indicators

Input Masking

Skip Options

Setup Modes

Command-Line Options

What the Setup Wizard Does

Project Metadata

Backend Services (Optional)

⚠️ Important: Environment Variable Security

Security Features in Setup Wizard

Step 3: Install Dependencies

Step 4: Verify Setup

Setup Summary

Verify Configuration Files

Check Backups

Step 5: Run Your App

Manual Configuration

1. Copy Environment Template

2. Edit `.env` File

3. Update `app.json`

Understanding Mock Mode

Next Steps

Advanced Usage

CI/CD Integration

Dry Run Mode

Service Validation

Restoring from Backup

Troubleshooting