Runner Model

VeloxKit apps ship as a single binary that contains both the runtime and your application code. No separate installer, no runtime dependency, no "install Node.js first."

The binary trailer

When you run veloxkit package, the output is a self-contained executable:

veloxkit-runtime  [~18MB]
    +
your-app.blob     [your compiled app, typically 1–5MB]
    =
my-app            [single executable, ~20MB]

The runtime reads a 64-byte trailer appended to itself to find the app blob offset. This means:

1. The runtime binary is identical for every VeloxKit app
2. Your app is a blob appended to the end
3. The OS sees one file; users double-click one thing

V8 snapshot

A V8 snapshot is a serialized heap image. VeloxKit generates a snapshot at build time that includes:

• The VeloxKit runtime library
• React and the custom reconciler
• Your application code

At startup, V8 deserializes this heap directly into memory instead of parsing and compiling JavaScript. This is why cold startup is ~50ms rather than ~500ms.

The snapshot is generated once (veloxkit build) and included in the blob.

No Rust required

You never interact with Rust directly. The native bindings (file system, SQLite, GPU, etc.) are pre-compiled into the runtime binary. Your JavaScript calls them via the capability-gated bridge:

// JavaScript side — what you write
import { db } from 'veloxkit'
const rows = await db.query('SELECT * FROM notes')
 
// Rust side — what the runtime does (you never see this)
// velox_db::query(sql) → Vec<Row>

The bridge is typed end-to-end. TypeScript types for all native APIs are bundled with the veloxkit npm package.

Development vs production

The dev server trades startup time for instant reloads. Production builds restore full snapshot performance.