Scripts Reference

Sovran includes a comprehensive set of scripts for development, building, testing, and deployment. This guide covers all available npm/yarn scripts.

Development Scripts

Start Development Server

Launch the Expo development server:

yarn start

npm start

This starts the Metro bundler and opens the Expo developer tools. From there you can:

Press i to open iOS simulator
Press a to open Android emulator
Scan the QR code with Expo Go on a physical device

Run on Platforms

iOS

Production Build
Development Mode

yarn ios

npm run ios

Builds and runs the app on the iOS simulator using production settings.

yarn start:emulator:ios

npm run start:emulator:ios

Runs expo run:ios with development mode enabled.

Android

Production Build
Development Mode

yarn android

npm run android

Builds and runs the app on the Android emulator using production settings.

yarn start:emulator:android

npm run start:emulator:android

Runs expo run:android with development mode enabled.

Build Scripts

Prebuild

Generate native iOS and Android projects:

yarn prebuild

npm run prebuild

Runs expo prebuild --clean which:

Deletes existing ios/ and android/ directories
Regenerates native projects from app.json configuration
Applies all Expo config plugins

Run this after:

Adding new native dependencies
Modifying app.json plugins
Changing native permissions

EAS Build - iOS

Production
Development

yarn build:ios

npm run build:ios

Builds iOS for production using EAS Build:

Platform: ios
Profile: production
Non-interactive mode
Auto-submit to App Store

Full command: eas build --platform ios --profile production --non-interactive --auto-submit

yarn build:dev:ios

npm run build:dev:ios

Builds iOS for development using EAS Build:

Platform: ios
Profile: development
Non-interactive mode
Development client enabled
Internal distribution

Full command: eas build --platform ios --profile development --non-interactive

EAS Build - Android

Development
Preview APK

yarn build:dev:android

npm run build:dev:android

Builds Android for development using EAS Build:

Platform: android
Profile: development
Development client enabled

Full command: eas build --platform android --profile development

yarn build:android:apk

npm run build:android:apk

Builds Android APK for preview/testing:

Platform: android
Profile: preview
Output: APK file
Internal distribution

Full command: eas build -p android --profile preview

EAS Build Profiles are configured in eas.json:

development - Dev client, internal distribution
preview - Testing builds, internal distribution
production - Production builds, auto-increment version

Submission Scripts

Submit builds to app stores using EAS Submit:

iOS App Store

yarn submit:ios

npm run submit:ios

Configuration (eas.json):

{
  "submit": {
    "production": {
      "ios": {
        "appleId": "business@sovranbitcoin.com",
        "ascAppId": "6499554529",
        "appleTeamId": "2ZTL7KLN2V"
      }
    }
  }
}

Android Play Store

yarn submit:android

npm run submit:android

Submits the latest Android build to Google Play Console.

Code Quality Scripts

Pre-Commit Requirement: All five code quality checks must pass before committing code.

Linting

Run ESLint to check for code issues:

yarn lint

npm run lint

Configuration:

Extends eslint-config-expo
Prettier integration
Unused imports detection
TypeScript support

Fix automatically:

yarn lint --fix

Type Checking

Run TypeScript compiler to check types:

yarn type-check

npm run type-check

Runs tsc --noEmit to validate TypeScript without emitting files. Common issues:

Missing type imports
Incorrect prop types
Untyped function parameters

Code Formatting

Check Formatting
Format Files

yarn pretty:check

npm run pretty:check

Checks if files are formatted correctly without modifying them.Pattern: ./**/*.{js,jsx,mjs,cjs,ts,tsx,json}

yarn pretty

npm run pretty

Formats all files using Prettier.Plugins:

prettier-plugin-tailwindcss - Sorts Tailwind classes

Find Dead Code

yarn knip

npm run knip

Runs Knip to find:

Unused exports
Unused dependencies
Unreachable code
Duplicate exports

Configuration: knip.json

Testing

Run Jest unit tests:

yarn test

npm test

Test framework: Jest with jest-expo preset

UI Testing

Maestro Tests

Run end-to-end UI tests with Maestro:

yarn maestro

npm run maestro

Runs all Maestro test flows in .maestro/ directory. Prerequisites:

Install Maestro CLI: brew tap mobile-dev-inc/tap && brew install maestro
Build app for simulator/emulator
Ensure device is running

Build Utilities

Theme Generation

Build background theme metadata:

yarn build:themes

npm run build:themes

Runs scripts/build-background-themes.js to:

Extract colors from background images
Generate theme metadata
Create palette definitions
Output to scripts/background-themes-metadata.json

Screenshot Utilities

Resize and optimize app screenshots:

yarn screenshots

npm run screenshots

Runs scripts/resize-screenshots.js to:

