SOP: Install the Neon Toolchain

Fresh 🌱

Goal: Get a machine ready to build Neon modules. Neon needs two toolchains present at the same time: Node.js (the JavaScript runtime and package manager) and Rust (the systems language and its build tool, Cargo).

Done when: node --version, npm --version, and cargo --version all return a version, and npm init neon runs.

Step 1 - Install Node.js

Neon supports the latest Node version and all active LTS releases. If you do not already have a supported Node version installed, install one from the official Node.js distribution.

Verify:

node --version
npm --version

Which Node version?

By default, npm init neon targets the Node version you currently have installed. You can change the target later by adjusting the napi feature in Cargo.toml (see Step 4).

Step 2 - Install Rust

Neon requires a Rust toolchain for development. Install Rust with rustup (the official Rust toolchain installer) if you do not already have it.

Verify:

rustc --version
cargo --version

Step 3 - Install platform build dependencies

Rust may need additional native build tools depending on your operating system:

Platform	Extra requirement
Windows	Visual Studio Build Tools (the C++ build toolchain / MSVC linker).
macOS	Xcode Command Line Tools (xcode-select --install).
Linux	A C compiler and make (for example the build-essential package on Debian/Ubuntu).

These provide the linker and system headers that the Rust compiler invokes when producing the final native binary.

Step 4 - Understand the Node-API target

Neon builds on top of Node-API (the stable native addon ABI). A Neon project declares which Node-API version it targets through a Cargo feature, much like Babel targets a minimum JavaScript version:

[dependencies.neon]
features = ["napi-6"]

A higher napi-N enables more runtime capabilities but requires a newer minimum Node version. npm init neon picks a sensible default for you based on your installed Node version, so you usually do not need to set this by hand on day one.

Step 5 - Smoke test with a throwaway project

Confirm the full toolchain works end to end before starting real work:

npm init neon@latest my-project
cd my-project
npm install
node
> require(".").hello()
'hello node'

If require(".").hello() returns 'hello node', every piece of the toolchain is wired correctly.

Checklist

• [ ] node --version and npm --version succeed on a supported version
• [ ] cargo --version and rustc --version succeed
• [ ] Platform C/C++ build tools installed (MSVC / Xcode CLT / build-essential)
• [ ] npm init neon@latest scaffolds without error
• [ ] npm install builds and require(".").hello() returns 'hello node'

Build tools are the usual culprit

The most common first-time failure is a missing system linker or C compiler, which surfaces as a Rust link error at the end of npm run build, not at install time. If the build fails late with linker errors, revisit Step 3.

Next: build a real module in Hello, World!.