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-devGTK 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 initIt 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.jsongainsbasalt-coreand 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-configand@react-native-community/clias dev dependencies, which an Expo app does not have becauseexpois its CLI.scriptsgainslinux,macosandwindows, each runningreact-native run-<platform>. Any script you already defined is left alone.metro.config.jsis wrapped inwithDesktopPlatforms, or written if you have none, which is what a stock Expo app looks like. It starts fromexpo/metro-configin 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 windowsBuilding
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 -- --buildThe 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 --buildrelease 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 Native | Supported | Fast Refresh | What it is |
|---|---|---|---|
| 0.88tested on 0.88.1 | Works | Yes | What Expo SDK 58 installs, and what CI builds and tests every change against. |
| 0.87tested on 0.87.1 | Works | Yes | What CI built and tested every change against until 0.88. |
| 0.86tested on 0.86.3 | Works | No | What a current Expo app installs, which is why it is supported. |
| 0.83 - 0.85 | Untested | Never built or tested. Nothing suggests they would not work; nothing has checked. | |
| 0.82 and older | No | Tried, 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
| package | what it is |
|---|---|
basalt-core | the platform, the CLI and the shared C++ |
basalt-gtk | the Linux host, and the run-linux command |
basalt-appkit | the macOS host, and run-macos |
basalt-win32 | the Windows host, and run-windows |
basalt-navigation | native screens for react-navigation; see Navigation |
basalt-skia | react-native-skia's module, platform context and <Canvas> |
basalt-subprocess | running a command and watching its output |
basalt-notifications | desktop 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.