neon-bindings/neon

This system is a Rust library and tooling ecosystem for building native Node.js addons, enabling developers to expose Rust code as JavaScript modules with high performance and safety. It provides a comprehensive API for managing JavaScript values, handling asynchronous concurrency via Tokio, and defining classes, while ensuring memory safety through strict borrow checking and thread-local storage. The project also includes scaffolding tools to generate portable library projects with integrated CI/CD pipelines and supports execution across Node.js, Bun, and Electron environments.

27 changes.

The project was restructured into a Cargo and npm monorepo, introducing Neon 1.0 with a comprehensive N-API backend and procedural macros for simplified Rust-to-JavaScript bindings. This period focused on rebuilding core type systems, handle safety, and asynchronous execution models while expanding the \create-neon\ CLI to support library scaffolding and modern Rust editions.

12 changes.

The Neon library introduced a new type-extraction system with ergonomic extractors and a global async runtime executor to improve developer experience and async support. Simultaneously, the create-neon tool was significantly enhanced with modular scaffolding, CI/CD workflow templates, and support for generating portable Node libraries with improved TypeScript boilerplate.

The \create-neon\ generator now includes a complete set of GitHub Actions workflow templates (located in \pkgs/create-neon/data/templates/ci/github\) to automate the build, test, and release lifecycle for Neon libraries. These templates provide a reusable \build.yml\ that compiles native binaries across a matrix of platforms (macOS, Windows, Linux) and handles packaging, a \release.yml\ that manages versioning, tagging, and publishing to npm via workflow dispatch, and a \test.yml\ for continuous integration on pull requests and main branch pushes. The setup is configured to use Node 20 and stable Rust, with hardened third-party action references using explicit SHAs where available.

pkgs/create-neon/data/templates/ci · high confidence

The \create-neon\ tool now includes a dedicated GitHub CI plugin that automatically generates GitHub Actions workflows for building, testing, and releasing Neon projects. This plugin registers Handlebars helpers to process templates for setup actions, environment variables, and workflow files (build, release, test), and provides convenience scripts for triggering releases and dry-runs via the GitHub CLI.

pkgs/create-neon/src/ci · high confidence

A new benchmarking tool has been added to the \bench\ directory to track performance regressions in the Neon bindings. This suite includes a Rust library (\src/lib.rs\) that exposes several low-level operations—such as \hello\, no-op exports, and JavaScript callback invocations via \call\, \call\_with\, and \bind\—to a Node.js harness (\index.js\). The harness uses the \bench-node\ library to measure throughput and latency, reporting results in a format compatible with the bencher.dev platform.

bench · high confidence

Users can now register a global async runtime (such as Tokio) to be used by the Neon addon, enabling the execution of asynchronous tasks within the Node.js environment. This change introduces a \Runtime\ trait and a \set\_global\_executor\ function in \crates/neon/src/executor\, allowing developers to initialize a shared Tokio runtime once per process. Additionally, when the \tokio-rt\ feature is enabled, a multithreaded Tokio runtime is automatically registered if no custom executor is provided, simplifying setup for async-heavy addons.

crates/neon/src/executor · high confidence

This change introduces the \cargo-cp-artifact\ package, a command-line tool that parses cargo metadata to reliably locate and copy compiler artifacts (such as binaries, cdylibs, and dylibs) to specified output locations. It supports wrapping cargo commands to handle JSON diagnostics, automatically resolves crate names from npm environment variables (including scoped packages), and includes a workaround for macOS code-signing cache issues by unlinking \.node\ files before copying. The package also includes argument parsing logic that handles both explicit artifact specifications and shorthand flags, along with tests for the parsing behavior.

pkgs/cargo-cp-artifact · high confidence

The \create-neon\ CLI now includes templates to generate boilerplate for portable Node libraries written in Rust. This adds two new manifest templates: a base template for simple Node packages and a library-specific template that configures dual ESM/CJS exports, TypeScript types, and Neon-specific settings (such as platform targets and load paths). The library template conditionally includes TypeScript dependencies and supports namespaced NPM packages with optional organization and prefix configurations.

