# Build

Build the NAPI-RS project

# Usage

# CLI
napi build [--options]

// Programmatically
import { NapiCli } from '@napi-rs/cli'

new NapiCli().build({
  // options
})

# Options

# Cross-compilation flags

napi build has three cross-compilation flags: --use-napi-cross, --cross-compile (-x) and --use-cross. All three are experimental: behavior may change between minor releases.

The recommended flags are --use-napi-cross for Linux glibc targets on a Linux x64/arm64 host, and --cross-compile (-x) for Windows MSVC targets from a non-Windows host and for musl targets. -x is also the fallback for glibc, macOS and FreeBSD targets when the preferred setup is not available on your host. Android, WASI and OpenHarmony targets need no cross flag at all: the CLI configures their toolchains from platform environment variables. --use-cross is legacy and not recommended, and the Docker-image based builds are deprecated. This page is a reference for what each flag does. To pick the right flag for your host and target, see Cross build. For Alpine/musl specifics, see the FAQ.

Each flag changes exactly one thing about the build:

# Pick exactly one

# Prerequisites

# Examples

One copy-paste command per flag:

# Linux glibc targets, from a Linux x64/arm64 host
napi build --release --target aarch64-unknown-linux-gnu --use-napi-cross

# Windows MSVC from a macOS/Linux host, musl, or the zigbuild fallback cases
napi build --release --target x86_64-unknown-linux-musl --cross-compile

# Legacy container build (not recommended)
napi build --release --target x86_64-unknown-linux-gnu --use-cross

# What napi build runs

napi build is a wrapper around one spawned command plus a set of environment variables. This section spells both out.

# The command

--cross-compile picks cargo-xwin by the target's platform: every *-windows-* triple built from a non-Windows host routes through cargo-xwin — including x86_64-pc-windows-gnu, not just MSVC. Being routed is not the same as being supported, though: cargo-xwin handles MSVC only, so for windows-gnu it configures nothing and the build fails at link time with error: linker `x86_64-w64-mingw32-gcc` not found. Build that target without -x, with a mingw-w64 toolchain — see the windows-gnu note in Recipes per target. Every non-Windows target goes through cargo-zigbuild — the CLI keeps no list of supported targets, and it uses zigbuild even when the target matches the host.

If the CARGO environment variable is set, the CLI spawns that binary instead — in every mode, including --use-cross, where it silently replaces cross.

# RUSTFLAGS

• Any *musl* target: the CLI appends -C target-feature=-crt-static to RUSTFLAGS.
• --strip: the CLI appends -C link-arg=-s.

Both are applied through the exported RUSTFLAGS environment variable. Cargo gives the env var precedence over rustflags in .cargo/config.toml, so once the CLI exports it, the rustflags from your .cargo/config.toml are ignored. If you need extra flags, add them to the RUSTFLAGS env var, not to .cargo/config.toml.

# C compiler

When both TARGET_CC and CC are set, TARGET_CC wins (since @napi-rs/cli 3.0.0-alpha.92).

# Default linkers for less common targets

Without --cross-compile, these targets get CARGO_TARGET_<T>_LINKER pointed at a cross gcc that you must install yourself. The CLI sets the env var without checking it: if the binary is missing, the build fails at link time. Your own CARGO_TARGET_<T>_LINKER env var always wins. With --cross-compile this table is skipped — linking is delegated to zig or xwin.

# Android, WASI and OpenHarmony

These targets get their toolchain env from the CLI whenever the target platform matches — with or without any cross flag — but each platform has its own conditions:

