# #[napi] attributes

The #[napi] macro exports Rust items and controls their JavaScript runtime behavior and generated TypeScript declarations. This page covers every public option accepted by napi-derive v3, including the two context-specific options parsed on parameters and enum variants.

use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi(js_name = "addOne", strict)]
pub fn add_one(value: u32) -> u32 {
  value + 1
}

# Supported targets

In the tables below:

• Function means an exported free function.
• Method includes instance methods, static methods, factories, constructors, getters, and setters where the option makes sense.
• Class means a struct exported with class identity. An object, array, or transparent struct is a value shape instead.
• Field means a struct field or a field of a structured enum variant.

With the default napi-derive/strict feature, an option accepted by the parser but unused on that kind of item is a compile error. Prefer the combinations documented here rather than relying on behavior when strict is disabled.

# Naming and exports

An inline Rust module can be turned into a JavaScript namespace. Only children that also carry #[napi] are exported, and nested napi modules are not supported.

#[napi(js_name = "math")]
mod arithmetic {
  #[napi]
  pub fn add(a: u32, b: u32) -> u32 {
    a + b
  }
}

export namespace math {
  export function add(a: number, b: number): number
}

# module_exports

The callback must be a non-generic free function. It can accept only Env, Object, or references to them, and it can return only () or Result<()>. It cannot be combined with constructor, factory, getter, setter, js_name, strict, return_if_invalid, or no_export.

#[napi(module_exports)]
pub fn initialize(mut exports: Object) -> Result<()> {
  exports.set("build", "release")?;
  Ok(())
}

For initialization that does not need the exports object, see Module initialization.

# Functions and methods

strict and return_if_invalid are mutually exclusive. They validate the ValidateNapiValue implementation for the Rust type; they do not perform arbitrary schema validation. Nested Vec<T> elements are converted one by one, and conversion can still fail after the initial array check.

Validation happens in the generated JavaScript callback before an async Rust future is created. On an async export, strict can therefore throw synchronously, while return_if_invalid returns synchronous undefined for invalid input rather than a Promise. These attributes do not change the generated async return type, so document that exceptional path explicitly.

# Classes and value shapes

Direction controls are compile-time controls: disabling a direction removes the corresponding conversion trait implementation. This is useful for input-only shapes containing callbacks or output-only shapes containing data that cannot be read from JavaScript.

#[napi(object, object_to_js = false)]
pub struct Request {
  pub path: String,
  pub on_chunk: ThreadsafeFunction<Buffer>,
}

#[napi(transparent)]
pub struct UserId(pub String);

#[napi(array)]
pub struct Point(pub f64, pub f64);

For an object or structured-enum field, the default mode accepts a missing property as None and omits None on output. A present value is converted as the inner T, so null and undefined are not universally accepted. With use_nullable = true, the property is required, Option<T> conversion accepts null as None, and output uses null; a missing or undefined property is still rejected. Arrays apply the same distinction to a missing tuple index versus a required index containing null. On a class, accessors and shorthand-constructor arguments already use normal Option<T> conversion and getters return null for None; use_nullable only changes the generated TypeScript shape.

# Fields

For a normal class, skip removes the generated JavaScript accessor, while skip_typescript leaves the accessor at runtime and hides only its declaration. On an object, array, or structured enum, skip and readonly affect the generated declaration but the runtime conversion still processes the field. Avoid skip with the #[napi(constructor)] struct shorthand: the generated constructor still consumes every field even though the skipped field is absent from its TypeScript signature.

# Enums

Accepted case names are lowercase, UPPERCASE, PascalCase, camelCase, snake_case, UPPER_SNAKE, kebab-case, and UPPER-KEBAB-CASE.

#[napi(string_enum = "kebab-case")]
pub enum Mode {
  ReadOnly,
  #[napi(value = "read-write")]
  Writable,
}

#[napi(discriminant = "kind", discriminant_case = "camelCase")]
pub enum Event {
  Ready,
  FileChanged { path: String },
  Progress(u32, u32),
}

string_enum accepts only fieldless variants and cannot be combined with explicit Rust discriminants. An enum containing any data-carrying variant is a structured enum; each variant becomes an object with the discriminator plus its fields. A field whose JavaScript name equals the discriminator is rejected.

# TypeScript overrides

#[napi(
  ts_generic_types = "T",
  ts_args_type = "value: T",
  ts_return_type = "T"
)]
pub fn identity<'env>(value: Unknown<'env>) -> Unknown<'env> {
  value
}

#[napi(ts_type = "(operation: 'add' | 'subtract', a: number, b: number): number")]
pub fn calculate(operation: String, a: i32, b: i32) -> i32 {
  match operation.as_str() {
    "add" => a + b,
    "subtract" => a - b,
    _ => 0,
  }
}

These strings are inserted into the generated declaration; napi-rs does not parse them as TypeScript or verify that they describe the runtime behavior. Keep runtime conversions authoritative and test the generated .d.ts file.

# Iterators

iterator and async_iterator are mutually exclusive. A generator class cannot expose public fields named next, return, or throw, because napi-rs installs those protocol methods. See Iterators and async iterators for the required traits and lifecycle constraints.

# Option index

The general parser accepts these options:

catch_unwind, async_runtime, module_exports, js_name, constructor, factory, getter, setter, readonly, enumerable, writable, configurable, skip, strict, return_if_invalid, object, object_from_js, object_to_js, custom_finalize, namespace, iterator, async_iterator, ts_args_type, ts_return_type, ts_type, ts_generic_types, string_enum, use_nullable, discriminant, discriminant_case, transparent, array, no_export, and skip_typescript.

The context-specific parsers additionally accept ts_arg_type on a function parameter and value on a string-enum variant.