Skip to main content

​
Prerequisites

Before you start, install these tools:
Recommended: Use Volta (automatically manages Node versions)
curl https://get.volta.sh | bash   # macOS/Linux
volta install node@20.19.0 yarn@4.9.1
Alternative: Use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
Verify installation:
node -v   # Should show v20.x.x
If you used Volta above, Yarn is already installed. Otherwise:
corepack enable          # Enables Yarn (included with Node)
Verify installation:
yarn -v   # Should show 4.x.x
macOS: Install Xcode Command Line Tools
xcode-select --install
Windows: Download from git-scm.comLinux:
sudo apt install git   # Ubuntu/Debian
  1. Install Xcode from the Mac App Store
  2. Open Xcode once and accept the license agreement
  3. Install iOS Simulator (Xcode → Settings → Platforms → iOS)
Xcode is ~12GB and only available on macOS.
  1. Download Android Studio
  2. During setup, install the Android SDK
  3. Create an emulator: Tools → Device Manager → Create Device
Works on macOS, Windows, and Linux.

​
Setup

git clone https://github.com/shipnativeapp/shipnative.git
cd shipnative
yarn install
yarn setup   # Optional: configure app name and services
cd apps/app
yarn ios     # or: yarn android, yarn web
Mock mode is enabled by default. You can skip yarn setup entirely and start building immediately. All services (auth, database, payments, analytics) work with simulated data. Configure real services when you’re ready for production.

​
Development Workflow

Important: yarn ios / yarn android compiles native code, which takes several minutes. You only need to run this once (or when native dependencies change).
For daily development, use this workflow: 
# First time only (builds native app)
cd apps/app
yarn ios     # Takes 3-5 minutes

# Daily development (fast refresh)
yarn start   # or: yarn dev
The dev server provides instant hot reload for JavaScript/TypeScript changes. You only need to rebuild with yarn ios when:
  • Adding/removing native dependencies
  • Changing app.json configuration
  • Modifying native code (Swift/Kotlin)
  • The app gets uninstalled from the simulator

​
Backend Choice

During yarn setup, you’ll choose between:
BackendBest For
SupabaseSQL apps, PostgreSQL experience, RLS-based security
ConvexTypeScript-first apps, reactive queries, function-level auth
Both work identically in mock mode. Choose based on your preference.
After you choose, setup automatically removes the other backend’s code and packages. You’ll have a clean codebase with only your chosen backend.

​
What’s Included

The app ships with working screens:
  • Welcome/Login/Signup - Full auth flow (Supabase or Convex)
  • Home - Main app screen
  • Profile - User settings and account deletion
  • Paywall - Subscription UI with mock purchases
  • Dev Menu - Cmd+D (iOS) / Cmd+M (Android) for debugging

​
AI-Assisted Development

Open your project in Cursor or Claude Code. To build features: 
Read AGENTS.md.
I want to build [describe your feature].
The AI reads the vibe/ context files and follows project patterns automatically.

​
Key Directories

LocationContents
apps/app/app/screens/Screen components
apps/app/app/components/Reusable UI components
apps/app/app/stores/Zustand stores (auth, subscriptions)
apps/app/app/services/Service clients (Supabase, Convex, RevenueCat, PostHog)
apps/app/app/hooks/Auth hooks (backend-specific after setup)
apps/app/app/theme/Unistyles theme tokens
convex/Convex backend functions (only if using Convex)
vibe/AI context files

​
Dev Menu

Access via Cmd+D (iOS) / Cmd+M (Android):
  • Toggle free/pro subscription
  • Switch light/dark mode
  • View component showcase
  • Check which services are mocked

​
Before Production

  1. Configure backend credentials (Supabase or Convex)
  2. Generate Android release keystore
  3. Update bundle identifiers in app.json
See Full Setup Guide.

​
Next Steps

Mock Services

How mock services work

Backend & Database

Choose and configure your backend

Full Setup

Configure all services

Deploy

Ship to app stores