Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

iOS: first foreground after launch remounts the whole app (isHeadless written into root appProperties)

Open Beginner friendly
  • Is something wrong?
#340 1 comment 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
66/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
objective-c, react-native
Domain
mobile

Research direction

Start in the Objective-C NativeVoltra module, at the UIApplicationWillEnterForegroundNotification observer and the updateRootAppPropertiesHeadless: method that writes isHeadless into the root view's appProperties. Confirm that a normal launch has no isHeadless key and that the early return only triggers on equal values. Reproduce on an iOS simulator by foregrounding once after a normal launch and watching Metro for the setSurfaceProps log. Done when the first foreground after a normal launch leaves surface props unchanged, and a background launch still sets YES and later clears it.

Written by the indexing model from the issue text.

Description

platform:iOS
Library Version

2.3.2 (the same code is in 2.4.0)

React Native Version

0.86.3 (New Architecture / Fabric)

React Version

19.2.3

Expo Version

57.0.22

Minimal Reproduction
  1. Launch an app that uses @use-voltra/ios-client normally (foreground). Its root view's appProperties has no isHeadless key.
  2. Send the app to the background, then bring it back.
  3. Watch Metro: on that first foreground React Native logs Updating props for Surface "main" with {"rootTag":…,"initialProps":{"isHeadless":false},"fabric":true}, and the whole React tree unmounts and remounts. Later foregrounds don't do it again, because the key is now present.

Expected: foregrounding an app that was launched normally doesn't change its surface props.

Actual: the first foreground after every launch remounts the app. Anything in flight is torn down. For example, a ScrollView mid pull-to-refresh is unmounted while refreshing, and screen state and effects all reset.

Additional Information (Optional)

NativeVoltra observes UIApplicationWillEnterForegroundNotification and calls updateRootAppPropertiesHeadless:NO. That method only returns early when the existing value equals the new one:

if ([nextProperties[@"isHeadless"] isEqual:nextValue]) {
  return;
}
nextProperties[@"isHeadless"] = nextValue;
[rootView setValue:nextProperties forKey:@"appProperties"];

For a normal launch the key is missing, so nil isn't equal to @NO and Voltra writes it. Setting appProperties makes React Native call AppRegistry.setSurfaceProps, which re-runs the root.

A missing key already reads as "not headless" for anyone reading the prop, so skipping the write in that case fixes it without changing what headless launches see:

if (!isHeadless && nextProperties[@"isHeadless"] == nil) {
  return;
}

With this guard, the first foreground no longer updates the surface props or remounts anything (checked on an iOS 26.5 simulator). A background launch still sets YES and later clears it, since only the missing-key case is skipped. We're carrying it as a local patch for now and are happy to open a PR.

Dominant language
TypeScript
Stars
844
Forks
45
Avg merge
2d 14h
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from callstackincubator/voltra

All issues in callstackincubator/voltra

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.