Neon Docs

Appearance

Introduction to Neon ​

Fresh 🌱

Neon is a library and toolchain for embedding Rust in your Node.js apps and libraries.

Why Neon? ​

With Neon, you can create native Node modules like you might in C or C++, but without the headaches and anxiety of unsafe systems programming. Embedding Rust in Node is useful for several reasons:

  • Raw performance - run hot paths in compiled, optimized Rust.
  • Threads and parallel programming - use real OS threads and Rust's fearless concurrency.
  • Access to Rust's package ecosystem - pull any crate from the Rust registry.
  • Access to native, OS-specific libraries - bind to system APIs that have no npm equivalent.

Neon also works hard to make creating native modules easy, with a convenient command-line interface and a workflow built around sensible project conventions. That eliminates much of the usual hassle of building native Node addons.

The core mental model ​

flowchart LR
    JS[JavaScript caller] -->|calls| FN["Neon function (Rust body)"]
    FN -->|receives| CX["Context (cx)"]
    CX -->|read| ARGS[Arguments + this]
    CX -->|build| VALS["JS values (number, string, object...)"]
    FN -->|returns| RES["JsResult: Ok value or thrown error"]
    RES --> JS
    style FN fill:#10b981,color:#fff
    style CX fill:#6366f1,color:#fff

A Neon function looks and acts like a normal JavaScript function, but its behavior is written in Rust. Every Neon function receives a context (cx) - your handle to the JavaScript runtime. Through cx you:

  • read the call's arguments and its this,
  • construct JavaScript values (numbers, strings, objects, arrays, ...),
  • and ultimately return a result.

The return type is almost always a JsResult<T>, a Rust Result that is either Ok(value) or Err(thrown_exception).

What a project looks like ​

A Neon project is both a Node package and a Rust crate at the same time:

text
my-module/
├── Cargo.toml      # Rust crate manifest
├── package.json    # npm package manifest
└── src/
    └── lib.rs      # Rust source - your Neon functions

The Rust side compiles to a single binary, index.node, which Node loads with require('.').

Where to start ​

  1. Install the toolchain - get Node and Rust ready.
  2. Hello, World! - write and run your first module.
  3. Then explore values: Primitive Types, Objects, Functions.

Reference vs. guide

This site is a working SOP reference. For exhaustive type-by-type API signatures, the API Map points you to the right module in the neon crate.