useRouter replace() adds item to the history in v2

[Cameron Pulcifer]

Which package manager are you using? (Yarn is recommended)

yarn

Summary

In expo-router v2, when I use router.replace(), it pushes a history item on the stack. I've tried with just the path as a string and also with the config object.

For some context, I'm inside a modal stack. When I call replace(), I want load a screen from the stack inside the current modal and have no history so when I click the done button, it can just call router.back(). But it pushes a new screen inside the modal and adds a back button to the screen. This worked fine in v1.

Minimal reproducible example

Modal setup:

<Stack.Screen
  name="details"
  options={{
    headerShown: false,
    presentation: 'modal',
    gestureEnabled: false,
  }}
/>

"details" stack (inside modal above)

<Stack>
  <Stack.Screen
    name="index"
  />
  <Stack.Screen
    name="edit"
  />
  <Stack.Screen
    name="another"
  />
</Stack>

Inside the index, click a button to go to the edit screen. Either of the following pushes an item on the history stack

router.replace('/details/edit');
router.replace({ path: '/details/edit' });

[Cameron Pulcifer]

I discovered the culprit - unstable_settings. When I added this to my root layout, it broke replace(). Is there a setting the re-enables replace to work correctly?

export const unstable_settings = {
  initialRouteName: 'index',
};

[Evan Bacon]

This is documented behavior: https://docs.expo.dev/routing/navigating-pages/#replacing-screens

Native navigation does not always support replace. For example on Twitter, you wouldn't be able to "replace" directly from a profile to a tweet, this is because the UI requires a back button to return to the feed or other top-level tab screen. In this case, replace would switch to the feed tab, and push the tweet route on top of it, or if you were on a different tweet inside the feed tab, it would replace the current tweet with the new tweet. This exact behavior can be obtained in Expo Router by using [unstable_settings](https://docs.expo.dev/router/advanced/router-settings).