Crate neon

source ·
Expand description

The Neon crate provides bindings for writing Node.js addons (i.e., dynamically-loaded binary modules) with a safe and fast Rust API.

§Getting Started

You can conveniently bootstrap a new Neon project with the Neon project generator. You don’t need to install anything special on your machine as long as you have a supported version of Node and Rust on your system.

To start a new project, open a terminal in the directory where you would like to place the project, and run at the command prompt:

% npm init neon my-project
... answer the user prompts ...
✨ Created Neon project `my-project`. Happy 🦀 hacking! ✨

where my-project can be any name you like for the project. This will run the Neon project generator, prompting you with a few questions and placing a simple but working Neon project in a subdirectory called my-project (or whatever name you chose).

You can then install and build the project by changing into the project directory and running the standard Node installation command:

% cd my-project
% npm install
% node
> require(".").hello()
'hello node'

You can look in the project’s generated README.md for more details on the project structure.

§Example

The generated src/lib.rs contains a function annotated with the #[neon::main] attribute, marking it as the module’s main entry point to be executed when the module is loaded. This function can have any name but is conventionally called main:

#[neon::main]
fn main(mut cx: ModuleContext) -> NeonResult<()> {
    cx.export_function("hello", hello)?;
    Ok(())
}

The example code generated by npm init neon exports a single function via ModuleContext::export_function. The hello function is defined just above main in src/lib.rs:

fn hello(mut cx: FunctionContext) -> JsResult<JsString> {
    Ok(cx.string("hello node"))
}

The hello function takes a FunctionContext and returns a JavaScript string. Because all Neon functions can potentially throw a JavaScript exception, the return type is wrapped in a JsResult.

Modules§

  • Provides runtime access to the JavaScript engine.
  • Exposes the JavaScript event loop for scheduling asynchronous events.
  • References to garbage-collected JavaScript values.
  • Metadata about the Neon version and build.
  • Traits for working with JavaScript objects.
  • Convenience module for the most common Neon imports.
  • Exposes JavaScript’s reflection API to Rust.
  • Represents JavaScript exceptions as a Rust Result type.
  • syssys
    Raw bindings to Node-API
  • Thread-local storage for JavaScript threads.
  • Representations of JavaScript’s core builtin types.

Attribute Macros§

  • Marks a function as the main entry point for initialization in a Neon module.