Basalt
Reference

CLI

Two kinds of command. basalt is a binary you run with npx, because before it runs Basalt is not a dependency yet and React Native's CLI has no config to read. The run commands are React Native CLI commands, registered by the host packages.

basalt

basalt <command> [directory]

  init     configure an app to build for the desktop
  doctor   report what a build needs, changing nothing

directory defaults to the working directory. The binary is basalt; the package is basalt-core, because the bare name was taken on npm and bin names are a separate namespace where it was not.

basalt init

npx basalt init [directory]

Configures an app that exists. Idempotent; running it twice is safe and says so. It writes package.json and metro.config.js; see what it changes.

Exits 1 if the directory is not an app it recognises, or if any step needs doing by hand. 0 otherwise, including when there was nothing to do.

basalt doctor

npx basalt doctor [directory]

init with its hands behind its back, the same steps, reported the same way, writing nothing: plus the checks init has no fix for, which are the expensive ones:

  • every host package the app asked for is actually installed
  • the installed React Native is one Basalt supports
  • cmake and ninja are on PATH
  • and, for this machine's desktop only: GTK 4's development headers on Linux, the macOS SDK and clang on macOS, VCPKG_INSTALLATION_ROOT and clang-cl on Windows

It will not claim a desktop it cannot see. Whether GTK's headers are installed is not a question a Mac can answer, so those report as ? with the reason rather than as passing.

Exits 1 when something is blocked, 0 otherwise. A step init would change is not a failure: an app that has never been configured is not a broken machine.

Step markers

=already right
+this run changed it, or init would
!somebody has to do this
?could not be asked from here

react-native run-linux, run-macos, run-windows

Each comes from its host package, basalt-gtk, basalt-appkit, basalt-win32, so an app sees only the commands it could have used. init adds an npm script per desktop, so npm run linux is the same thing.

Builds nothing by default and runs your app against a packager. Pass --build for a first run, or after changing native code.

optiondefault
--port <number>8081the port Metro is or should be on
--mode <string>devdev to run against Metro, release to run a bundle
--no-packagerdo not start Metro, and do not check for one
--buildbuild the host before running it, into .basalt/build
--jobs <number>parallelism for --build
--host-binary <path>the host executable to run, if it is not somewhere obvious
--module <string>the AppRegistry name to start, if it is not app.json's
--bundle <path>build/main.jsbundle.jswhere the release bundle is written and read
--entry-file <path>index.jsthe app entry point

Through an npm script, options need -- first:

npm run linux -- --build --jobs 8

The host binaries are basalt_gtk, basalt_appkit and basalt_win32. That is what shows in ps and in a crash report, rather than your app's name, which is deliberate.

react-native package-macos

A .app that runs on a Mac other than the one that built it, and is not launched. From basalt-appkit, so an app that does not target macOS never sees the command.

npx react-native package-macos --build

A development run already builds a .app, because NSBundle.mainBundle comes from where the executable sits rather than from how it was launched, and notifications, the Dock icon and the menu bar name all need a bundle. What that one lacks is everything that makes it somebody else's:

  • Its libraries. The host links Hermes and jsi through rpaths into this machine's .basalt/build, and glog, gflags, fmt, double-conversion, boost_regex, OpenSSL and three ICU libraries by absolute Homebrew path. Eleven libraries another Mac has not got, so it dies in dyld before a line of JavaScript runs.
  • Its bundle. A development host is pointed at Metro, or at a bundle path relative to the working directory, which is not something Finder sets.
  • A signature Gatekeeper accepts. Ad hoc is refused for anything downloaded.

So those are what this does, and it does nothing about running:

the bundlea release bundle straight into Contents/Resources, so its assets, app.config.json and app.identity.json land beside it
the moduleapp.identity.json records the AppRegistry name, and a host launched with no arguments at all, which is how Finder starts one, runs Resources/main.jsbundle.js with it
librariesevery non-system dylib the executable reaches, transitively, copied into Contents/Frameworks and referenced as @rpath/<name>, with the build directory rpaths replaced by @executable_path/../Frameworks
resourceswhatever basalt.resources names, executable bits kept
the signatureinside out: each Mach-O under Frameworks and Resources, then the app itself

