expo-fix-ios-simulator-arch

An Expo config plugin to automatically fix iOS Simulator arm64 architecture issues with a clean, project-level approach.

Problem

When running iOS apps on Apple Silicon Macs with the iOS Simulator, some CocoaPods dependencies may exclude the arm64 architecture, causing build failures with errors like:

building for iOS Simulator, but linking in object file built for iOS

Solution

This plugin provides three methods to fix the issue:

1. 🎯 Xcode Project Modification (Recommended)

Directly modifies the Xcode project's build settings. This is the most elegant and general solution as it:

• ✅ Works at the project level, no need to modify individual files
• ✅ No hardcoded paths
• ✅ Survives pod install/update
• ✅ Applies to all targets automatically
• ✅ Clean and maintainable

2. 📝 Podfile Hook

Adds a post_install hook to the Podfile that fixes all Pods automatically.

3. 🔄 Combined Approach

Uses both methods for maximum compatibility.

Installation

Local Installation (for this project)

Since this is a local plugin, you can use it directly in your app.config.js:

module.exports = {
  expo: {
    // ... other config
    plugins: [
      // ... other plugins
      './plugins/fix-ios-simulator-arch',
    ],
  },
};

NPM Package Installation (for publishing)

If you want to publish this as an npm package:

npm install expo-fix-ios-simulator-arch
# or
yarn add expo-fix-ios-simulator-arch

Then add to your app.config.js:

module.exports = {
  expo: {
    // ... other config
    plugins: [
      'expo-fix-ios-simulator-arch',
    ],
  },
};

Usage

Method 1: Xcode Project Modification (Default & Recommended)

This is the default behavior and the recommended approach:

// app.config.js
module.exports = {
  expo: {
    plugins: [
      // Simple usage - fixes all targets
      './plugins/fix-ios-simulator-arch',
    ],
  },
};

With options:

// app.config.js
module.exports = {
  expo: {
    plugins: [
      [
        './plugins/fix-ios-simulator-arch',
        {
          // Apply to all targets (default: true)
          applyToAllTargets: true,
          
          // Or specify specific targets (only used if applyToAllTargets is false)
          // applyToAllTargets: false,
          // targetNames: ['MorphixAI', 'MorphixAITests'],
        },
      ],
    ],
  },
};

Method 2: Podfile Hook

Use the Podfile modification approach:

const { withFixIOSSimulatorArchPodfile } = require('./plugins/fix-ios-simulator-arch');

module.exports = {
  expo: {
    plugins: [
      [
        withFixIOSSimulatorArchPodfile,
        {
          // No options needed
        },
      ],
    ],
  },
};

Method 3: Combined Approach

Use both methods for maximum compatibility:

const { withFixIOSSimulatorArchCombined } = require('./plugins/fix-ios-simulator-arch');

module.exports = {
  expo: {
    plugins: [
      [
        withFixIOSSimulatorArchCombined,
        {
          method: 'both', // or 'xcode', or 'podfile'
          applyToAllTargets: true,
        },
      ],
    ],
  },
};

Configuration Options

For Xcode Project Method

| Option | Type | Default | Description | |--------|------|---------|-------------| | applyToAllTargets | boolean | true | Whether to apply to all targets | | targetNames | string[] | [] | Specific target names to fix (only used if applyToAllTargets is false) |

For Combined Method

| Option | Type | Default | Description | |--------|------|---------|-------------| | method | string | 'xcode' | Method to use: 'xcode', 'podfile', or 'both' | | applyToAllTargets | boolean | true | Same as Xcode method | | targetNames | string[] | [] | Same as Xcode method |

How It Works

Xcode Project Method (Recommended)

This plugin uses withXcodeProject to directly modify the .pbxproj file. It:

1. Detects machine architecture using os.arch()
2. Only runs on Apple Silicon (arm64) - skips on Intel Macs
3. Automatically detects your project name
4. Only modifies DEBUG configurations (not Release)
5. Sets "EXCLUDED_ARCHS[sdk=iphonesimulator*]" to "" (empty string)
6. If the key doesn't exist, it adds it
7. If the key exists with arm64, it changes it to ""

Architecture Detection:

# Apple Silicon Mac (M1/M2/M3/M4)
os.arch() === 'arm64' → Apply fix ✅

# Intel Mac
os.arch() === 'x64' → Skip fix (not needed) ⏭️

Scenarios:

# Scenario 1: Key exists with arm64 (needs fix)
Before: EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64
After:  EXCLUDED_ARCHS[sdk=iphonesimulator*] = ""

# Scenario 2: Key doesn't exist (add it)
Before: (no key)
After:  EXCLUDED_ARCHS[sdk=iphonesimulator*] = ""

# Scenario 3: Key already correct (no change)
Before: EXCLUDED_ARCHS[sdk=iphonesimulator*] = ""
After:  EXCLUDED_ARCHS[sdk=iphonesimulator*] = "" (unchanged)

Why only Debug?

• Debug builds run on simulator (where the issue occurs)
• Release builds are for production and shouldn't be modified
• Keeps Release configuration clean and predictable

