# Cargo features

The napi feature set controls which Node-API symbols and high-level Rust APIs are compiled into an addon. Choose the lowest Node-API level that provides the APIs you use, then enable only the optional integrations your crate needs.

[dependencies]
napi = { version = "3", features = ["napi6", "async", "serde-json"] }
napi-derive = "3"

# Defaults

napi enables these features by default:

default = ["napi4", "dyn-symbols"]

This means adding features = ["napi2"] without disabling defaults still builds for Node-API 4. To target a level below 4, disable defaults explicitly and decide whether to retain dynamic symbol loading:

[dependencies]
napi = {
  version = "3",
  default-features = false,
  features = ["napi3", "dyn-symbols"]
}

# Node-API levels

The napi1 through napi10 features are cumulative. For example, napi8 enables napi7, which enables every lower level. The selected level is the minimum Node-API capability your addon may rely on.

The table lists representative high-level gates, not every raw function re-exported by napi-sys.

Node.js has backported some Node-API levels to multiple release lines, so a single Node major version is not a precise compatibility test. Check the official Node-API version matrix and the actual runtime value:

console.log(process.versions.napi)

Inside native code, Env::get_napi_version() reads the same value. Your package's supported-runtime claim should be no broader than both the selected Node-API level and the runtime versions you actually test.

# Choosing a level

1. Start with the template/default napi4 unless a dependency or required API dictates otherwise.
2. Raise it when the compiler shows that a needed API is feature-gated.
3. Test the oldest runtime in the resulting compatibility range.
4. Keep the CLI's minNodeApiVersion, Cargo features, package engines, and CI matrix consistent.

Raising the feature can make the resulting addon unloadable or unusable on older runtimes. Lowering it removes Rust APIs at compile time and is the safest way to discover accidental dependencies on a newer level.

# Async and Tokio

The component features enable features on the Tokio dependency. They do not all imply napi-rs's tokio_rt; list it explicitly unless another selected feature, such as web_stream, already enables it.

[dependencies]
napi = { version = "3", features = ["async", "tokio_fs", "tokio_time"] }

For CPU-bound work, prefer AsyncTask, which uses libuv's worker pool, instead of blocking the Tokio runtime.

# Conversion features

See Type conversions for directionality and data-copy behavior.

# Linking and runtime detection

# dyn-symbols

On supported native targets, dyn-symbols resolves Node-API functions from the host process when the addon initializes instead of requiring every symbol to be resolved by the platform linker. It is enabled by default.

This is especially useful across operating systems and Node-compatible hosts with different native linking behavior. Missing functions use generated stubs so symbol loading can continue, but calling a missing API still fails. dyn-symbols does not turn Node-API 10 into Node-API 4.

Disable it only when the target's static/direct symbol-linking model is deliberate and tested:

napi = { version = "3", default-features = false, features = ["napi6"] }

# node_version_detect

node_version_detect reads and caches the host Node version during module registration. napi-rs uses it to select a few guarded optimized paths, including newer property-creation paths when the required symbols and companion features are enabled.

It is not a general compatibility guard around every Node-API call. Your code must still respect the selected Node-API feature and runtime support matrix.

# Diagnostics and observability

[dependencies]
napi = { version = "3", features = ["napi4", "tracing"] }
napi-derive = { version = "3", features = ["tracing"] }

Generated callback events use the napi tracing target. Install and configure a tracing subscriber in the embedding application or addon initialization path if you want to observe them.

# Compatibility and development-only features

The iterator attributes are labeled experimental in the Rust API but are not controlled by the experimental Cargo feature. Synchronous iterators are in the base bindgen runtime; async iterators require tokio_rt.

# Cargo-only tests with noop

[features]
noop = ["napi/noop", "napi-derive/noop"]

[dependencies]
napi = "3"
napi-derive = "3"

Use this to test pure Rust logic that happens to live in an addon crate. Run JavaScript integration tests against a real built addon for conversions, exceptions, references, finalizers, workers, and environment cleanup.

# The full bundle

full is a convenience bundle containing exactly:

full = [
  "latin1",
  "napi10",
  "async",
  "serde-json",
  "experimental",
  "chrono_date",
]

It does not mean every feature: for example, it does not include web_stream, object_indexmap, deferred_trace, node_version_detect, tracing, error_anyhow, or every Tokio component.

Because it raises the Node-API level to 10 and enables experimental APIs, full is convenient for documentation builds and broad internal testing but is rarely the right default for a published addon.

# napi-derive features

The procedural macro crate has its own feature set:

Do not confuse napi-derive/strict with the per-function #[napi(strict)] attribute: the feature checks macro usage at compile time; the attribute validates JavaScript values at runtime.

# Recommended published-addon baseline

[dependencies]
napi = {
  version = "3",
  default-features = false,
  features = ["napi4", "dyn-symbols"]
}
napi-derive = "3"

[build-dependencies]
napi-build = "2"

Add integration features only as the public API requires them, document the resulting minimum Node-API level, and test that minimum runtime plus the current supported runtimes in CI.