Basalt

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-context

Screens 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.

WindowsmacOS and Linux
navigation, routingyesyes
safe area insetsyesyes
header baryesyes
covered screen detachedyeswith basalt-navigation
body inset below the headeryeswith 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-navigation
import {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-stackscreens render and navigate
expo-routerfile routes under app/, <Link> routing, the stock entry point
SafeAreaProvider, useSafeAreaInsetsreal insets, which are zero on a desktop
initialWindowMetricsthe 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. TabsHost and TabsScreen ship 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:

  • NativeTabs is what create-expo-app now generates, and expo-router implements it for iOS and Android only -- it throws "You are using NativeTabs on an unsupported platform" anywhere else. A Stack works. This is expo-router's own platform gate, upstream of Basalt.
  • @/* path aliases come from tsconfig.json, and Expo installs tsconfig-path resolution in @expo/cli rather than in expo/metro-config. A config built on getDefaultConfig alone -- which is what basalt init writes -- does not get them, so the aliases have to be spelled out in metro.config.js as Metro resolveRequest entries.
  • expo-device, which the template's own index route imports, has no native module here. See Expo for how that list works.

On this page