Resize screenshots for App Store
Optimize image sizes
Generate required dimensions

Automation Scripts

FreedomStore Release

Create a pull request to FreedomStore:

yarn release:freedomstore:pr

npm run release:freedomstore:pr

Runs scripts/create-freedomstore-pr.sh which:

Clones FreedomStore repository
Updates Sovran metadata
Creates a pull request
Automates release process

Lifecycle Hooks

Post-Install

Automatically runs after yarn install or npm install:

{
  "scripts": {
    "postinstall": "patch-package"
  }
}

Applies patches from patches/ directory:

coco-cashu-core+1.1.2-rc.47.patch
cashu-kym+0.4.1.patch

Patches are created with npx patch-package <package-name> after modifying node_modules.

Script Execution Order

For a typical development workflow:

# 1. Install dependencies
yarn install

# 2. Start development server
yarn start

# 3. Run on device (separate terminal)
yarn ios  # or yarn android

# 4. Before committing:
yarn lint
yarn type-check
yarn pretty:check
yarn knip
yarn test

# 5. Format if needed
yarn pretty

# 6. Commit changes
git add .
git commit -m "feat: add new feature"

Production Build Workflow

iOS Production Release

# 1. Build for production (auto-submits)
yarn build:ios

# 2. Or manually submit after build
yarn submit:ios

Android Production Release

# 1. Build APK for testing
yarn build:android:apk

# 2. Test APK on device
# ...

# 3. Build production AAB
eas build --platform android --profile production

# 4. Submit to Play Store
yarn submit:android

Troubleshooting

Clear Cache

If you encounter build issues:

# Clear Metro bundler cache
yarn start --clear

# Clear Expo cache
rm -rf .expo

# Clear node modules and reinstall
rm -rf node_modules
yarn install

# Regenerate native projects
yarn prebuild

Build Errors

If EAS builds fail:

# Check EAS build logs
eas build:list

# View specific build
eas build:view <build-id>

# Check credentials
eas credentials

Type Errors

If type checking fails:

# Check specific file
npx tsc --noEmit path/to/file.ts

# Generate types for Expo Router
npx expo customize tsconfig.json

CI/CD Integration

GitHub Actions Workflow

The repository includes a CI workflow (.github/workflows/ci.yml) that runs:

steps:
  - run: yarn install
  - run: yarn lint
  - run: yarn type-check
  - run: yarn pretty:check
  - run: yarn test

Status Badge:

Environment Variables

EAS Build Environment

Configure per-profile environments in eas.json:

{
  "build": {
    "development": {
      "env": {
        "APP_VARIANT": "development",
        "EXPO_NO_DEV_CLIENT": "1"
      }
    }
  }
}

Local Development

No .env file is needed for basic development. Sensitive values are stored in:

expo-secure-store - Runtime secrets
eas.json - Build secrets (use EAS Secrets for sensitive data)

Next Steps

Getting Started

Set up your development environment

Project Structure

Understand the codebase organization

Tech Stack

Learn about the technologies used

Contributing

Contribution guidelines and workflow

​Development Scripts

​Start Development Server

​Run on Platforms

​iOS

​Android

​Build Scripts

​Prebuild

​EAS Build - iOS

​EAS Build - Android

​Submission Scripts

​iOS App Store

​Android Play Store

​Code Quality Scripts

​Linting

​Type Checking

​Code Formatting

​Find Dead Code

​Testing

​UI Testing

​Maestro Tests

​Build Utilities

​Theme Generation

​Screenshot Utilities

​Automation Scripts

​FreedomStore Release

​Lifecycle Hooks

​Post-Install

​Script Execution Order

​Production Build Workflow

​iOS Production Release

​Android Production Release

​Troubleshooting

​Clear Cache

​Build Errors

​Type Errors

​CI/CD Integration

​GitHub Actions Workflow

​Environment Variables

​EAS Build Environment

​Local Development

​Next Steps

Getting Started

Project Structure

Tech Stack

Contributing

Development Scripts

Start Development Server

Run on Platforms

iOS

Android

Build Scripts

Prebuild

EAS Build - iOS

EAS Build - Android

Submission Scripts

iOS App Store

Android Play Store

Code Quality Scripts

Linting

Type Checking

Code Formatting

Find Dead Code

Testing

UI Testing

Maestro Tests

Build Utilities

Theme Generation

Screenshot Utilities

Automation Scripts

FreedomStore Release

Lifecycle Hooks

Post-Install

Script Execution Order

Production Build Workflow

iOS Production Release

Android Production Release

Troubleshooting

Clear Cache

Build Errors

Type Errors

CI/CD Integration

GitHub Actions Workflow

Environment Variables

EAS Build Environment

Local Development

Next Steps