Basalt

Getting started

Getting started

Basalt adds a desktop to a React Native app that already exists. It does not create one: create-expo-app does that, and the division is deliberate: this is a platform you add, not a way to start a project.

Which React Native

This is decided when the app is created rather than when Basalt is added, and it is the one choice worth making deliberately.

0.88 is the one to be on. It is what CI pins, it is what every host is built and tested against, and it has Fast Refresh. react-native@latest is 0.88.1 today, so an app created from React Native's own template is already there.

An Expo app gets it from its SDK. SDK 58 installs React Native 0.88.1, which is the version every release builds an Expo app against end to end. SDK 57 installs 0.86.3, which Basalt also supports and which has no Fast Refresh: a reload collapses the host, from a bug in React Native's own teardown that upstream fixed in 0.87 by deleting three lines. Everything else works; you restart to see a change.

So: on 0.86, expect to restart the app after an edit. On 0.87 or 0.88, do not.

Before you start

Install the toolchain for the desktop you are building on. You only need the one you are building for; the build configures the host for the platform it is running on and ignores the others.

React Native's C++ does not vendor its dependencies, so the build links against your system's glog, Boost, fmt, double-conversion and OpenSSL. They are the bulk of each list below, and they are the same libraries on all three desktops.

sudo apt install build-essential clang cmake ninja-build pkg-config \
  libgtk-4-dev libpango1.0-dev libglib2.0-dev \
  libgoogle-glog-dev libboost-dev libboost-regex-dev libfmt-dev \
  libdouble-conversion-dev libgflags-dev libssl-dev libcurl4-openssl-dev

GTK 4's development headers draw the window; pkg-config --exists gtk4 is the check doctor runs. clang rather than gcc because React Native builds -Werror and is a clang codebase -- docs/DECISIONS.md has the detail.

Check before you build

npx basalt-core doctor asks all of these questions in seconds and changes nothing. A first build compiles Hermes and React Native's C++ from source and takes tens of minutes, and without this every missing prerequisite surfaces as a CMake error twenty minutes in.

Configure the app

From the root of your app:

npx basalt-core init

It is idempotent, and it reports every step as one of four things:

  = dependencies     dependencies are already present
  + scripts          added scripts: linux, macos, windows
  + metro config     wrote metro.config.js, on expo/metro-config
  ! desktops         app.json's "basalt.desktops" names bsd, which is not a
                     desktop this platform has. Expected any of linux, macos,
                     windows; using all of them

= already right, + changed by this run, ! needs you, ? could not be asked from here. An app it cannot recognise is refused before anything is written; a half-configured app fails later and further from the cause.

What it changes

  • package.json gains basalt-core and a host package per desktop as dependencies, at the same version because they share a C++ ABI with the host. It also adds @react-native/metro-config and @react-native-community/cli as dev dependencies, which an Expo app does not have because expo is its CLI.
  • scripts gains linux, macos and windows, each running react-native run-<platform>. Any script you already defined is left alone.
  • metro.config.js is wrapped in withDesktopPlatforms, or written if you have none, which is what a stock Expo app looks like. It starts from expo/metro-config in an Expo app and React Native's own otherwise.

All three desktops are configured by default, because package.json is committed: which desktops an app builds for is a property of the project, not of whoever happened to run the command. Narrow it in app.json if you want fewer. The cost of the others is source that is never compiled.

Then install, and run:

npm install
npm run linux     # or macos, or windows

Building

The run command does not build by default: it starts your app against a Metro packager, which is what you want on the second and every later run. Pass --build for the first one:

npm run linux -- --build

The build lands in .basalt/build. Add --jobs to control parallelism.

The binary is turned into a real application on every run, not only for release: on macOS NSBundle.mainBundle is derived from where the executable sits, so a host run straight out of a build directory has no bundle identifier and cannot post a notification, while the same code inside a .app can. Packaging only for release would mean a feature that works in production and not in development.

Release

npm run linux -- --mode release --build

release runs a production bundle from disk instead of connecting to Metro. A --dev bundle is not a development mode and will not load.

Supported React Native versions

React NativeSupportedFast RefreshWhat it is
0.88tested on 0.88.1WorksYesWhat Expo SDK 58 installs, and what CI builds and tests every change against.
0.87tested on 0.87.1WorksYesWhat CI built and tested every change against until 0.88.
0.86tested on 0.86.3WorksNoWhat a current Expo app installs, which is why it is supported.
0.83 - 0.85UntestedNever built or tested. Nothing suggests they would not work; nothing has checked.
0.82 and olderNoTried, and stopped deliberately. It needs a second way of constructing the host and a websocket client React Native does not ship there.

This table is packages/basalt-core/supported-versions.json, rendered. That file is what bootstrap.sh reads before it downloads anything and what doctor checks your app against, so what you are reading cannot drift from what the build enforces. A version on it has been built against and had both suites run; one that is not on it fails the build with a message naming the file, rather than being allowed and failing later somewhere stranger.

The 0.86 limitation is specific: a reload leaves the host without a mounting manager and it collapses. That was root-caused here and fixed upstream in 0.87 by deleting three lines. Everything else on 0.86 works, and you restart the app to see a change.

doctor checks the installed version and reports rather than refuses.

Hermes is pinned alongside React Native rather than derived from it, because Basalt builds it from source: Meta publishes a prebuilt Hermes for Windows, macOS, iOS and Android, and none for Linux. That single difference is where every version problem here comes from.

Packages

packagewhat it is
basalt-corethe platform, the CLI and the shared C++
basalt-gtkthe Linux host, and the run-linux command
basalt-appkitthe macOS host, and run-macos
basalt-win32the Windows host, and run-windows
basalt-navigationnative screens for react-navigation; see Navigation
basalt-skiareact-native-skia's module, platform context and <Canvas>
basalt-subprocessrunning a command and watching its output
basalt-notificationsdesktop notifications

basalt-core and one host package is the minimum. The other four are optional and each one is a dependency an app adds when it wants that thing; see Libraries for what works with what.

Each host package carries its own run command, because React Native's CLI reads a react-native.config.js out of every dependency. An app with only basalt-appkit installed never sees a command it could not have used, and an app that installed basalt-core alone has no desktop commands at all.

If something goes wrong

run-linux is not a command. The host package is not installed. Run your package manager, or npx basalt-core init if it was never a dependency.

Metro cannot find a module, or fails on @babel/runtime. Usually a linked checkout or a monorepo, where Metro resolves Basalt's files by their real path and then looks for dependencies from there. withDesktopPlatforms names the project's node_modules explicitly to cover this, so check your Metro config is actually wrapped, doctor reports that.

The build fails naming a path, deep in CMake. Run npx basalt-core doctor. It encodes the same prerequisite list the build needs and CI installs.

On this page