The icon is not in that list because it is not a release step: basalt.icon becomes Resources/AppIcon.icns on every run, so a development app has it too.

The .app is rebuilt from nothing each time. A leftover file from an older run inside a signed bundle is the kind of thing nobody finds until after it ships.

optiondefault
--buildbuild the host first, into .basalt/build
--jobs <number>parallelism for --build
--host-binary <path>the basalt_appkit to package, if it is not somewhere obvious
--module <string>the AppRegistry name, if it is not app.json's
--entry-file <path>index.jsthe app entry point
--sign <identity>codesigning identity; else BASALT_SIGN_IDENTITY, else ad hoc
--out <path>build/releasewhere the app goes

Signing, and the step this does not take

Without --sign the app is signed ad hoc, which is enough to run it here and not enough to give it to anybody.

npx react-native package-macos --build \
  --sign "Developer ID Application: Your Name (TEAMID)"

A Developer ID adds the hardened runtime and a secure timestamp, both of which notarization requires, and signs basalt.entitlements into every executable in the bundle.

Notarization is yours. With a Developer ID signature Gatekeeper's answer is "Unnotarized Developer ID", and notarytool plus a DMG or a zip to staple it to are the remaining steps. Basalt takes neither.

A release host is built twice over

--build configures this one with CMAKE_BUILD_TYPE=Release into .basalt/build-release/macos, beside the unoptimised .basalt/build/macos a development run uses, and package-macos looks for the optimised one first. Two directories rather than one, because reconfiguring a single tree would make the next run-macos pay for a full rebuild. Hermes is not rebuilt either way: it is in third_party and already Release.

Linux and Windows have no package- command

basalt-gtk and basalt-win32 register run-linux and run-windows and nothing else, so there is no package-linux or package-windows to run.

What each one already does on every run is the identity half, which is what a notification and a switcher entry need: Linux gets a .desktop file written beside the build, naming the app, its icon, its StartupWMClass and its URL schemes, and on Windows the host registers its own AppUserModelID and Start Menu shortcut in C++, because a shortcut carrying that property means COM.

What neither has is the distribution half: the transitive dependency walk that embeds libraries, which is otool and install_name_tool and has no counterpart written for either; a real signature, which is signtool on Windows; an icon in the delivered app at all; and the container people expect to download, an AppImage or a Flatpak on Linux and an installer or MSIX on Windows. Tracked in docs/backlog/ecosystem.md.

basalt-bundle

For apps that cannot use React Native's CLI. An Expo app has expo as its CLI, which does not know this platform, and Metro's own build emits no assets. This is the missing command: one bundle, its assets beside it, ready for the host to load.

npx basalt-bundle --platform linux --bundle-output build/main.jsbundle.js
optiondefault
--platform <name>linux
--project-root <path>the working directory
--entry-file <path>index.js
--bundle-output <path>
--assets-dest <path>
--config <path>
--dev <bool>false
--minify <bool>

--dev false is the default on purpose: a development bundle on disk is not a development mode and the host will not load one.

Metro configuration

const {withDesktopPlatforms} = require('basalt-core/metro-config');

module.exports = withDesktopPlatforms(config, options);

init writes this for you. options is optional:

default
platforms['linux', 'macos', 'windows']which desktops to enable
devServerPlatformthe first enabledwhich one a dev-server request with no app= is assumed to be
platformFallbackswhat to fall back to for a module with no desktop implementation

The wrapper adds the platforms to Metro's resolver, redirects React Native's self-importing deep-import shims to their Android siblings: these platforms report PlatformConstants from C++ and drive the same components Android's JavaScript drives, so Android's implementation is the one that matches what is actually implemented, and adds its own directory to watchFolders, because Metro will not read a file it is not watching and this package hands it files.

On this page