Why only on Apple Silicon?

• The arm64 exclusion issue only exists on Apple Silicon Macs
• Intel Macs don't need this fix
• Avoids unnecessary modifications on Intel machines

Podfile Method

Adds a post_install hook to the Podfile that runs after every pod install:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = ""
    end
  end
end

Why This Approach is Better

❌ Old Approach (Hardcoded Paths)

// Had to specify exact files
const filesToModify = [
  'ios/Pods/Target Support Files/Pods-MorphixAI/Pods-MorphixAI.debug.xcconfig',
  'ios/Pods/Target Support Files/Pods-MorphixAI/Pods-MorphixAI.release.xcconfig',
  // ... more hardcoded paths
];

Problems:

• Not portable across projects
• Breaks when pod names change
• Needs updates for new pods
• Only fixes after pod install

✅ New Approach (Project-Level)

// Automatically applies to all configurations
withXcodeProject(config, async (config) => {
  // Modify build settings at project level
  buildSettings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = '""';
});

Benefits:

• ✅ Works for any project
• ✅ No hardcoded paths
• ✅ Survives project changes
• ✅ Fixes at build configuration level
• ✅ More maintainable

When to Use

You should use this plugin if:

• You're developing on an Apple Silicon Mac (M1, M2, M3, M4, etc.)
• You encounter build errors related to architecture mismatches
• Some of your CocoaPods dependencies exclude arm64 for simulators
• You want a clean, maintainable solution

Comparison of Methods

| Feature | Xcode Project | Podfile Hook | Combined | |---------|--------------|--------------|----------| | No hardcoded paths | ✅ | ✅ | ✅ | | Survives pod install | ✅ | ✅ | ✅ | | Works with any project | ✅ | ✅ | ✅ | | Modifies project file | ✅ | ❌ | ✅ | | Modifies Podfile | ❌ | ✅ | ✅ | | Runs on prebuild | ✅ | ✅ | ✅ | | Runs on pod install | ❌ | ✅ | ✅ | | Simplicity | ⭐⭐⭐ | ⭐⭐ | ⭐ | | Recommended | ✅ | - | - |

Rebuilding

After adding this plugin, you need to:

1. Run prebuild:

npx expo prebuild --clean

2. Install pods (if needed):

cd ios && pod install && cd ..

3. Build your app:

npx expo run:ios

Verifying the Fix

Check Xcode Project Settings

Open Xcode and check Build Settings:

open ios/YourApp.xcworkspace

Look for EXCLUDED_ARCHS in Build Settings for the iOS Simulator SDK.

Check Podfile (if using Podfile method)

cat ios/Podfile

You should see the post_install hook with the architecture fix.

Check Build Logs

When you run npx expo prebuild, you should see:

🔧 Fixing iOS Simulator architecture in Xcode project...
  ✅ Fixed Debug configuration
  ✅ Fixed Release configuration
✨ Architecture fix complete! Modified 2 configuration(s).

Troubleshooting

Plugin doesn't seem to work

1. Make sure you've run npx expo prebuild --clean
2. Check that the plugin is listed in your config plugins array
3. Try running with --clear flag: npx expo prebuild --clean --clear

Build still fails

1. Clean your build folder: cd ios && rm -rf build && cd ..
2. Clean derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
3. Reinstall pods: cd ios && pod deintegrate && pod install && cd ..
4. Try the combined method: method: 'both'

Want to see what changed?

Check the git diff after running prebuild:

git diff ios/YourApp.xcodeproj/project.pbxproj

Alternative: Manual Fix Script

If you prefer not to use the plugin, you can still use the standalone script:

npm run ios:fix

This runs the script in scripts/fix-ios-arch.js.

Publishing as NPM Package

If you want to publish this plugin to npm for others to use:

1. Update package.json with your author information
2. Create an npm account if you don't have one
3. Login to npm: npm login
4. Publish: npm publish --access public

Then others can install it via:

npm install expo-fix-ios-simulator-arch

See PUBLISHING.md for detailed instructions.

Migration from Old Version

If you were using the old version that modified xcconfig files:

Old way:

plugins: [
  './plugins/fix-ios-simulator-arch', // Modified xcconfig files
]

New way (same usage, better implementation):

plugins: [
  './plugins/fix-ios-simulator-arch', // Now modifies Xcode project
]

No changes needed in your config! The plugin now uses the better approach automatically.

Examples

See example-usage.js for more examples.

Technical Details

Xcode Build Configuration

The plugin modifies the pbxXCBuildConfigurationSection in the .pbxproj file:

// Before
buildSettings = {
  EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64;
  // ... other settings
};

// After
buildSettings = {
  EXCLUDED_ARCHS[sdk=iphonesimulator*] = "";
  // ... other settings
};

Podfile Hook

The Podfile method adds Ruby code that runs after CocoaPods installation:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = ""
    end
  end
end

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

Created to solve iOS Simulator architecture issues on Apple Silicon Macs with a clean, maintainable approach.

Related Resources

• Expo Config Plugins
• Xcode Build Settings Reference
• CocoaPods Podfile
• Apple Silicon Support