Neon CLI

0.10.1 verified Sat Apr 25 auth: no javascript

Official command-line tool for creating, building, and loading native Rust/Node.js modules using the Neon bindings framework. Current stable version is 0.10.1, targeting Node >=8 and N-API. The CLI provides scaffolding and build infrastructure for Neon projects; the core Neon library (separate package) enables high-performance Rust addons with a safe, idiomatic Rust API. Differentiates from napi-rs with a more Rust-centric declarative API and a mature macro-based approach. Release cadence is periodic with major versions (1.0.0-alpha pre-releases available).

Common errors

error neon: command not found ↓

cause neon-cli not installed globally or npx not used.

fix

Run 'npx neon' instead, or install globally with 'npm install -g neon-cli'.

error error[E0433]: failed to resolve: could not find `neon` in the crate root ↓

cause Missing neon dependency in Cargo.toml.

fix

Add 'neon = "0.10"' to [dependencies] in Cargo.toml.

error Error: Module did not self-register ↓

cause Neon module not built correctly or Node.js ABI mismatch.

fix

Run 'npx neon build' to rebuild the native module. Ensure Node.js version matches the module's target.

Warnings

breaking Removal of legacy backend in v1.0.0-alpha.1: only Node-API is supported going forward. ↓

fix Ensure your Neon module uses N-API only. Remove any legacy backend dependencies.

breaking Length APIs (argument, argument_ops, len) now use usize instead of i32 in v1.0.0-alpha.1. ↓

fix Update Rust code to use usize for length-related values.

breaking Removal of neon::object::This trait in v1.0.0-alpha.2. ↓

fix Remove usage of This trait. The declare_types macro was already removed.

breaking Snake_case to camelCase conversion when exporting functions in v1.1.0-alpha.2. ↓

fix Ensure exported function names use camelCase in JavaScript, or rename Rust functions accordingly.

breaking Removal of generic parameter from JsFunction in v1.0.0. ↓

fix Update JsFunction usage to remove generic parameter.

gotcha Soundness hole in JsArrayBuffer::external and JsBuffer::external (fixed in v0.10.1). Previous versions allowed creating buffers without 'static lifetime. ↓

fix Upgrade to v0.10.1 or later. Ensure external data has 'static lifetime.

Install

npm install neon-cli

yarn add neon-cli

pnpm add neon-cli

Imports

neon
wrong
```
const neon = require('neon-cli')
```
correct
```
import { neon } from 'neon-cli'
```
The CLI is primarily used as a command-line tool, not imported programmatically. However, if imported, it provides programmatic APIs. Use ESM import syntax.

build

wrong

const build = require('neon-cli').build

correct

import { build } from 'neon-cli'

Programmatic build function. Available from v0.10.0+.

load
wrong
```
const load = require('neon-cli/build').load
```
correct
```
import { load } from 'neon-cli'
```
Loads a Neon module into Node.js. Correct import is from 'neon-cli' directly.

Quickstart

Creates a new Neon project, builds the native Rust module, and runs a simple test to verify the module loads and works.

npx neon new my-project
cd my-project
npm install
npx neon build
npx node -e "const m = require('./native'); console.log(m.hello())"