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 nothingdirectory 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
cmakeandninjaare onPATH- and, for this machine's desktop only: GTK 4's development headers on
Linux, the macOS SDK and
clangon macOS,VCPKG_INSTALLATION_ROOTandclang-clon 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.
| option | default | |
|---|---|---|
--port <number> | 8081 | the port Metro is or should be on |
--mode <string> | dev | dev to run against Metro, release to run a bundle |
--no-packager | do not start Metro, and do not check for one | |
--build | build 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.js | where the release bundle is written and read |
--entry-file <path> | index.js | the app entry point |
Through an npm script, options need -- first:
npm run linux -- --build --jobs 8The 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 --buildA 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 bundle | a release bundle straight into Contents/Resources, so its assets, app.config.json and app.identity.json land beside it |
| the module | app.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 |
| libraries | every 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 |
| resources | whatever basalt.resources names, executable bits kept |
| the signature | inside 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.
| option | default | |
|---|---|---|
--build | build 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.js | the app entry point |
--sign <identity> | codesigning identity; else BASALT_SIGN_IDENTITY, else ad hoc | |
--out <path> | build/release | where 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| option | default |
|---|---|
--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 |
devServerPlatform | the first enabled | which one a dev-server request with no app= is assumed to be |
platformFallbacks | what 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.