iOS Deployment

Overview

Tareas uses Capacitor to package the web application as a native iOS app. This guide covers building and deploying to iOS devices, simulators, and the App Store.

macOS RequirediOS development requires a Mac with macOS. You cannot build iOS apps on Windows or Linux.

Prerequisites

Required Software

macOS 12.0 or later
Xcode 14.0 or later (latest stable version recommended)
Node.js 18+ and npm 9+
CocoaPods - Dependency manager for iOS
Apple Developer Account (for physical device testing and App Store deployment)

Install Xcode

Download Xcode

Install Xcode from the Mac App Store:

Open the App Store app
Search for “Xcode”
Click Install

Alternatively, download from developer.apple.com/xcode

Install Command Line Tools

After Xcode installation:

xcode-select --install

Accept Xcode License

sudo xcodebuild -license accept

Install CocoaPods

CocoaPods manages iOS dependencies:

sudo gem install cocoapods

Verify installation:

pod --version

Initial Capacitor Setup

Install dependencies

Make sure all npm packages are installed:

npm install

Add iOS platform

Add the iOS platform to your Capacitor project:

npx cap add ios

This creates an ios/ directory with the native iOS project.

Sync project files

Synchronize your web build with the native iOS project:

npx cap sync ios

This command:

Copies web assets to the iOS project
Updates native dependencies
Installs CocoaPods dependencies

Building for iOS

Development Build

Build the web app

Create a production build of the web application:

npm run build --configuration production

Sync with iOS

Copy the web assets to the iOS project:

npx cap sync ios

Open in Xcode

Open the iOS project in Xcode:

npx cap open ios

This opens the .xcworkspace file in Xcode.

Configure signing

In Xcode:

Select the App target in the project navigator
Go to Signing & Capabilities tab
Select your Team (Apple Developer account)
Xcode will automatically manage signing certificates

Run on simulator or device

Select a simulator or connected device from the device dropdown
Click the Run button (▶️) or press Cmd + R

Alternative: Using Ionic CLI

# Build and run in one command
ionic capacitor build ios

This builds the web app and opens the project in Xcode.

Running on Simulator

Using Xcode

Open project

npx cap open ios

Select simulator

In Xcode, click the device dropdown and select a simulator:

iPhone 15 Pro
iPhone 15
iPad Pro (12.9-inch)
etc.

Build and run

Click the Run button or press Cmd + R.The simulator will launch and the app will be installed automatically.

Using Command Line

List available simulators:

xcrun simctl list devices

Boot a simulator:

xcrun simctl boot "iPhone 15 Pro"

Build and run:

ionic capacitor run ios

Running on Physical Device

Apple Developer Account RequiredTo deploy to a physical iOS device, you need:

An Apple Developer account (free or paid)
A registered device (for free accounts)
Proper provisioning profile and signing certificate

Connect your device

Connect your iPhone or iPad to your Mac via USB cable.

Trust your computer

On your iOS device:

A prompt will appear asking to “Trust This Computer?”
Tap Trust and enter your device passcode

Open project in Xcode

npx cap open ios

Configure signing

In Xcode:

Select the App target
Go to Signing & Capabilities
Check Automatically manage signing
Select your Team

Select your device

From the device dropdown, select your physical device (e.g., “Miguel’s iPhone”).

Build and run

Click Run (▶️) or press Cmd + R.Xcode will:

Build the app
Install it on your device
Launch the app automatically

Trust developer certificate (first time only)

On your device:

Go to Settings > General > VPN & Device Management
Tap on your developer certificate
Tap Trust

Complete Workflow

Typical development workflow:

# Install dependencies
npm install

# Add iOS platform
npx cap add ios

# Install CocoaPods dependencies
npx cap sync ios

Troubleshooting

CocoaPods Installation Issues

If CocoaPods fails to install or update:

# Update CocoaPods
sudo gem install cocoapods

# Update pod repository
pod repo update

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

Signing Errors

Common signing issues:“No signing certificate found”

Ensure you’re logged into Xcode with your Apple ID
Go to Xcode > Preferences > Accounts and sign in

“No provisioning profiles found”

Enable Automatically manage signing in Xcode
Xcode will create the necessary profiles

“Failed to register bundle identifier”

Change the Bundle Identifier in Xcode to something unique
Format: com.yourcompany.tareas

Device Not Recognized

If your device doesn’t appear in Xcode:

Unlock your device
Disconnect and reconnect the USB cable
Trust the computer again if prompted
Restart Xcode
Check cable (try a different USB port or cable)

Build Fails After Dependency Updates

Clean and rebuild:

# Clean project
cd ios/App
xcodebuild clean

# Reinstall pods
rm -rf Pods Podfile.lock
pod install

# Sync again
cd ../..
npx cap sync ios

Simulator Not Launching

Reset the simulator:

# List simulators
xcrun simctl list devices