• Android: linker/CC/AR env is built from ANDROID_NDK_LATEST_HOME. A missing variable only prints a warning — the env vars are still set, with broken paths, and the build fails at link time. The whole setup is skipped when the host itself is Android.
• WASI: EMNAPI_LINK_DIR is always set to the bundled emnapi (the CLI errors if the emnapi, @emnapi/core and @emnapi/runtime versions mismatch). The wasi-sdk linker/CC env is set only when WASI_SDK_PATH is set and the directory exists — otherwise linking falls back to cargo's default, rustup's bundled rust-lld.
• OpenHarmony: env is built from $OHOS_SDK_PATH/native, or from OHOS_SDK_NATIVE when OHOS_SDK_PATH is unset. If neither is set, the CLI warns and sets nothing.

# Passing flags to Cargo

Flags after -- will be passed through to the cargo build command. For example:

napi build -- --locked

This will pass the --locked flag to cargo build, resulting in cargo build --locked.

# Note for --js-package-name

In the Deep dive section, we recommended you publish your package under npm scope. But if you are migrating an existed package which is not under the npm scope or you just don't want your package under an npm scope , you may trigger the npm spam detection while publishing the native platform packages. Like snappy-darwin-x64 snappy-darwin-arm64 etc...

In this case, you can publish your platform packages under npm scope to avoid the npm spam detection. And your users don't need to care about the platform native packages in optionalDependencies. Like snappy, users only need to install it via yarn add snappy. But platform native packages are under @napi-rs scope:

{
  "name": "snappy",
  "version": "7.0.0",
  "optionalDependencies": {
    "@napi-rs/snappy-win32-x64-msvc": "7.0.0",
    "@napi-rs/snappy-darwin-x64": "7.0.0",
    "@napi-rs/snappy-linux-x64-gnu": "7.0.0",
    "@napi-rs/snappy-linux-x64-musl": "7.0.0",
    "@napi-rs/snappy-linux-arm64-gnu": "7.0.0",
    "@napi-rs/snappy-win32-ia32-msvc": "7.0.0",
    "@napi-rs/snappy-linux-arm-gnueabihf": "7.0.0",
    "@napi-rs/snappy-darwin-arm64": "7.0.0",
    "@napi-rs/snappy-android-arm64": "7.0.0",
    "@napi-rs/snappy-android-arm-eabi": "7.0.0",
    "@napi-rs/snappy-freebsd-x64": "7.0.0",
    "@napi-rs/snappy-linux-arm64-musl": "7.0.0",
    "@napi-rs/snappy-win32-arm64-msvc": "7.0.0"
  }
}

For this case, @napi-rs/cli provides the --js-package-name to override generated package loading logic. For example in snappy we have package.json like this:

{
  "name": "snappy",
  "version": "7.0.0",
  "napi": {
    "name": "snappy"
  }
}

Without the --js-package-name flag, @napi-rs/cli will generate JavaScript binding to load platform native packages for you:

switch (platform) {
  case 'darwin':
    switch (arch) {
      case 'x64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-x64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-x64.node')
          } else {
            nativeBinding = require('snappy-darwin-x64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      case 'arm64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-arm64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-arm64.node')
          } else {
            nativeBinding = require('snappy-darwin-arm64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      default:
        throw new Error(`Unsupported architecture on macOS: ${arch}`)
    }
    break
    ...
}

This isn't what we want. So build it with --js-package-name to override the package name in generated JavaScript binding file: napi build --release --platform --js-package-name @napi-rs/snappy. Then the generated JavaScript file will become:

switch (platform) {
  case 'darwin':
    switch (arch) {
      case 'x64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-x64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-x64.node')
          } else {
            nativeBinding = require('@napi-rs/snappy-darwin-x64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      case 'arm64':
        localFileExisted = existsSync(join(__dirname, 'snappy.darwin-arm64.node'))
        try {
          if (localFileExisted) {
            nativeBinding = require('./snappy.darwin-arm64.node')
          } else {
            nativeBinding = require('@napi-rs/snappy-darwin-arm64') 
          }
        } catch (e) {
          loadError = e
        }
        break
      default:
        throw new Error(`Unsupported architecture on macOS: ${arch}`)
    }
    break
    ...
}