pkgs/create-neon/data/templates/manifest · high confidence

The scaffolding tool now includes a dedicated NPM cache class that stores the organization and prefix details for generated packages. This component provides the foundational logic to handle namespaced and optionally prefixed NPM binary packages, ensuring that the correct registry context is maintained during the creation of portable Node libraries.

pkgs/create-neon/src/cache · high confidence

The \create-neon\ CLI now supports creating library projects via the \--lib\ flag (e.g., \npm init neon --lib my-lib\). When generating a library, the tool scaffolds a TypeScript-based project structure, configures GitHub Actions CI/CD by default for automated testing and publishing, and allows users to specify target platforms and binary cache settings (such as npm org/prefix) through interactive prompts or command-line arguments. This complements the existing app generation, giving users a streamlined way to create reusable Neon modules with pre-configured publishing pipelines.

pkgs/create-neon/src · high confidence

The \crates/neon/src/sys\ module now provides a comprehensive set of unsafe Rust wrappers around Node-API (N-API) functions, exposing raw capabilities for working with JavaScript values, objects, arrays, buffers, strings, promises, and asynchronous work. This new layer allows users to interact directly with the underlying Node.js runtime when higher-level Neon abstractions are insufficient, including specific support for external buffers, type tagging (N-API 8+), and threadsafe functions.

crates/neon/src/sys · high confidence

The \neon::thread\ module is now available, providing \LocalKey\<T\>\ to store and access data specific to each JavaScript addon instance (thread). This allows addons to maintain distinct state across multiple worker threads or repeated instantiations within a single Node.js process, preventing panics that would occur if static references were shared across threads. The module includes methods like \get\_or\_init\ and \get\_or\_try\_init\ for safe, lazy initialization of thread-local values.

crates/neon/src/thread · high confidence

The \crates/neon/src/event\ module now exposes \Channel\ and \TaskBuilder\ to allow Rust code to schedule closures and tasks on the JavaScript main thread or Node worker pool. \Channel\ enables background threads to send results back to the event loop via \send\/\try\_send\, while \TaskBuilder\ provides a builder pattern for creating asynchronous tasks that resolve to JavaScript Promises or execute completion callbacks. This introduces a structured way to handle concurrency without blocking the JavaScript thread, replacing the deprecated \EventQueue\ type.

crates/neon/src/event · high confidence

This change introduces the \\#\[neon::class\]\ attribute macro, which automatically implements the \Class\ trait to simplify defining JavaScript classes in Rust, and adds the \Object::prop()\ builder method for convenient property access and manipulation. It also includes the internal \ClassMetadata\ and \Wrap\ infrastructure required to support these new capabilities.

crates/neon/src/object · high confidence

The \neon-macros\ crate now provides \\#\[neon::export\]\, \\#\[neon::class\]\, and \\#\[neon::main\]\ procedural macros to simplify building Node.js addons. \\#\[neon::export\]\ registers Rust functions, constants, and statics as JavaScript module exports, automatically converting snake\_case names to camelCase and supporting optional \context\ and \this\ parameters. \\#\[neon::class\]\ generates JavaScript class wrappers for Rust \impl\ blocks, handling constructors, methods, and finalizers. \\#\[neon::main\]\ registers the addon's entry point. These macros use \linkme\ for distributed slice registration, replacing manual symbol generation.

crates/neon-macros · high confidence

The \neon\ library introduces a new \types::extract\ module that replaces the previous argument-handling approach with a unified \TryFromJs\/\TryIntoJs\ trait system. This adds newtype extractors for common JavaScript types, including \Array\, \Buffer\, \ArrayBuffer\, \Json\ (via serde), \Boxed\ (for \JsBox\), and typed arrays (e.g., \Uint8Array\, \Float64Array\). It also provides extractors for Rust container types like \Vec\, \Arc\, \Rc\, \RefCell\, and \Either\, along with a \with!\ macro for executing arbitrary code during return conversion. Users can now extract function arguments and return values using these typed wrappers, enabling more ergonomic and type-safe bindings.

