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.
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.