Build Properties

Configure native build settings with expo-build-properties.

The expo-build-properties config plugin lets you customize iOS and Android build settings from app.json without editing native files directly.

Installation

npx expo install expo-build-properties

Basic Usage

Add the plugin to your app.json:

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 34,
            "targetSdkVersion": 34,
            "minSdkVersion": 24
          },
          "ios": {
            "deploymentTarget": "13.4"
          }
        }
      ]
    ]
  }
}

Then run prebuild:

npx expo prebuild --clean

Android Configuration

SDK Versions

{
  "android": {
    "compileSdkVersion": 34,
    "targetSdkVersion": 34,
    "minSdkVersion": 24,
    "buildToolsVersion": "34.0.0"
  }
}

Property	Description	Default
compileSdkVersion	SDK version to compile against	34
targetSdkVersion	Target API level	34
minSdkVersion	Minimum supported API level	23
buildToolsVersion	Build tools version	34.0.0

NDK Version

{
  "android": {
    "ndkVersion": "26.1.10909125"
  }
}

Required for:

• React Native libraries with native C++ code
• Custom JNI modules
• Specific NDK features

Kotlin Version

{
  "android": {
    "kotlinVersion": "1.9.20"
  }
}

Gradle Properties

{
  "android": {
    "packagingOptions": {
      "pickFirst": [
        "**/libc++_shared.so"
      ]
    },
    "enableProguardInReleaseBuilds": true,
    "enableShrinkResourcesInReleaseBuilds": true
  }
}

Memory Settings

{
  "android": {
    "minHeapSize": "512m",
    "maxHeapSize": "4g"
  }
}

Multidex

{
  "android": {
    "usesCleartextTraffic": true,
    "useLegacyPackaging": false,
    "networkInspector": true
  }
}

ProGuard/R8

{
  "android": {
    "enableProguardInReleaseBuilds": true,
    "enableShrinkResourcesInReleaseBuilds": true,
    "extraProguardRules": "-keep class com.myapp.** { *; }"
  }
}

iOS Configuration

Deployment Target

{
  "ios": {
    "deploymentTarget": "13.4"
  }
}

iOS 13.4+ is required for Expo SDK 50+

Use Frameworks

{
  "ios": {
    "useFrameworks": "static"
  }
}

Options:

• "static": Use static frameworks (recommended)
• "dynamic": Use dynamic frameworks
• null: No frameworks (default)

Required for:

• Swift libraries
• Some CocoaPods dependencies

Flipper

{
  "ios": {
    "flipper": false
  }
}

Disable Flipper for:

• Production builds
• Smaller binary size
• Faster builds

New Architecture

{
  "ios": {
    "newArchEnabled": true
  },
  "android": {
    "newArchEnabled": true
  }
}

Enables React Native’s new architecture (Fabric, TurboModules).

Cocoapods

{
  "ios": {
    "cocoapodsInstallerCommand": "bundle exec pod install"
  }
}

Common Configurations

Minimum Example

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 24
          },
          "ios": {
            "deploymentTarget": "13.4"
          }
        }
      ]
    ]
  }
}

Production Optimized

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 34,
            "targetSdkVersion": 34,
            "minSdkVersion": 24,
            "buildToolsVersion": "34.0.0",
            "kotlinVersion": "1.9.20",
            "enableProguardInReleaseBuilds": true,
            "enableShrinkResourcesInReleaseBuilds": true
          },
          "ios": {
            "deploymentTarget": "13.4",
            "useFrameworks": "static",
            "flipper": false
          }
        }
      ]
    ]
  }
}

Development Optimized

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 24,
            "enableProguardInReleaseBuilds": false,
            "networkInspector": true
          },
          "ios": {
            "deploymentTarget": "13.4",
            "flipper": true
          }
        }
      ]
    ]
  }
}

New Architecture

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "newArchEnabled": true,
            "minSdkVersion": 24
          },
          "ios": {
            "newArchEnabled": true,
            "deploymentTarget": "13.4",
            "useFrameworks": "static"
          }
        }
      ]
    ]
  }
}

