# NAPI Config

Put the configuration under the napi key in package.json:

{
  "name": "@scope/addon",
  "napi": {
    "binaryName": "addon",
    "targets": ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
  }
}

Commands that expose --config-path can instead read a standalone JSON file. When both sources are present, the standalone config takes precedence. All user-supplied fields are optional.

# Schema

{
  napi?: {
    binaryName?: string
    targets?: string[]
    packageName?: string
    npmClient?: string
    constEnum?: boolean
    runtimeStringEnum?: boolean
    dtsHeader?: string
    dtsHeaderFile?: string
    wasm?: {
      initialMemory?: number
      maximumMemory?: number
      browser?: {
        fs?: boolean
        asyncInit?: boolean
        buffer?: boolean
        errorEvent?: boolean
      }
    }
  }
}

# Fields and effective defaults

One WebAssembly memory page is 64 KiB. The memory settings are written into the generated Node and browser WASI loaders; they are not Cargo memory limits.

# Declaration file header

When NAPI-RS generates index.d.ts, it starts the file with a default header:

/* auto-generated by NAPI-RS */
/* eslint-disable */

You can replace this header with your own TypeScript types, imports, license comments, or lint directives. A custom header replaces the default header entirely; include the auto-generated comment and the eslint directive in your own header if you want to keep them.

There are three ways to set the header, plus one way to disable it:

When several of them are set, NAPI-RS resolves the header in this order:

--no-dts-header skips header resolution and generates the .d.ts without any header.

For example, with a complex header in dts-header.d.ts:

/* auto-generated by NAPI-RS */
/* eslint-disable */

import type { ReadableStream } from 'node:stream/web'

type MaybePromise<T> = T | Promise<T>

{
  "napi": {
    "dtsHeaderFile": "./dts-header.d.ts"
  }
}

See Types overwrite for the attribute-level TypeScript overrides (ts_args_type, ts_return_type, and friends), which change individual declarations rather than the file header.

# What targets controls

targets drives packaging:

• napi create-npm-dirs creates one npm directory per target.
• napi artifacts maps built files into those directories.
• napi pre-publish versions and publishes those packages.
• A WASI target enables generation of <binaryName>.wasi.cjs and the related browser and worker files.

Setting targets does not make napi build compile each entry. Every build invocation produces one target selected by --target, CARGO_BUILD_TARGET, or the host default. Likewise, the cross-compilation flags (--use-napi-cross, --cross-compile, and --use-cross) have no config equivalent.

The target list also does not create arbitrary CI jobs. napi new filters the jobs already present in its selected template. If you add another accepted target, add its build job and verify its runtime separately. See Support and compatibility and Cross build.

# Deprecated v2 fields

The CLI still reads these fields for compatibility, but new projects should not use them:

The old nested napi.package.name field is not read by the v3 config normalizer. Move that value explicitly to napi.packageName.

# What is a target triple?

See Rust platform support and LLVM cross-compilation. A target triple describes the architecture, vendor, operating system, and ABI of the artifact, for example:

x86_64-unknown-linux-gnu
└─ arch  └ vendor └ system └ ABI

Once you know which triples you intend to ship, use Cross build to choose and verify the build mechanism for each one.