A practical SOP reference for embedding Rust in Node.js. Setup, exporting functions, async tasks, boxed data, and shipping to npm - without the C/C++ headaches.
This is a self-contained operating reference for Neon - the library and toolchain for writing native Node.js addons in Rust. It is organized for getting things done:
| Section | Use it when you want to... |
|---|---|
| SOPs | Follow a step-by-step procedure: install, scaffold a module, export functions, ship to npm. |
| Guides | Understand a concept: primitive types, objects, arrays, async, error handling, JsBox. |
| Workflows | See an end-to-end pattern with a diagram: module load order, async data flow, the publish pipeline. |
| Quick Reference | Look something up fast: CLI commands, cx methods, the JS↔Rust type table, fixes for common errors. |
| API Map | Find the right module in the neon crate (context, types, event, result, object, thread). |
Mental model
A Neon function is a normal JavaScript function whose body is written in Rust. You receive a context (cx) that is your handle to the JS runtime: you use it to read arguments, build JS values, and return results. Everything else builds on that.
use neon::prelude::*;
// A Rust function that JavaScript will see as `hello()`
fn hello(mut cx: FunctionContext) -> JsResult<JsString> {
Ok(cx.string("hello node"))
}
// Wire it into the module's exports
#[neon::main]
fn main(mut cx: ModuleContext) -> NeonResult<()> {
cx.export_function("hello", hello)?;
Ok(())
}// In JavaScript, after `npm run build`
const { hello } = require('.');
console.log(hello()); // "hello node"Start with the Install Toolchain SOP, then build your first real module in Hello, World!.