Development Setup

This guide covers everything needed to set up, build, test, and deploy the Certi-Lock® mobile app locally.

Prerequisites

Tool	Version	Purpose
Node.js	20+	JavaScript runtime
npm	10+	Package management
Expo CLI	Latest	Development server and tooling
EAS CLI	>=16.0.1	Build and deployment
Xcode	15+	iOS development and simulator (macOS only)
Android Studio	Latest	Android development and emulator
Watchman	Latest	File watching (recommended on macOS)

Initial Setup

1. Clone the Repository

git clone <repo-url> scottsdale-mint-mobile-app
cd scottsdale-mint-mobile-app

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file in the project root with the required API keys:

# Algolia Product Search
EXPO_PUBLIC_ALGOLIA_API_KEY=<search-only-api-key>
EXPO_PUBLIC_ALGOLIA_APP_ID=<application-id>
EXPO_PUBLIC_ALGOLIA_INDEX_NAME=<index-name>

# Certi-Lock Image API
EXPO_PUBLIC_IMAGE_API_KEY=<api-key>
EXPO_PUBLIC_IMAGE_API_URL=<base-url>

# WordPress REST API (Banners + Error Logging)
EXPO_PUBLIC_WP_API_KEY=<api-key>
EXPO_PUBLIC_WP_API_URL=<base-url>

caution

Never commit the .env file to version control. It is already included in .gitignore. Contact the project lead for the required API keys.

4. Install EAS CLI (If Not Already Installed)

npm install -g eas-cli
eas login

5. Start the Development Server

npm start

This starts the Expo development server. Press:

i to open on iOS simulator
a to open on Android emulator
w to open in web browser (limited support)

Running on Devices

iOS Simulator (macOS Only)

npm run ios

Or select the simulator from the Expo dev server menu.

note

The custom native Vision Camera module requires a development build rather than Expo Go. Use npx expo run:ios for the first build, then subsequent runs can use the dev server.

Android Emulator

npm run android

Ensure an Android emulator is running or a physical device is connected via USB.

Physical Device

Install the Expo Dev Client build on the device (created via eas build --profile development)
Scan the QR code from the Expo dev server
The app connects to the local development server over the network

Build Commands

Development Commands

Command	Description
`npm start`	Start Expo development server
`npm run ios`	Run on iOS simulator
`npm run android`	Run on Android emulator
`npm run web`	Run in web browser (limited)
`npm test`	Run Jest test suite
`npm run lint`	Run ESLint checks
`npm run check-types`	TypeScript type checking

EAS Build Commands

# Development build (internal testing with dev client)
eas build --profile development --platform ios
eas build --profile development --platform android

# Preview build (internal distribution / staging)
eas build --profile preview --platform ios
eas build --profile preview --platform android

# Production build (app store submission)
eas build --profile production --platform ios
eas build --profile production --platform android

# iOS simulator build
eas build --profile simulator --platform ios

EAS Submit

# Submit to App Store
eas submit --platform ios

# Submit to Google Play
eas submit --platform android

EAS Build Configuration

The eas.json file defines build profiles:

{
  "cli": {
    "version": ">= 16.0.1",
    "appVersionSource": "remote"
  },
  "build": {
    "simulator": {
      "extends": "development",
      "ios": {
        "simulator": true
      }
    },
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {
      "autoIncrement": true
    }
  },
  "submit": {
    "production": {}
  }
}

Profile	Purpose	Distribution
`simulator`	iOS simulator testing	Internal
`development`	Development with hot reload	Internal
`preview`	Staging/QA testing	Internal
`production`	App store release	Public (auto-increment version)

Database Migrations

Creating a New Migration

After modifying the schema in db/schema.ts:

npx drizzle-kit generate

This generates a new SQL migration file in the drizzle/ directory.

Applying Migrations

Migrations apply automatically on app startup via the SQLiteProvider onInit callback. No manual step is needed — simply restart the app after generating new migrations.

