Installation

Prerequisites

Before setting up the DPM Delivery Mobile app, ensure you have the following tools and software installed on your development machine.

Required Software

Node.js

Version: LTS (18.x or higher recommended)Node.js is required to run the Expo development server and build tools.

# Check your Node.js version
node --version

Installation:

Download from nodejs.org
Or use a version manager like nvm:
```
nvm install --lts
nvm use --lts
```

Bun

Version: Latest stableBun is the recommended package manager for this project, offering faster installation and runtime performance.

# Check if bun is installed
bun --version

Installation:

# macOS, Linux, and WSL
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

While bun is recommended, you can also use npm or yarn. All examples in this documentation use bun, but the commands are interchangeable.

Expo CLI

Version: LatestExpo CLI is used to run and build the application. You don’t need to install it globally—npx expo works out of the box.

# Run Expo commands without global installation
npx expo --version

Optional Global Installation:

npm install -g expo-cli

Platform-Specific Setup

Choose the platform(s) you want to develop for and follow the corresponding setup instructions.

iOS
Android
Web

iOS Development Setup

iOS development requires a Mac with Xcode installed.

Install Xcode

Download and install Xcode from the Mac App Store.Minimum Version: Xcode 14.0 or higher

# Verify Xcode installation
xcode-select --version

Install Command Line Tools

Install Xcode Command Line Tools:

xcode-select --install

Accept the license agreement:

sudo xcodebuild -license accept

Install CocoaPods

CocoaPods is required for managing iOS dependencies:

sudo gem install cocoapods

Verify installation:

pod --version

Install iOS Dependencies

After cloning the project and installing npm packages, install iOS pods:

npx pod-install
# Or if you're in the ios directory:
cd ios && pod install

iOS Simulator

Xcode includes the iOS Simulator, which allows you to test the app without a physical device.Launch Simulator:

# List available simulators
xcrun simctl list devices

# Launch a specific simulator
open -a Simulator

The app is configured to support both iPhone and iPad (see app.json:12).

Physical iOS Device

To run on a physical iOS device:

Connect your iPhone/iPad via USB
Enable Developer Mode on the device (Settings > Privacy & Security > Developer Mode)
Trust your Mac when prompted
Run bun run ios --device

Android Development Setup

Android development requires Android Studio and the Android SDK.

Install Android Studio

Download and install Android Studio.During installation, ensure the following components are selected:

Android SDK
Android SDK Platform
Android Virtual Device (AVD)

Configure Android SDK

Open Android Studio and navigate to:

Settings > Appearance & Behavior > System Settings > Android SDK

Install the following:

Android 13.0 (Tiramisu) or higher
Android SDK Build-Tools
Android Emulator

Set Environment Variables

Add the following to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Windows:

setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"

Verify the setup:

echo $ANDROID_HOME
adb --version

Create an Android Virtual Device (AVD)

Open Android Studio
Go to Tools > Device Manager
Click Create Device
Select a device definition (e.g., Pixel 5)
Download and select a system image (Android 13+ recommended)
Finish the setup

Android Emulator

Launch Emulator:

# List available emulators
emulator -list-avds

# Launch a specific emulator
emulator -avd <device-name>

Or launch from Android Studio’s Device Manager.

The app uses edge-to-edge display mode (see app.json:22).

Physical Android Device

To run on a physical Android device:

Enable Developer Options (tap Build Number 7 times in Settings > About Phone)
Enable USB Debugging in Developer Options
Connect your device via USB
Verify connection: adb devices
Run bun run android

Web Development Setup

Web development requires the least setup—just a modern browser.Supported Browsers:

Chrome/Edge (recommended)
Firefox
Safari

Running on Web:

bun run web

The app will open in your default browser at http://localhost:8081 or similar.

The web version uses encrypted storage for secure token management (see src/utils/storage for implementation details).

Web-Specific Considerations

Some native features have web fallbacks:

SecureStore: Uses Web Crypto API
MMKV: Falls back to encrypted localStorage
Icons: Uses MaterialIcons instead of SF Symbols

Verifying Your Setup

After completing the installation, verify your development environment:

node --version
# Should output v18.x.x or higher

Installing the Project

Once your development environment is ready:

Clone the Repository

git clone https://github.com/Felix-Asante/dpm-delivery-mobile.git
cd dpm-parcel-delivery-app

Install Dependencies

npm install

This will install all dependencies listed in package.json:15.

Configure Environment

Create .env.local with required variables:

.env.local

EXPO_PUBLIC_API_BASE_URL=https://your-api.example.com
EXPO_PUBLIC_ENCRYPTION_KEY=your-encryption-key
EXPO_PUBLIC_WEB_CRYPTO_KEY=your-web-crypto-key

These environment variables are validated at runtime in src/utils/env.ts:1. Missing values will cause the app to crash.

Start Development Server

bun start

Choose your platform and start developing!

Next Steps

Quickstart Guide

Get the app running in minutes

Project Structure

Understand the codebase organization

Environment Setup

Learn about environment configuration

Configuration

Configure the app for your needs

Troubleshooting

Command not found errors

If you see “command not found” errors:

Ensure the tool is installed correctly
Verify PATH environment variables
Restart your terminal
Run source ~/.bashrc (or ~/.zshrc) to reload shell configuration

Android SDK issues

If Android tools aren’t recognized:

Verify ANDROID_HOME is set correctly
Ensure Android SDK is installed via Android Studio
Check that platform-tools are in your PATH

iOS pod install failures

If CocoaPods installation fails:

# Update CocoaPods
sudo gem install cocoapods

# Clean and reinstall
cd ios
rm -rf Pods Podfile.lock
pod install

Permission errors

If you encounter permission errors:

# Fix npm permissions (Unix)
sudo chown -R $(whoami) ~/.npm

# Or use a version manager like nvm to avoid sudo

Get Started

Core Features

Architecture

Development

API Reference

Deployment

Prerequisites

Required Software

Platform-Specific Setup

iOS Development Setup

iOS Simulator

Physical iOS Device

Android Development Setup

Android Emulator

Physical Android Device

Web Development Setup

Web-Specific Considerations

Verifying Your Setup

Installing the Project

Next Steps

Quickstart Guide

Project Structure

Environment Setup

Configuration

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Development

API Reference

Deployment

​Prerequisites

​Required Software

​Platform-Specific Setup

​iOS Development Setup

​iOS Simulator

​Physical iOS Device

​Android Development Setup

​Android Emulator

​Physical Android Device

​Web Development Setup

​Web-Specific Considerations

​Verifying Your Setup

​Installing the Project

​Next Steps

Quickstart Guide

Project Structure

Environment Setup

Configuration

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Required Software

Platform-Specific Setup

iOS Development Setup

iOS Simulator

Physical iOS Device

Android Development Setup

Android Emulator

Physical Android Device

Web Development Setup

Web-Specific Considerations

Verifying Your Setup

Installing the Project

Next Steps

Troubleshooting