_crates/neon/src/types\impl/extract · high confidence

The \create-neon\ CLI has been updated to require users to explicitly specify whether they are creating an application or a library using the \--app\ or \--lib\ flags (or an interactive prompt). When creating a library (\--lib\), the tool now supports namespaced NPM packages and allows users to configure how native binary packages are cached and named via the \--bins\ flag, enabling flexible publishing strategies for scoped packages.

pkgs/create-neon/src/bin · high confidence

The \neon\ crate now enforces Rust's borrowing rules on JavaScript \Buffer\ and \TypedArray\ data at runtime. A new \Lock\ mechanism and \Ledger\ track active memory regions, allowing \try\_borrow\ and \try\_borrow\_mut\ to return a \BorrowError\ if a requested slice overlaps with an existing borrow. This prevents data races and memory corruption when multiple parts of a Rust extension access the same JavaScript buffer simultaneously, replacing previous unsafe assumptions with verified safety checks.

_crates/neon/src/types\impl/buffer · high confidence

The \crates/neon/src/result\ module now provides a Rust-native way to handle JavaScript exceptions using the standard \Result\ type. This introduces \NeonResult\ and \JsResult\ types, along with a \Throw\ struct to represent the JavaScript throwing state, allowing developers to use the \?\ operator for cleaner error propagation. It also includes a \ResultExt\ trait with an \or\_throw\ method to easily convert Rust errors into JavaScript exceptions.

crates/neon/src/result · high confidence

The \crates/neon/src/types\_impl\ module has been completely rewritten to provide the underlying implementations for Neon's JavaScript type system. This change introduces new or significantly updated implementations for core types including \JsBigInt\ (with support for i64/u64/i128/u128 conversions), \JsDate\ (with overflow/underflow error handling), \JsBox\ (for wrapping Rust data with garbage collection), and \JsError\ (with specific constructors for TypeError and RangeError). The refactoring also updates the internal handling of \JsPromise\ and \Deferred\, standardizes the \Value\ and \ValueInternal\ traits across all types, and improves safety and performance in FFI string handling via the new \Utf8\ and \SmallUtf8\ utilities. Users benefit from a more robust, consistent, and safer API for interacting with JavaScript values from Rust.

_crates/neon/src/types\impl · high confidence

The Neon bindings layer now dynamically loads Node-API symbols at runtime instead of linking against a static library. This allows native modules built with Neon to run in Bun, which may not expose the full Node-API surface; missing symbols now trigger a warning at startup rather than a hard failure, ensuring graceful degradation for unsupported APIs.

crates/neon/src/sys/bindings · high confidence

The \crates/neon/src\ module has been reorganized to support Node-API lifecycle management and enhanced macro capabilities. A new \lifecycle\ module introduces \InstanceData\ and \LocalCell\ to handle per-instance data and safe, re-entrant initialization via \get\_or\_try\_init\, ensuring clean termination of initialization transactions. The \macros\ module now includes documentation for the \\#\[neon::class\]\ attribute, enabling Rust structs to be exposed as JavaScript classes with support for constructors, methods, and finalizers. Additionally, the crate exposes \Exports\ for batch exporting values and updates the type hierarchy documentation to use the \aquamarine\ crate for generated diagrams.

crates/neon/src · high confidence

The \crates/neon/src/types\_impl/function\ module introduces \BindOptions\ as a new builder for invoking JavaScript functions, allowing users to chain \.bind()\, \.arg()\, and \.call()\ methods for cleaner function invocation. This new API replaces the previously available \CallOptions\ and \ConstructOptions\ builders, which are now marked as deprecated in favor of the unified \BindOptions\ approach.

_crates/neon/src/types\impl/function · high confidence