# Erase a specific simulator
xcrun simctl erase "iPhone 15 Pro"

# Or reset all simulators
xcrun simctl erase all

App Crashes on Launch

View logs in Xcode:

Open Window > Devices and Simulators
Select your device
View console logs in the lower panel

Or use Console.app:

Open Console.app on macOS
Filter by your app name or “Capacitor”

App Store Deployment

Prepare for Release

Update app configuration

In Xcode, update:

Version (e.g., 1.0.0)
Build number (increment for each submission)
App Icons (all required sizes)
Launch Screen

Create App Store Connect record

Go to App Store Connect
Click My Apps > +
Create a new app
Fill in app information

Archive the app

In Xcode:

Select Any iOS Device (arm64) as the destination
Go to Product > Archive
Wait for the archive to complete

Upload to App Store Connect

When the archive finishes:

The Organizer window opens automatically
Select your archive
Click Distribute App
Choose App Store Connect
Follow the wizard to upload

Submit for review

In App Store Connect:

Complete all required metadata
Add screenshots for all device sizes
Submit for App Store review

Apple’s review process typically takes 24-48 hours. Ensure your app complies with the App Store Review Guidelines.

TestFlight Beta Testing

Before public release, test with TestFlight:

After uploading to App Store Connect, the build appears in TestFlight
Add internal testers (up to 100)
Add external testers (requires beta app review)
Testers receive an invitation email
They install via the TestFlight app

Configuration Files

Update Bundle Identifier

In capacitor.config.json:

{
  "appId": "com.yourcompany.tareas",
  "appName": "Tareas",
  "webDir": "www",
  "bundledWebRuntime": false
}

Update App Icons

Place app icons in:

ios/App/App/Assets.xcassets/AppIcon.appiconset/

Required sizes: 20pt, 29pt, 40pt, 60pt, 76pt, 83.5pt, 1024pt (all at 1x, 2x, and 3x).

Update Launch Screen

Edit the storyboard:

ios/App/App/Base.lproj/LaunchScreen.storyboard

Or use Capacitor’s splash screen plugin.

Live Reload on Device

For faster development, use live reload:

Find your local IP

ifconfig | grep "inet " | grep -v 127.0.0.1

Start dev server

ionic serve

Update capacitor config

Temporarily add to capacitor.config.json:

{
  "server": {
    "url": "http://YOUR_LOCAL_IP:8100",
    "cleartext": true
  }
}

Sync and run

npx cap sync ios
npx cap open ios

Run on your device - it will load from your dev server with live reload.

Remember to remove the server configuration before production builds!

Next Steps

Android Deployment

Build and deploy to Android devices

Web Build

Deploy as a web application

Build & Deploy

Overview

Prerequisites

Required Software

Install Xcode

Install CocoaPods

Initial Capacitor Setup

Building for iOS

Development Build

Alternative: Using Ionic CLI

Running on Simulator

Using Xcode

Using Command Line

Running on Physical Device

Complete Workflow

Troubleshooting

CocoaPods Installation Issues

Signing Errors

Device Not Recognized

Build Fails After Dependency Updates

Simulator Not Launching

App Crashes on Launch

App Store Deployment

Prepare for Release

TestFlight Beta Testing

Configuration Files

Update Bundle Identifier

Update App Icons

Update Launch Screen

Live Reload on Device

Next Steps

Android Deployment

Web Build

Build docs developers (and LLMs) love

Build & Deploy

​Overview

​Prerequisites

​Required Software

​Install Xcode

​Install CocoaPods

​Initial Capacitor Setup

​Building for iOS

​Development Build

​Alternative: Using Ionic CLI

​Running on Simulator

​Using Xcode

​Using Command Line

​Running on Physical Device

​Complete Workflow

​Troubleshooting

​CocoaPods Installation Issues

​Signing Errors

​Device Not Recognized

​Build Fails After Dependency Updates

​Simulator Not Launching

​App Crashes on Launch

​App Store Deployment

​Prepare for Release

​TestFlight Beta Testing

​Configuration Files

​Update Bundle Identifier

​Update App Icons

​Update Launch Screen

​Live Reload on Device

​Next Steps

Android Deployment

Web Build

Build docs developers (and LLMs) love

Overview

Prerequisites

Required Software

Install Xcode

Install CocoaPods

Initial Capacitor Setup

Building for iOS

Development Build

Alternative: Using Ionic CLI

Running on Simulator

Using Xcode

Using Command Line

Running on Physical Device

Complete Workflow

Troubleshooting

CocoaPods Installation Issues

Signing Errors

Device Not Recognized

Build Fails After Dependency Updates

Simulator Not Launching

App Crashes on Launch

App Store Deployment

Prepare for Release

TestFlight Beta Testing

Configuration Files

Update Bundle Identifier

Update App Icons

Update Launch Screen

Live Reload on Device

Next Steps