Building for iOS

Requirements

Install Xcode

1. Open the App Store on your Mac
2. Search for Xcode
3. Click Get (it's free, but ~12GB download)
4. Wait for installation to complete

After installation:

bash
Copy
# Accept license agreement
sudo xcodebuild -license accept

# Install command line tools
xcode-select --install

Verify Installation

bash
Copy
xcodebuild -version
# Should show: Xcode 15.x (or higher)

Opening Your Project in Xcode

From your Capacitor project:

bash
Copy
npx cap open ios

This opens the Xcode workspace. Always open the .xcworkspace file, not the .xcodeproj.

Project Structure

In Xcode, you'll see:

App/
├── App/
│   ├── AppDelegate.swift      # App lifecycle
│   ├── public/                # Your web files (synced)
│   │   ├── index.html
│   │   └── ...
│   ├── Info.plist             # App configuration
│   └── Assets.xcassets        # App icons, images
├── Pods/                      # Dependencies
└── App.xcworkspace            # Open this!

Running on Simulator

Step 1: Select a Simulator

In Xcode's toolbar, click the device dropdown (next to the Play button).

Choose a simulator:

• iPhone 15 (or similar) for general testing
• iPhone SE for smaller screen testing
• iPad if you support tablets

Step 2: Build and Run

Click the Play button (▶) or press Cmd + R.

Xcode will:

1. Build your app
2. Launch the simulator
3. Install and run your app

Step 3: Debug

While running:

• Console: View → Debug Area → Activate Console
• Safari Dev Tools: Safari → Develop → Simulator → Your App

Running on a Physical Device

Step 1: Apple Developer Account

For device testing, you need an Apple account:

Free Apple ID (limited):

• Test on your own devices
• No App Store distribution
• Apps expire after 7 days

Apple Developer Program ($99/year):

• Unlimited device testing
• App Store distribution
• TestFlight beta testing

Step 2: Configure Signing

1. In Xcode, select the App project (top of file navigator)
2. Select the App target
3. Go to Signing & Capabilities
4. Check Automatically manage signing
5. Select your Team (your Apple ID)

Step 3: Connect Device

1. Connect your iPhone/iPad with a USB cable
2. On the device, tap Trust when prompted
3. The device appears in Xcode's device dropdown

Step 4: Build and Run

Select your device and click Play (▶).

First time on a new device:

1. Xcode installs a provisioning profile
2. Go to Settings → General → VPN & Device Management
3. Tap your developer certificate
4. Tap Trust

Now the app should launch!

Configuring Your App

App Icons

Replace the placeholder icons:

1. In Xcode, open Assets.xcassets → AppIcon
2. Drag your icon files to each size slot
3. Or use a tool like AppIcon Generator to generate all sizes

Icon requirements:

• 1024x1024 for App Store
• PNG format
• No transparency

Display Name

Edit capacitor.config.ts:

typescript
Copy
const config: CapacitorConfig = {
  appName: 'My Cool App',  // This is the display name
  // ...
};

Then sync: npx cap sync ios

Splash Screen

Install the splash screen plugin:

bash
Copy
npm install @capacitor/splash-screen
npx cap sync

Configure in capacitor.config.ts:

typescript
Copy
const config: CapacitorConfig = {
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      backgroundColor: '#ffffff',
      showSpinner: false,
    },
  },
};

For custom images, edit in Xcode's Assets.xcassets.

Status Bar

Control status bar appearance:

bash
Copy
npm install @capacitor/status-bar
npx cap sync

typescript
Copy
import { StatusBar, Style } from '@capacitor/status-bar';

// Set style
StatusBar.setStyle({ style: Style.Dark });

// Hide status bar
StatusBar.hide();

Info.plist Configuration

The Info.plist file controls iOS permissions and behaviors.

Common Configurations

Open ios/App/App/Info.plist and add:

Camera usage description (required if using camera):

xml
Copy
<key>NSCameraUsageDescription</key>
<string>We need camera access to take photos</string>

Photo library access:

xml
Copy
<key>NSPhotoLibraryUsageDescription</key>
<string>We need photo access to select images</string>

Location access:

xml
Copy
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need location to show nearby stores</string>

Live Reload Development

For faster development, use live reload:

1. Start your Next.js dev server:

   bash
   Copy
   npm run dev
   

2. Configure Capacitor for live reload:

   typescript
   Copy
   // capacitor.config.ts
   const config: CapacitorConfig = {
     server: {
       url: 'http://YOUR_LOCAL_IP:3000',  // e.g., 192.168.1.100
       cleartext: true,
     },
   };
   

3. Find your local IP:

   bash
   Copy
   ipconfig getifaddr en0
   # Or: ifconfig | grep "inet " | grep -v 127.0.0.1
   

4. Run on device/simulator:

   bash
   Copy
   npx cap run ios
   

Now changes to your web code appear instantly!

Debugging

Safari Developer Tools

1. Open Safari on your Mac
2. Go to Safari → Settings → Advanced
3. Check Show Develop menu in menu bar
4. With your app running, go to Develop → [Device/Simulator] → [Your App]

You get full web developer tools (console, elements, network, etc.)!

Xcode Console

View native logs in Xcode's debug area (View → Debug Area → Activate Console).

Common Debug Commands

typescript
Copy
// Log to Safari console
console.log('Debug message');

// Check if running in Capacitor
import { Capacitor } from '@capacitor/core';
console.log('Platform:', Capacitor.getPlatform());
console.log('Is native:', Capacitor.isNativePlatform());

Common Issues

bash
Copy
xcrun simctl shutdown all

bash
Copy
npx cap sync ios
cd ios && pod install

Preparing for App Store

When ready to submit:

1. Remove Development Settings

typescript
Copy
// capacitor.config.ts - REMOVE or comment out:
// server: {
//   url: 'http://localhost:3000',
//   cleartext: true,
// },

2. Build for Release

In Xcode:

1. Set device to "Any iOS Device"
2. Product → Archive
3. Follow the distribution workflow

3. Create App Store Connect Entry

Go to App Store Connect and:

1. Create your app
2. Fill in metadata
3. Upload screenshots
4. Submit for review

We cover this in detail in the deployment lesson.

Next: Set up Android development with Android Studio.