The \create-neon\ tool now requires users to explicitly specify the Neon project type (either \--app\ or \--lib\) via command-line flags or an interactive dialog. This change is supported by the introduction of a new \expect.ts\ testing utility in the \pkgs/create-neon/dev\ directory, which provides a structured way to automate and verify interactive CLI sessions by matching expected prompts and inputs against child process output.

pkgs/create-neon/dev · high confidence

The repository has been reorganized into a monorepo structure with a \packages/\ directory, and the project documentation has been significantly updated. This includes adding a new \AUTHORS.md\ file, adopting the Contributor Covenant Code of Conduct, and introducing \CONTRIBUTING.md\ with guidelines for issues and RFCs. The \README.md\ has been rewritten to reflect modern usage via \npm init neon\, updated platform support matrices (including Windows and Bun), and new licensing information (dual MIT/Apache 2.0). Additionally, configuration files like \.editorconfig\ and \.prettierignore\ have been added to standardize code formatting and editor behavior across the project.

(repo-wide) · high confidence

The project scaffolding code in \pkgs/create-neon/src/expand\ has been reorganized to improve maintainability and separation of concerns. The previous \expand.ts\ and \versions.ts\ files have been moved into a dedicated subdirectory, and the \Metadata\ class has been renamed to \Context\ to better reflect its role in holding project options and manifest data. A new \context.ts\ file defines the \Context\ class and associated types for package and crate data, while \versions.ts\ now explicitly handles version loading with static type assertions to avoid unstable Node.js import assertions. The \index.ts\ file provides utility functions for expanding Handlebars templates using this context, and the \Creator\ class logic (referenced in imports) has been split into a \create/\ directory to handle the sequence of creating temporary directories, generating boilerplate, and finalizing the project structure.

pkgs/create-neon/src/expand · high confidence

The internal implementation of JavaScript value handles has been restructured to improve safety guarantees. A new \TransparentNoCopyWrapper\ trait and \SuperType\ trait replace previous casting mechanisms, ensuring that handle types are transparent wrappers around their inner data. The \Root\ type, which holds strong references to prevent garbage collection, now explicitly tracks the JavaScript thread instance ID to enforce that roots are only accessed on the thread where they were created, panicking if accessed from a different thread. Additionally, the handling of root drops has been refined: for N-API versions prior to 6, dropping a root without calling \into\_inner\ or \drop\ will panic to prevent leaks, while N-API 6+ uses a global drop queue to manage cleanup.

crates/neon/src/handle · high confidence

The project creation logic has been restructured from a single script into a class-based hierarchy (AppCreator and LibCreator) that programmatically generates package.json scripts and handles boilerplate generation. This change introduces support for namespaced NPM packages by automatically stripping the namespace when generating the corresponding Rust crate name, and it ensures that Cargo build diagnostics are rendered to stderr for better visibility. Additionally, library projects now support TypeScript boilerplate generation, CI configuration, and explicit platform targeting.

pkgs/create-neon/src/create · high confidence

The main library entry point \lib/index.js\ has been removed. This file previously contained the core logic for detecting Rust manifests, generating Gyp and Cargo build configurations, and executing the native addon build process via node-gyp. Its removal indicates that the build orchestration functionality has been relocated or refactored out of this specific module.

lib · high confidence

The \\#\[neon::export\]\ macro now supports async functions, allowing Rust async code to be directly exposed to Node.js via a new internal executor integration. Additionally, JSON wrapping for return values has been improved using autoref specialization, and the \TryIntoJs\ and \TryFromJs\ traits now accept \Cx\ directly instead of being generic over \Context\, simplifying type inference for users.

_crates/neon/src/macro\internal · high confidence

The context API has been refactored to replace multiple generic context types with a single \Cx\ type, which uses deref coercion to work seamlessly with \FunctionContext\ and \ModuleContext\. This change simplifies writing generic helper functions that can accept any context type. Additionally, the \execute\_scoped\ and \compute\_scoped\ methods have been updated to prevent handle leaks by ensuring temporary handles are properly released within their scopes, improving memory safety during iterative operations.