Inspecting the Database

Use Expo's built-in SQLite inspector or a third-party tool:

# Using Drizzle Studio (browser-based)
npx drizzle-kit studio

Debugging

React Native Debugger

Press j in the Expo dev server terminal to open the JavaScript debugger in Chrome DevTools.

React Query DevTools

TanStack React Query devtools can be enabled for inspecting query state, cache, and mutations during development.

Sentry (Production Monitoring)

Dashboard: Check the Sentry project for crash reports and performance data
Dev mode: Traces sample rate is set to 1.0 (100%) for full visibility
Prod mode: Traces sample rate is set to 0.1 (10%) to reduce overhead

Common Debug Commands

# Clear Metro cache
npx expo start --clear

# Reset Expo dev client
npx expo start --dev-client --clear

# Check TypeScript errors
npm run check-types

# Lint all files
npm run lint

Testing

Jest Configuration

{
  "jest": {
    "preset": "jest-expo"
  }
}

Running Tests

# Watch mode (default)
npm test

# Single run
npx jest --no-watch

# With coverage
npx jest --coverage

Testing Dependencies

Package	Purpose
`jest`	Test runner
`jest-expo`	Expo-specific Jest preset
`react-test-renderer`	Component rendering for tests
`@types/jest`	TypeScript type definitions

Code Quality

ESLint

The project uses Expo's ESLint configuration:

npm run lint

TypeScript

Strict mode is enabled in tsconfig.json:

npm run check-types

Path Aliases

The @/ alias resolves to the project root:

// Instead of:
import { items } from "../../db/schema";

// Use:
import { items } from "@/db/schema";

Deployment Workflow

App Store (iOS)

Bump version in app.json (or let EAS auto-increment in production profile)
Build: eas build --profile production --platform ios
Submit: eas submit --platform ios
Review in App Store Connect, then release

Google Play (Android)

Bump version in app.json (or let EAS auto-increment in production profile)
Build: eas build --profile production --platform android
Submit: eas submit --platform android
Review in Google Play Console, then release

Internal Testing

Build: eas build --profile preview --platform all
Distribute via internal links (EAS generates install URLs)
Testers install directly on their devices

Troubleshooting

Native Module Build Failures

# iOS: Reinstall pods
cd ios && pod install --repo-update && cd ..

# Android: Clean Gradle
cd android && ./gradlew clean && cd ..

# Full clean rebuild
npx expo prebuild --clean

Metro Bundler Issues

# Clear all caches
npx expo start --clear
watchman watch-del-all  # macOS only
rm -rf node_modules/.cache

EAS Build Failures

# Check EAS credentials
eas credentials

# View build logs
eas build:list

# Check project configuration
eas diagnostics

Environment Variable Issues

Ensure variables are prefixed with EXPO_PUBLIC_
Restart the Expo dev server after changing .env
Variables are embedded at build time — rebuild for production changes

Prerequisites​

Initial Setup​

1. Clone the Repository​

2. Install Dependencies​

3. Configure Environment Variables​

4. Install EAS CLI (If Not Already Installed)​

5. Start the Development Server​

Running on Devices​

iOS Simulator (macOS Only)​

Android Emulator​

Physical Device​

Build Commands​

Development Commands​

EAS Build Commands​

EAS Submit​

EAS Build Configuration​

Database Migrations​

Creating a New Migration​

Applying Migrations​

Inspecting the Database​

Debugging​

React Native Debugger​

React Query DevTools​

Sentry (Production Monitoring)​

Common Debug Commands​

Testing​

Jest Configuration​

Running Tests​

Testing Dependencies​

Code Quality​

ESLint​

TypeScript​

Path Aliases​

Deployment Workflow​

App Store (iOS)​

Google Play (Android)​

Internal Testing​

Troubleshooting​

Native Module Build Failures​

Metro Bundler Issues​

EAS Build Failures​

Environment Variable Issues​