Monorepo Configuration

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 24,
            "packagingOptions": {
              "pickFirst": [
                "**/libc++_shared.so",
                "**/libfbjni.so"
              ]
            }
          },
          "ios": {
            "deploymentTarget": "13.4"
          }
        }
      ]
    ]
  }
}

Platform-Specific Features

Android Only

Jetpack Compose

{
  "android": {
    "kotlinVersion": "1.9.20",
    "compileSdkVersion": 34
  }
}

Material 3

{
  "android": {
    "compileSdkVersion": 34,
    "targetSdkVersion": 34
  }
}

iOS Only

Swift Modules

{
  "ios": {
    "useFrameworks": "static"
  }
}

App Clips

{
  "ios": {
    "deploymentTarget": "14.0"
  }
}

EAS Build Integration

Build Profiles

eas.json

{
  "build": {
    "development": {
      "developmentClient": true,
      "android": {
        "buildType": "apk"
      }
    },
    "production": {
      "android": {
        "buildType": "aab"
      }
    }
  }
}

Combine with build properties:

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "enableProguardInReleaseBuilds": true
          }
        }
      ]
    ]
  }
}

Environment-Specific Configuration

Using app.config.js

app.config.js

const IS_PRODUCTION = process.env.NODE_ENV === 'production';

export default {
  expo: {
    plugins: [
      [
        'expo-build-properties',
        {
          android: {
            minSdkVersion: 24,
            enableProguardInReleaseBuilds: IS_PRODUCTION,
            enableShrinkResourcesInReleaseBuilds: IS_PRODUCTION,
            networkInspector: !IS_PRODUCTION,
          },
          ios: {
            deploymentTarget: '13.4',
            flipper: !IS_PRODUCTION,
          },
        },
      ],
    ],
  },
};

Multiple Configurations

app.config.js

const buildConfigs = {
  development: {
    android: {
      minSdkVersion: 24,
      networkInspector: true,
    },
    ios: {
      deploymentTarget: '13.4',
      flipper: true,
    },
  },
  production: {
    android: {
      minSdkVersion: 24,
      enableProguardInReleaseBuilds: true,
      enableShrinkResourcesInReleaseBuilds: true,
    },
    ios: {
      deploymentTarget: '13.4',
      flipper: false,
    },
  },
};

const config = buildConfigs[process.env.BUILD_ENV || 'development'];

export default {
  expo: {
    plugins: [['expo-build-properties', config]],
  },
};

Troubleshooting

Build Fails: SDK Version Mismatch

Error: The minSdkVersion should not be lower than 24

Solution:

{
  "android": {
    "minSdkVersion": 24
  }
}

iOS Build Fails: Framework Not Found

Error: framework not found 'Pods_MyApp'

Solution:

{
  "ios": {
    "useFrameworks": "static"
  }
}

Android Build Fails: Duplicate Classes

Error: Duplicate class found

Solution:

{
  "android": {
    "packagingOptions": {
      "pickFirst": [
        "**/libc++_shared.so"
      ]
    }
  }
}

CocoaPods Install Fails

Error: [!] CocoaPods could not find compatible versions

Solution:

# Update CocoaPods
cd ios
rm -rf Pods Podfile.lock
pod install --repo-update

Best Practices

1. Use Specific Versions

// Good
{
  "android": {
    "compileSdkVersion": 34,
    "kotlinVersion": "1.9.20"
  }
}

// Bad
{
  "android": {
    "compileSdkVersion": "latest"
  }
}

2. Match Platform Targets

{
  "android": {
    "minSdkVersion": 24,  // Android 7.0+
    "targetSdkVersion": 34
  },
  "ios": {
    "deploymentTarget": "13.4"  // iOS 13.4+
  }
}

3. Optimize for Release

{
  "android": {
    "enableProguardInReleaseBuilds": true,
    "enableShrinkResourcesInReleaseBuilds": true
  },
  "ios": {
    "flipper": false
  }
}

4. Test After Changes

# After modifying build properties
npx expo prebuild --clean
npx expo run:ios
npx expo run:android

Next Steps

Prebuild

Learn about the prebuild workflow

Creating Builds

Build with custom properties

Monorepos

Configure monorepo builds

Native Modules

Create native modules