redjs
JavaScriptCore for native apps.
redjs embeds Bun's build of JavaScriptCore in Rust, with a C ABI and C# bindings for .NET 10. Run JavaScript, expose native functions, and give your scripts familiar web APIs without opening a browser.
use ;
What you get
- JavaScript with JIT. Evaluate scripts, call functions, and read exceptions with their JavaScript stacks.
- Native integration. Host functions and objects, promises, typed arrays, and zero-copy buffers over host memory.
- Useful web APIs. Timers, events, URLs, fetch, WebSocket, streams, crypto, and more. The host drives the event loop.
- Optional extras. Web Audio, Canvas 2D, IndexedDB, and WebGPU.
Build targets are Windows x64, Linux x64 (glibc), and macOS x64 / Apple Silicon. Each uses a verified prebuilt from the same JavaScriptCore revision. The engine's internal headers are version-sensitive, so upgrades need testing.
Build and try it
On Windows, you'll need Rust 1.97.1 with the MSVC target, LLVM's clang-cl on PATH,
Visual Studio C++ Build Tools (MSVC 14.44 or newer, plus the Windows SDK),
and PowerShell.
From this repository's root:
./setup.ps1
cd redjs
cargo run --release --no-default-features --example mini
setup.ps1 downloads and verifies the native dependencies; allow roughly a
gigabyte for the unpacked JavaScriptCore build. The mini probe creates a VM,
evaluates a few expressions, and prints each step.
Versions and hashes live in redjs/pins.txt. Run setup.ps1 again after
a pin change. To use a prebuilt stored elsewhere, set BUN_WEBKIT_DIR; the
build checks it against the same pin.
Without a setup run (a crate from crates.io, for one), the build script fetches
the same pinned inputs itself, checks the same hashes, and keeps them in a shared
cache: REDJS_CACHE_DIR, else redjs under %LOCALAPPDATA%, ~/Library/Caches
or $XDG_CACHE_HOME (~/.cache). REDJS_PROXY or HTTPS_PROXY sets a proxy;
with CARGO_NET_OFFLINE set it fails instead of downloading. Debug builds on Windows link JavaScriptCore
and WTF without their debug info; REDJS_WEBKIT_DEBUG_INFO=1 keeps it, for
stepping through engine source.
Back in the repository root, run ./build.ps1 -Test to build
the library, run the Rust suite, and stage the DLL and static library under
runtimes/ and lib/.
Linux and macOS
Use Rust 1.97.1 and Bun 1.4.4. On Linux, install Clang 20, curl, unzip, pkg-config and OpenSSL headers; Web Audio additionally needs ALSA development headers:
On macOS, install Xcode command-line tools (xcode-select --install); the
macOS 26 SDK / Xcode 26 toolchain supplies the C++23 compiler and standard
library. The pinned engine requires macOS 13+ at runtime. Both Intel and Apple
Silicon use their native architecture. For direct Cargo commands, set
MACOSX_DEPLOYMENT_TARGET=13.0 (the build script and CI already do this).
# Additional web APIs, including persistent IndexedDB and HTTP/2:
setup.sh verifies archive SHA-256 and extracted source-tree pins. Unix
JavaScriptCore libraries live in prebuilt/bun-webkit-linux-amd64,
prebuilt/bun-webkit-macos-amd64, or prebuilt/bun-webkit-macos-arm64.
The upstream Unix archives omit the portable frontend AOT table sources;
setup obtains those from the verified Windows archive at the same engine
pin and checks that the generated ABI headers match before using them.
It copies sources only. Unix engine bindings already present in the native
archive are not compiled twice.
build.sh stages libredjs.a under lib/{linux-x64,osx-x64,osx-arm64}.
On macOS it also stages libredjs.dylib under runtimes/{rid}/native for
the C# library resolver. The upstream Linux archive uses executable-only TLS
relocations, so this port supports Rust, static C linking, and C# NativeAOT
on Linux. Building a Linux .so requires a separately built PIC engine;
build.sh --shared can use one supplied through BUN_WEBKIT_DIR.
cargo build emits Rust/static libraries; the build scripts explicitly request
shared libraries on Windows and macOS. After building the native library:
# macOS (shared library):
# Select linux-x64, osx-x64, or osx-arm64 for a .NET NativeAOT smoke build:
GitHub Actions runs core and web-feature Rust suites on standard Linux and macOS runners, plus C# NativeAOT smoke tests (and shared-library smoke tests on macOS). WebGPU's real-device tests require a GPU, so the hosted test matrix does not enable them.
Use it in your app
Rust: start with Context and Value. Disable default
features if you only need the engine and core web APIs. Your host's Cargo
configuration must also use the static CRT settings in
redjs/.cargo/config.toml on Windows.
Declare raw JSC host callbacks with #[redjs::host_fn] unsafe fn ...; the
attribute selects SysV on Windows x64 and the native C ABI on Unix, including
Apple Silicon. Existing function_sysv / redjs_function_create_sysv names
retain their ABI and accept this platform-correct callback.
C#: reference csharp/RedJs and build the native library first. The basic API looks like this:
using RedJs;
var js = JsContext.Create();
Console.WriteLine(js.Eval("6 * 7").AsNumber); // 42
The C# smoke project includes both DLL
loading and static linking for .NET NativeAOT. NativeAOT here compiles the
.NET host; JavaScript still uses JSC's normal execution path. Compiling
JavaScript to native images is a separate, experimental
native-aot feature.
Other languages: the redjs_* C ABI exposes the same
engine operations, with per-function documentation in the source.
Web APIs and the event loop
A fresh context starts with the JavaScript language globals. To add the web layer:
- Call
redjs_web_installfor timers, animation frames, andperformance. - Call
redjs_webshim_installfor the web APIs, passing your scripts and assets roots. - Call
redjs_pump(ctx, 7, stats)regularly on the VM thread to process timers, animation frames, async completions, and microtasks.statscan be null.
In C#, these are InstallWebGlobals(),
InstallWebShims(scriptsRoot, assetsRoot), and Pump().
A render loop can pump once per frame.
The default Cargo features include audio, indexeddb, svg-images and
canvas. WebGPU is the separate redjs-webgpu crate (redjs/webgpu): call
redjs_webgpu::register() before installing the web shims. Native GPU
acquisition is lazy; see the WebGPU support notes. Use
--no-default-features for a smaller starting point, then enable what you need.
Some additions are opt-in:
| Feature | Adds |
|---|---|
storages |
localStorage and sessionStorage, with host hooks for persistence |
clipboard |
navigator.clipboard, backed by the host's clipboard |
battery |
navigator.getBattery() and BatteryManager, with native Windows, Linux, and macOS power notifications |
indexeddb-sqlite |
Persistent IndexedDB when the host supplies its storage configuration |
net-h2 |
Pooled HTTP/1.1 and HTTP/2 for fetch |
audio-codecs-extra |
More audio formats, including AAC-LC and ALAC |
icu-root |
Links only ICU's root locale (about 3 MB instead of 12) on Windows and Linux; hand the full icudt79l.dat, which the build writes beside your binaries, to icu::set_common_data before the first context to get every locale back |
The optional Battery Status API caches one
Promise and one BatteryManager per context. Its read-only charging,
chargingTime, dischargingTime, and level attributes support the four
standard change events through addEventListener and on…change handlers.
Subscriptions start on the first getBattery() call; the existing pump
delivers changes without battery polling. Windows uses power-setting
notifications and cannot provide a charging-time estimate (Infinity until
full). Linux uses UPower's aggregate display device on the system D-Bus,
including daemon restart notifications. macOS uses IOPowerSources and a
sleeping Core Foundation run loop; its charge estimates are converted from
minutes to seconds. Linux/macOS acquisition runs on a cancellable native
worker, and the initial Promise resolves only after its first snapshot is
pumped. Native callbacks publish no JavaScript values, and cleanup never
joins a worker on the JS thread. No battery, unavailable status / services,
and unsupported platforms use the specification's defaults (true, 0,
Infinity, 1). Linux requires the UPower system service; a lost bus
connection falls back to defaults for that subscription. The native web
installer provides a Window-like application context; there is no Worker installer or Document permissions-policy model.
The feature is off by default in redjs and the generic SDK host; Argon enables
it by default. SDK consumers opt in with sk-app/battery (forwarded through
sk-runtime/battery); building Argon with --no-default-features omits it.
These APIs cover parts of the web platform. DOM, rendering, permissions, and OS integration depend on what the host provides. The web API modules document individual behavior and limits.
A few things to know
- Keep contexts for the process lifetime. The current prebuilt has a
known crash during VM teardown. C# deliberately has no
Disposefor a context. - Use one thread per context. Pump on that same thread. Separate contexts have separate VMs; values cannot be passed directly between them.
- Protect values you keep. A value stored in a field or collection needs
protect/unprotect(Protect/Unprotectin C#). Copying aValuedoes not keep the JavaScript object alive. - Bundle your scripts. Evaluation runs classic scripts; there is no module
loader, dynamic
import(), or remote inspector yet.
Benchmarks
The C# benchmark suite compares redjs with ClearScript/V8, Jint, YantraJS, Jurassic, and NiL.JS using BenchmarkDotNet. It covers script execution, calls in both directions, allocations, and first use. The redjs modes comparison covers warmed JIT, cached bytecode with JIT on or off, and native JavaScript AOT images. See the recorded comparison for results and the conditions they were measured under.
Going further
- Rust examples — audio, spatial sound, WebGPU, and engine probes.
- Rust conformance suite and C# smoke tests — working examples of the embedding API.
- IndexedDB web-platform-tests — how to run the compatibility suite.
- Native image probes and AOT memory profiles — the experimental JavaScript AOT path.
Releases
redjs, redjs-macros and redjs-webgpu are published from this repository on their own version line, not Skathi's, and always together at one version. The version is semver for this code: a breaking change to the Rust API, the C ABI or a feature's default bumps the minor version (0.3 to 0.4), anything else the patch version. Skathi requires a compatible version next to its path dependency on this checkout, and its release stops while that version is not on crates.io, or while its checkout has changes made since that version was published.
To release:
- Set
versioninredjs/Cargo.toml,redjs/macros/Cargo.tomlandredjs/webgpu/Cargo.toml, and theversionof the dependencies between them, and commit. bun scripts/publish-crates.ts --tag v<version> --dry-runpackages and verifies the three crates.- Push the tag
v<version>:.github/workflows/release.ymlpublishes them in dependency order. A re-run goes on where the last one stopped. - In Skathi, raise the
versionof itsredjsandredjs-webgpudependencies to this one.
License
redjs is licensed under either of Apache License 2.0 or MIT, at your option.
It links JavaScriptCore, WTF and bmalloc from Bun's WebKit build, statically by default. Parts of
JavaScriptCore and WTF are licensed under the GNU LGPL 2; the rest of WebKit is BSD. To meet the
LGPL, the patched WebKit source is public at oven-sh/WebKit:
the exact commit is webkit.version in redjs/pins.txt. To relink redjs, or a program built
on it, against a modified JavaScriptCore: build that commit, point BUN_WEBKIT_DIR at the result
and rebuild (build.ps1 / build.sh). On Windows, REDJS_ENGINE_DLL=redjs.dll puts the engine in
a DLL of its own that can be replaced without relinking the program.
Also linked: ICU (Unicode License V3), mimalloc (MIT) and, with the indexeddb-sqlite feature,
SQLite3MultipleCiphers (MIT; SQLite is public domain).