Crate neon

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

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

Structs

• Exports
  Values exported with neon::export

Functions

• registered
  Access values exported with neon::export
• set_global_executornapi-6 and futures
  Register a Future executor runtime globally to the addon.

Attribute Macros

• export
  Register an item to be exported by the Neon addon
• main
  Marks a function as the main entry point for initialization in a Neon module.