Neon Documentation

Install the cargo-cp-artifact command line utility globally using npm.

npm install -g cargo-cp-artifact

Neon 0.10 introduces two layers for function interaction:

1. Low-level API: .call() and .construct() are now primitives that do not automatically downcast arguments or results. They accept arrays of handles.
2. High-level API: .call_with() and .construct_with() provide a convenient builder pattern for method chaining and automatic argument handling.

Use the high-level API for cleaner, more idi-omatic code.

// High-level API: Calling a function
f.call_with(&cx)
 .args((cx.string("hello"), cx.number(42)))
 .apply(&mut cx)

// High-level API: Constructing (new) a function
f.construct_with(&cx)
 .args((s, n))
 .apply(&mut cx)

// Low-level API: Calling a function
f.call(&mut cx, this, [s.upcast(), n.upcast()])

// Low-level API: Constructing a function
f.construct(&mut cx, [s.upcast(), n.upcast()])

In Neon 1.0.0, many previously unstable features (like try-catch-api or channel-api) have been stabilized and their feature flags removed. You should remove these from your Cargo.toml.

Only the following feature flags remain:

• napi-N: Specifies the Node-API version.
• futures: Provides compatibility between Rust Future and JavaScript Promise.

To start a new project using Neon, use the create-neon utility via npm init. Ensure you have installed the required platform dependencies before running this command.

$ npm init neon@latest my-project

Neon 0.10 replaces the old JsArrayBuffer API with idiomatic JsTypedArray<T> types. This allows you to access the underlying data as Rust slices directly via .as_slice() or .as_mut_slice().

To cast between different buffer types (e.g., from u8 to f32), use a crate like bytemuck instead of the deprecated Neon casting methods.

// Reading a buffer
let b: Handle<JsTypedArray<u32>> = ...;
let slice = b.as_slice(&cx);

// Reading and writing buffers
let src_buf: Handle<JsTypedArray<u32>> = ...;
let dst_buf: Handle<JsTypedArray<u32>> = ...;
{
    let lock = cx.lock();
    let src = src_buf.as_slice(&lock).unwrap();
    let dst = dst_buf.as_mut_slice(&lock).unwrap();
}

// Casting buffer types using bytemuck
use bytemuck::cast_slice;
let b: Handle<JsTypedArray<u8>> = ...;
let u8_slice = b.as_slice(&cx);
let f32_slice: &[f32] = cast_slice(u8_slice);

To migrate to the N-API backend, follow these steps:

1. Remove build script: Delete build.rs from your project directory and remove the build = "build.rs" line from your Cargo.toml.
2. Disable default features: Set default-features = false in your Cargo.toml to opt out of the legacy backend.
3. Select N-API version: Enable the specific N-API version feature flag required for your target Node.js environment (e.g., "napi-4").

Requirements:

• Minimum Node.js version: 10.0.
• Consult the official N-API feature matrix to determine the appropriate version for your Node.js release.

[dependencies.neon]
version = "0.9.1"
default-features = false
features = ["napi-4"]

Use create-neon to bootstrap a Neon project consisting purely of Rust code. This allows you to build binary Node modules written in Rust.

To create a project, use the npm init neon syntax. Note that the -- separator is required to pass options through npm init to the Neon tool.

$ npm init neon[@latest] -- [<opts> ...] my-project

In Neon 1.0.0, CallContext<T> is replaced by FunctionContext. The This trait is also removed. Instead of relying on the T parameter in JsFunction to type-check cx.this(), cx.this() now always returns a JsValue. You must use .this::<T>()? to downcast the context to a specific type.

// Before
fn example(mut cx: CallContext<JsObject>) -> JsResult<JsUndefined> {
    let a = cx.this().get::<JsValue, _, _>(&mut cx, "a")?;
    Ok(cx.undefined())
}

// After
fn example(mut cx: FunctionContext) -> JsResult<JsUndefined> {
    let a = cx.this::<JsObject>()?.get::<JsValue, _, _>(&mut cx, "a")?;
    Ok(cx.undefined())
}