backend Stable WINMACLNX

Call custom Rust functions from JavaScript. Use this for CPU-intensive work, native OS APIs, C library bindings, or anything that should not run in JS.

backend is a Proxy — any property access returns an async function that dispatches to a registered Rust command.

Import

import { backend } from 'veloxkit'

Registering commands in Rust

Commands are registered in your VeloxExtension::register_commands implementation:

impl VeloxExtension for MyExtension {
    fn register_commands(&self, cmds: &mut BackendRegistryBuilder) {
        cmds.add("greet", |args_json| async move {
            let v: serde_json::Value = serde_json::from_str(&args_json)?;
            let name = v["name"].as_str().unwrap_or("world");
            Ok(format!(r#""Hello, {}!""#, name))  // return valid JSON
        });
 
        cmds.add("sum", |args_json| async move {
            let v: serde_json::Value = serde_json::from_str(&args_json)?;
            let n = v["n"].as_u64().unwrap_or(0);
            let result: u64 = (0..=n).sum();
            Ok(serde_json::to_string(&result)?)
        });
    }
}

Commands receive a JSON string and must return a JSON string result.

Calling commands from JS

import { backend } from 'veloxkit'
 
const greeting = await backend.greet({ name: 'Alice' })
// 'Hello, Alice!'
 
const total = await backend.sum({ n: 1_000_000 })
// 500000500000

Arguments are JSON.stringify'd automatically. Results are JSON.parse'd automatically.

Calling an unregistered command rejects the Promise:

try {
  await backend.missing({})
} catch (e) {
  // 'Unknown backend command: missing'
}

Scaffold a command

velox generate command process_image

Creates src-velox/commands/process_image.rs with a template and prints the JS usage pattern.

Examples

Parse a large CSV without blocking the UI

cmds.add("parseCsv", |args_json| async move {
    let v: serde_json::Value = serde_json::from_str(&args_json)?;
    let path = v["path"].as_str().ok_or("missing path")?;
    let content = tokio::fs::read_to_string(path).await?;
    let rows: Vec<Vec<String>> = content
        .lines()
        .map(|l| l.split(',').map(String::from).collect())
        .collect();
    Ok(serde_json::to_string(&rows)?)
});

const rows = await backend.parseCsv({ path: '/data/large.csv' })
setTableData(rows)

Type-safe wrapper module

// src/commands.ts
import { backend } from 'veloxkit'
 
export async function greet(name: string): Promise<string> {
  return backend.greet({ name })
}
 
export async function parseCsv(path: string): Promise<string[][]> {
  return backend.parseCsv({ path })
}

backend requires a native project (velox create --native). JS-only projects use built-in APIs (db, fs, ai, etc.).

⚠️

For CPU-bound Rust commands, use spawn_blocking to avoid blocking the async executor:

cmds.add("crunch", |args| async move {
    let result = tokio::task::spawn_blocking(move || {
        expensive_computation()
    }).await??;
    Ok(serde_json::to_string(&result)?)
});

credentials crash