timesafari

3.5 KiB

Raw Blame History

iOS Simulator Build and App Icon Troubleshooting

Author: Matthew Raymer
Date: 2025-07-12
Status: 🎯 ACTIVE - In Use

Overview

This guide documents how to build and run the TimeSafari iOS app in the simulator, and how to resolve common issues with iOS app icons and AppIcon.appiconset errors.

Building and Running the iOS App in Simulator

1. Build the App

Use the npm script to build for development (debug/simulator):

npm run build:ios:dev

This prepares the iOS project for simulator deployment.

2. Run in Simulator

Use Capacitor to launch the app in the iOS Simulator:

npx cap run ios

This will:

Sync web assets
Build the native iOS app
Launch the iOS Simulator
Install and run the app

3. Open in Xcode (Optional)

To open the project in Xcode for manual simulator/device control:

npm run build:ios:dev -- --studio

Or:

npx cap open ios

Common App Icon and AppIcon.appiconset Errors

Typical Error Message

error: None of the input catalogs contained a matching stickers icon set or app
icon set named "AppIcon".

Why This Happens

The iOS build expects an AppIcon.appiconset in ios/App/App/Assets.xcassets/.
If missing or incomplete, the build fails.
The icon generator may also fail if the source icon is missing or invalid.

Typical Causes

No AppIcon.appiconset directory
No or invalid Contents.json in the icon set
Missing or corrupt icon.png in assets/
Generator tool errors (permissions, path, or file type)

Step-by-Step: Generating iOS App Icons

1. Automatic Generation (Preferred)

Place a valid PNG icon (at least 1024x1024) at assets/icon.png.
Run:

npx capacitor-assets generate --ios

This should create ios/App/App/Assets.xcassets/AppIcon.appiconset/ with all required icon sizes and a Contents.json.

Troubleshooting Automatic Generation

If you see errors about missing directories, create them manually:

mkdir -p ios/App/App/Assets.xcassets/AppIcon.appiconset

If you see errors about file type, ensure icon.png is a real PNG (not SVG).
If the generator fails with a TypeError, check for missing or corrupt files.

2. Manual Generation (Fallback)

Use an online tool like appicon.co to generate iOS icons from your icon.png.
Download and extract the zip.
Copy the contents into:

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

Ensure the Contents.json is present and valid.

Directory Structure

ios/App/App/Assets.xcassets/
  └── AppIcon.appiconset/
      ├── Contents.json
      ├── AppIcon-20x20@2x.png
      ├── AppIcon-20x20@3x.png
      ├── ...
      └── AppIcon-1024x1024@1x.png

Troubleshooting Checklist

Is assets/icon.png present and a valid PNG?
Does AppIcon.appiconset exist in Assets.xcassets?
Is Contents.json present and correct?
Are all required icon PNGs present?
If using the generator, did it complete without errors?
If manual, did you copy all files from the zip?

iOS Build Troubleshooting

If the build fails with icon errors, fix the icon set and rebuild.
If the simulator does not launch, try running:

npx cap open ios

and launch from Xcode.

For other build errors, check the logs for missing files or permissions.

Status: In Use
Last Updated: 2025-07-12
Maintainer: Matthew Raymer

3.5 KiB Raw Blame History