crates/neon/src/context · high confidence

The templates used by \npm init neon --lib\ have been refined to improve type safety and clarity in the generated Node library. The CommonJS entry point now uses a \declare module\ block to explicitly type the Rust addon's exports, preventing them from defaulting to \any\, and replaces the previous string-subtype example with a clearer wrapper type. Additionally, the ESM entry point has been updated to re-export from the CommonJS module, and the addon loader template includes updated comments referencing the Neon CLI.

pkgs/create-neon/data/templates/ts · high confidence

The \create-neon\ scaffolding templates have been updated to generate projects compatible with Neon 1.0 and the Rust 2024 edition. Key changes include a new nested directory structure for TypeScript libraries (separating \src/\, \lib/\, and \crates/\), the addition of a Cargo workspace configuration (\Workspace.toml\), and updated boilerplate for library-specific exports and entry points. The templates now conditionally include CI/release scripts for libraries and adjust \.gitignore\ rules to account for the new layout.

pkgs/create-neon/data/templates · high confidence

Added Electron integration tests using Playwright; Added N-API integration tests for core Neon types and functions; Added N-API test suite for core JavaScript types and APIs; Added Rust 2024 edition test project for Neon bindings; Added UI tests for Neon class and export macros; Added tests for create-neon CLI argument validation and project scaffolding; Expanded test coverage for Neon N-API bindings.

The project is restructured into a Cargo and npm workspace, introducing the \neon\ crate at version 1.1.1 and \neon-macros\ at 1.1.1. This update includes a new \Cargo.lock\ file and updates various dependency versions, such as \syn\ to 2.0.57, \tokio\ to 1.34.0, and \smallvec\ to 1.11.2. The workspace also includes new test packages for Electron, N-API, Rust 2024, and UI testing, along with a benchmark suite, all configured to use the new Neon core.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 60 → 57 (-2.6)
• Rubric changed (rubric-2026.09.9 → rubric-2026.09.17) — scores are not directly comparable.

• Code Health 79 → 78 (-0.4)
• Architecture 92 → 89 (-2.9)
• Maturity 68 → 68 (-0.3)
• Readiness 63 → 46 (-16.3)
• Security 47 → 61 (+13.2)
• Performance 70 (new)

• Critical CVE: [CVE redacted] (package-lock.json)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [CVE redacted] (package-lock.json)
• …and 21 more

• Duplicate methods on Root with different names returning the same type
• Duplicate methods with different names (args vs arg) performing the same operation
• Duplicate methods with different names (argument vs arg) performing the same operation
• Duplicate operations with different names returning the same type
• Duplicated block (5 lines × 2) (crates/neon/src/sys/array.rs)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• Inconsistent naming and return types for error creation vs throwing. error/type_error/range_error return JsResult (likely creating the value), while throw_* variants return NeonResult (likely creating and throwing). However, throw_error is ambiguous compared to error + throw, and the naming convention mixes 'create' and 'throw' verbs inconsistently.
• Inconsistent naming for converting from a rooted/strong reference to a local handle. Root uses to_inner, while RootClassMetadata also uses to_inner, but Root has a duplicate into_inner. This is minor but adds to the noise.
• Low cohesion: Handle (LCOM4 5) (crates/neon/src/handle/mod.rs)
• Low cohesion: JsTypedArray (LCOM4 8) (crates/neon/src/types_impl/buffer/types.rs)
• Low cohesion: Meta (LCOM4 5) (crates/neon-macros/src/export/function/meta.rs)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Off-boarding risk: anonymized user #1
• Off-boarding risk: anonymized user #2
• Outdated: doc-comment
• Outdated: either
• …and 14 more

• 1 commits — 1 feature/other, 0 fixes

• (repo) — 1 commit

• change: Merge pull request #1144 from neon-bindings/kj/with-macro

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

neon-bindings/neon was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.