iOS capture

Upload an unsigned Apple Silicon simulator build of your Storybook app.

Requirements#

Build an arm64 app for the iOS simulator, containing the JavaScript bundle and capture mode. A device IPA or an arm64 device binary is not a simulator app. Code signing is not required for the simulator build.

The current documented target is iPhone 17 / iOS 27. Confirm the offered simulator in your project when iOS is enabled. Your CI may build using EAS or Xcode on macOS; hosted capture itself runs in Framecheck.

EAS Build#

Initialise the EAS project if needed, then add a simulator capture profile to your existing eas.json:

{
  "build": {
    "framecheck": {
      "ios": { "simulator": true },
      "env": { "EXPO_PUBLIC_FRAMECHECK_CAPTURE": "1" }
    }
  }
}

Preserve any existing profiles and environment settings. The project must already select its Storybook entry in capture mode. Build the profile, obtain its simulator artifact, and use the Setup instructions for downloading/extracting it. EAS build access and any charges are managed by your Expo account.

Xcode on macOS#

Use the generated workspace and scheme for your app, with simulator SDK, release configuration, arm64, and signing disabled. The important build options are:

xcodebuild \
  -workspace ios/YourApp.xcworkspace \
  -scheme YourApp \
  -configuration Release \
  -sdk iphonesimulator \
  -derivedDataPath build/framecheck \
  ARCHS=arm64 CODE_SIGNING_ALLOWED=NO

Install the project's native dependencies first and set the capture environment for bundling. Use the generated command if your Expo/React Native version needs additional preparation.

Upload the app#

node framecheck-native.mjs upload \
  --platform ios \
  --app build/framecheck/Build/Products/Release-iphonesimulator/YourApp.app

On macOS the bundle identifier can be read from the app. On another host, provide --app-id com.example.storybook. The native CLI's pack command can package the app without uploading; see native CLI for packaging and local capture options.

If validation fails#

Check that the app was built for the simulator, includes arm64, and contains a bundled Storybook entry. Do not rename an IPA or device build to .app as a workaround. If the app launches but never connects, inspect capture mode and story generation.

iOS screenshot reliability improvements are being prepared. They do not require you to install capture software on your CI runner; continue to provide a valid simulator build.