Introduction

#What is NativeRuntime?

NativeRuntime combines three things that have existed separately for years but never been assembled cleanly: QuickJS (Fabrice Bellard's small, fast, MIT-licensed JavaScript engine), a repeatable adapter pattern for connecting that engine to any native library written in C, C++, or Rust, and a build tool that produces a single native binary for every major target platform.

It is not a framework. There is no large runtime library you depend on, no bridge between your JavaScript and the native libraries you use, no marshalling layer with serialization overhead. The JavaScript is interpreted by QuickJS embedded directly in your binary; the adapters expose native functions to JavaScript through QuickJS's lightweight object-binding model. The resulting binary contains exactly the JavaScript you wrote, exactly the adapters you used, and nothing else.

Typical binaries are 2–4 MB, compared to 30 MB+ for Electron-class projects. Startup is immediate. The attack surface is whatever you imported.

#Why does this exist?

Developers who want to ship cross-platform applications have generally had three unsatisfying options. Electron embeds an entire web browser inside every app — accurate to platform conventions in name only, hugely expensive in memory and disk footprint. React Native and similar bridge-based frameworks marshall data between a JavaScript world and a native world, paying a per-call serialization tax and inheriting the constraints of both ecosystems. Native development in C, C++, Rust, or Swift works well but requires writing the same business logic three or four times for each platform, in languages with much smaller developer populations than JavaScript.

NativeRuntime takes a different approach: keep JavaScript as the language developers write applications in, but compile it into a native binary using QuickJS as the engine, with adapters bridging to platform-native libraries. The JavaScript developer can use any C, C++, or Rust library — through an adapter — without ever writing a line of those languages. The native developer can keep using the toolkits they trust without rewriting application logic.

This combination has been technically possible for years. Bellard released QuickJS in 2017. Native UI toolkits, database libraries, and graphics engines have existed for decades. What was missing was the assembly: a clean adapter pattern, a build tool that handles cross-platform output, and a small set of reference adapters that prove the approach works in practice. That is what NativeRuntime contributes.

#The five-second mental model

If you remember nothing else about NativeRuntime, remember this:

• Your application logic is JavaScript, executed by QuickJS embedded in the binary.
• Each capability you need (UI, database, networking, 3D, audio, whatever) is an adapter — a small layer of C or C++ that exposes a native library to JavaScript.
• The build tool takes your JavaScript plus the adapters you chose plus the QuickJS engine, and emits a single native binary per target platform.

That's the whole architecture. Everything else in these docs is detail about how each of those three pieces works, the conventions for writing adapters, and the reference implementations you can use today.

#Where to go from here

If you want to see NativeRuntime working in 15 minutes, follow the Quickstart — install the CLI, scaffold a hello-world project, run nr build, and run the resulting binary.

If you want to understand the architecture before writing code, read The adapter pattern next. It walks through how a JavaScript function call reaches a C library function, and why this approach has near-zero overhead compared to bridge-based runtimes.

If you want to write an adapter — wrap a library you care about so JavaScript can drive it — start with Writing your first adapter. The pattern is small enough that you can usually have a working binding in an afternoon.