@expo/repack-app

Repacking tool for Expo apps

API Documentation

CLI Usage

repack-app [options] [project-root]

Options

• -p, --platform <platform> (required): Platform to repack the app for (android or ios)
• --source-app <path> (required): Path to the source app file (APK/AAB for Android, IPA for iOS)
• --android-build-tools-dir <path>: Path to the Android build tools directory
• -w, --working-directory <path>: Path to the working directory
• -o, --output <path>: Path to the output artifact
• -v, --verbose: Enable verbose logging

Android-specific Options

• --ks <path>: Path to the keystore file
• --ks-pass <password>: Keystore password (supported formats: pass:<password>, env:<name>, file:<file>)
• --ks-key-alias <alias>: Keystore key alias
• --ks-key-pass <password>: Keystore key password (supported formats: pass:<password>, env:<name>, file:<file>)

iOS-specific Options

• --signing-identity <identity>: Code signing identity (fastlane backend, macOS only)
• --provisioning-profile <path>: Path to the provisioning profile file(s)
• --certificate <path>: Path to a .p12 signing identity. Signs with zsign instead of fastlane, in-process through WASM — no Xcode or keychain required, so it also works on Linux
• --key-password <password>: Password for the .p12 signing identity

Bundle Options

• --embed-bundle-assets: Force embedding of bundle assets
• --bundle-assets-sourcemap-output <path>: Generate sourcemap at the specified path (used with --embed-bundle-assets)

Programmatic Usage

import { repackAppAndroidAsync, repackAppIosAsync } from '@expo/repack-app';

// For Android
await repackAppAndroidAsync({
  platform: 'android',
  projectRoot: '/path/to/project',
  sourceAppPath: '/path/to/source.apk',
  // Optional configurations
  workingDirectory: '/path/to/working/dir',
  outputPath: '/path/to/output.apk',
  verbose: true,
  androidSigningOptions: {
    keyStorePath: '/path/to/keystore.jks',
    keyStorePassword: 'pass:password', // or 'env:KEYSTORE_PASS' or 'file:/path/to/pass'
    keyAlias: 'alias',
    keyPassword: 'pass:key-password', // or 'env:KEY_PASS' or 'file:/path/to/key-pass'
  },
  androidBuildToolsDir: '/path/to/build-tools',
  exportEmbedOptions: {
    sourcemapOutput: '/path/to/sourcemap',
  },
  env: {
    // Additional environment variables
  },
});

// For iOS
await repackAppIosAsync({
  platform: 'ios',
  projectRoot: '/path/to/project',
  sourceAppPath: '/path/to/source.ipa',
  // Optional configurations
  workingDirectory: '/path/to/working/dir',
  outputPath: '/path/to/output.ipa',
  verbose: true,
  // Sign with fastlane and a macOS keychain identity (requires Xcode)
  iosSigningOptions: {
    signingIdentity: 'Apple Development: Name (Team ID)',
    provisioningProfile: '/path/to/profile.mobileprovision',
    keychainPath: '/path/to/keychain', // Optional
  },
  // ...or with zsign and a .p12, which needs no Xcode and runs on Linux:
  // iosSigningOptions: {
  //   backend: 'zsign',
  //   certificatePath: '/path/to/identity.p12',
  //   keyPassword: 'p12-password',
  //   provisioningProfile: '/path/to/profile.mobileprovision',
  // },
  exportEmbedOptions: {
    sourcemapOutput: '/path/to/sourcemap',
  },
  env: {
    // Additional environment variables
  },
});

Configuration Options

The following options are available when using the API programmatically:

Common Options

• platform: 'android' | 'ios' - The platform to repack the app for
• projectRoot: string - Path to the project root directory
• sourceAppPath: string - Path to the prebuilt app file (APK/AAB/IPA)
• workingDirectory?: string - Working directory for temporary files
• outputPath?: string - Path to the output app file (defaults to projectRoot/repacked.apk or projectRoot/repacked.ipa)
• verbose?: boolean - Enable verbose logging
• exportEmbedOptions?: ExportEmbedOptions - Options for embedding JS bundle. When specified, repack will generate bundle assets.
• skipWorkingDirCleanup?: boolean - Skip working directory cleanup
• env?: Record<string, string | undefined> - Environment variables

Android-specific Options

• androidSigningOptions?: AndroidSigningOptions - Options for signing the Android app
  • keyStorePath: string - Path to the keystore file
  • keyStorePassword: string - Keystore password (supported formats: pass:<password>, env:<name>, file:<file>)
  • keyAlias?: string - Keystore key alias
  • keyPassword?: string - Keystore key password (supported formats: pass:<password>, env:<name>, file:<file>)
• androidBuildToolsDir?: string - Path to Android SDK build-tools directory
• When sourceAppPath is an .aab, repack uses bundletool from PATH to convert it into a universal APK first and still outputs an APK.

iOS-specific Options

• iosSigningOptions?: IosSigningOptions - Options for signing the iOS app. A union discriminated by backend:

  backend: 'fastlane' (the default) signs with fastlane's resign action and a macOS keychain identity, so it requires Xcode:

  • signingIdentity: string - Code signing identity
  • provisioningProfile: string | Record<string, string> - Path to provisioning profile file(s)
  • keychainPath?: string - Path to the keychain file for codesign

  backend: 'zsign' signs with zsign in-process through zsign-wasm. No Xcode, keychain, or external binary, so it also works on Linux:

  • certificatePath: string - Path to a .p12 signing identity, as exported from Keychain Access or downloaded from the Apple Developer portal. It holds the private key together with the certificate chain, including the Apple WWDR intermediate that iOS requires at install time
  • keyPassword?: string - Password protecting the .p12
  • provisioningProfile: string | Record<string, string> - Path to provisioning profile file(s)

Environment Variables

• ANDROID_SDK_ROOT: Path to the Android SDK root directory (required for Android builds)
• bundletool: Required on PATH for Android .aab inputs
• UNSTABLE_REPACK_APP_ICON: Set to 1 or true to enable experimental app icon repacking

TV apps

App icon repacking supports Apple TV and Android TV. Repack detects a TV app from the source artifact — UIDeviceFamily in the iOS Info.plist, and the leanback launcher entries in AndroidManifest.xml — so there is no extra option to set. When the source app is a TV app, repack also runs its internal expo prebuild with EXPO_TV=1.

Repack does not generate TV images. It reuses what expo prebuild writes, so the icon comes from the @react-native-tvos/config-tv plugin options:

• Apple TV: appleTVImages, which needs all seven images. Without it the asset catalog has no .brandassets, and repack keeps the source icon and logs a warning.
• Android TV: androidTVBanner and androidTVIcon.