Navigation
react-navigation and expo-router both work, with no change to your app.
npm install @react-navigation/native @react-navigation/native-stack \
react-native-screens react-native-safe-area-contextScreens render, navigation.navigate pushes, and a press on a <Link> routes.
Verified by running both on a desktop host and reading the mounted view tree.
What you get on each desktop
Navigation itself works everywhere, today, with no patching and no upstream
change: screens render, navigate pushes, <Link> routes. What varies is the
screen machinery underneath.
| Windows | macOS and Linux | |
|---|---|---|
| navigation, routing | yes | yes |
| safe area insets | yes | yes |
| header bar | yes | yes |
| covered screen detached | yes | with basalt-navigation |
| body inset below the header | yes | with basalt-navigation |
Windows is complete on its own because react-native-screens already lists it as a platform it supports, so Basalt's components are reachable there. On macOS and Linux the library renders its own fallback views instead, and one package closes the gap.
npm install basalt-navigationimport {NavigationScreens} from 'basalt-navigation';
<NavigationScreens>
<NavigationContainer>{/* navigators, as usual */}</NavigationContainer>
</NavigationScreens>One wrapper, and the last two rows behave like Windows. It is not a patch or a
fork: react-native-screens picks the component it renders for each screen out
of a React context, the platform check lives inside the component it would
otherwise pick, and this provides a different one. ScreenStack needs nothing,
because it was never gated.
Harmless on Windows and on a phone, where the library already renders the same components. The one place not to put it is a web build, which has no native components to ask for.
Nothing about this blocks shipping an app. A covered screen that stays mounted is invisible, because the screen in front covers it; what it costs is a subtree that is still measured and still reachable by a screen reader.
Why Basalt cannot just turn it on
// react-native-screens/src/core.ts
export const isNativePlatformSupported =
Platform.OS === 'ios' || Platform.OS === 'android' || Platform.OS === 'windows';That const is what Screen checks, and it is not a list of platforms where
native screens could work. It is the list of platforms the library ships native
code for, which is why macos is absent: react-native-macos reports macos
too and has no implementation behind it, so adding the name would claim support
that does not exist and break those apps.
The change proposed upstream is therefore an opt-in rather than a longer list.
Basalt could patch the library through its own Metro config instead, and does
not: metro-config.ts argues that the library fallback "cannot be a list of
names", and owning a third-party module's internals for one library is the
worse problem.
What works
@react-navigation/native with native-stack | screens render and navigate |
| expo-router | file routes under app/, <Link> routing, the stock entry point |
SafeAreaProvider, useSafeAreaInsets | real insets, which are zero on a desktop |
initialWindowMetrics | the window the app started with |
Insets are zero on every desktop, which is the correct answer rather than a placeholder: a window has no notch and no home indicator. If a desktop ever draws over its own content, a title bar on top of the client area for instance, that is where a non-zero inset would come from.
Headers
A header is a bar when it has something in it, and nothing when it does not.
headerShown: false removes it. A header with a title, a back button or
anything custom becomes a bar sized to its content plus a margin, with the body
of the screen moved down below it rather than hidden behind it.
A plain string title draws nothing
// No header: the title goes to a toolbar this platform does not have.
<Stack.Screen name="Home" component={Home} options={{title: 'Home'}} />
// A header, because react-navigation renders a centred title as a view.
<Stack.Screen
name="Home"
component={Home}
options={{title: 'Home', headerTitleAlign: 'center'}}
/>
// Also a header, and the way to control what is in it.
<Stack.Screen
name="Home"
component={Home}
options={{headerTitle: () => <Text style={{fontWeight: '600'}}>Home</Text>}}
/>react-navigation sends a left-aligned string straight to the native navigation
bar as a prop, and renders it as a <Text> only when it is centred or supplied
as a component. Basalt can lay out a view; it cannot draw a prop that no bar
exists to receive. Rather than reserve an empty strip for one, a header with no
content takes itself out of the layout entirely, so the default looks like no
header instead of a broken one.
What does not, yet
- A covered screen stays mounted on macOS and Linux without
basalt-navigation. Pushing a second screen leaves the first in the view tree at full size, underneath. It looks right, because the top screen covers it, but both are measured and both reach accessibility. The wrapper above fixes it, and Windows never had it, for the reason above. - Tabs are untested.
TabsHostandTabsScreenship no desktop file, so the bundler falls back to their Android implementations and says so as it builds.
That one has a history worth recording, because the obvious fix is not the fix.
RNSScreen has an activityState prop and Basalt hides a screen whose
activityState is 0, which looks like the answer and is not: a native stack
never sets it to 0. react-native-screens throws activityState cannot be decreased in NativeStack, because on iOS the navigation controller covers the
lower screen rather than the prop. Measured rather than assumed, every screen in
a pushed stack reports 2, the covered ones included.
So the stack does it instead. RNSScreenStack gives every screen below the
topmost opaque one DisplayType::None after layout, which all three hosts
already turn into a hidden widget, and a hidden widget is out of the
accessibility tree on each of them. A transparent modal covers nothing, so the
search for "topmost opaque" walks past one.
Versions
expo-router needs the React Native its Expo SDK targets, which for SDK 57 is 0.86.3 and for SDK 58 is 0.88.1. Both are supported.
On 0.88, routing itself works. Checked on 2026-11-10 with SDK 58,
expo-router 58.0.30 and basalt-core from npm: routes are discovered, a Stack
renders, and Reanimated -- which expo-router depends on directly -- runs. The
two obstacles this page used to describe are gone. Expo's SDK 58 Metro config
no longer looks for the react-native/rn-get-polyfills that 0.87 dropped, and
@react-native/assets-registry no longer has to be hoisted because React
Native 0.88 does not ship it as a separate package at all.
Three things in the default template still need a hand, and none of them is the router:
NativeTabsis whatcreate-expo-appnow generates, and expo-router implements it for iOS and Android only -- it throws "You are using NativeTabs on an unsupported platform" anywhere else. AStackworks. This is expo-router's own platform gate, upstream of Basalt.@/*path aliases come fromtsconfig.json, and Expo installs tsconfig-path resolution in@expo/clirather than inexpo/metro-config. A config built ongetDefaultConfigalone -- which is whatbasalt initwrites -- does not get them, so the aliases have to be spelled out inmetro.config.jsas MetroresolveRequestentries.expo-device, which the template's own index route imports, has no native module here. See Expo for how that list works.