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.
Representations of JavaScript’s core builtin types.
Attribute Macros
Marks a function as the main entry point for initialization in a Neon module.