Docs
CLI
Build

Build

Flags list

FlagType/Defualt ValueDescription
--platformBoolean/falseAdd platform triple to the .node file. [name].linux-x64-gnu.node for example.
--releaseBoolean/falseBypass to cargo build --release
--config or -cString/package.jsonnapi config path, only JSON format accepted. Default to package.json
--cargo-nameString/The [package].name field in Cargo.toml under command cwd.@napi-rs/cli will copy ./target/release/lib_[CARGO_NAME].[dll/dylib/so] file to [NAPI_NAME].[TRIPLE?].node by default. The [CARGO_NAME] in the source path is read from Cargo.toml in cwd by default. If you are building some other crate other than the one in the current cwd using the cargo build -p flag, you should override the CARGO_NAME by --cargo-name.
--targetString/undefinedBypass to cargo build --target, use this flag for cross compile.
⚠️ If no --target is specified, @napi-rs/cli will invoke rustup to determine the current target you build for. Make sure you have rustup installed on your PATH if this flag is omitted.
--featuresString/undefinedBypass to cargo build --features
--binString/undefinedBypass to cargo build --bin
--dtsString/index.d.tsThe filename and path of generated .d.ts file, relative to command cwd.
If you don't want NAPI-RS to generate .d.ts for you, you can disable the type-def feature in the napi-derive crate.
eg. napi-derive = { veriosn = "2", default-features = false }
⚠️ If type-def feature is disabled, the NAPI-RS will not generate the JavaScript binding file for you either because of the lack of type information.
-pString/undefinedBy pass to cargo build -p
--cargo-flagsString/''All the others flag bypass to cargo build command.
--jsString/index.jsThe filename and path of the JavaScript binding file, relative to the command cwd, pass false to disable it. Only effect if --platform is specified and type-def feature in napi-derive is enabled .
--js-package-nameString/name filed in package.json under command cwd.Packages name in generated js binding file, Only affect if --js is affected. #Note
⚠️ This flag will override the package.name field in napi config
You can omit it if you have specificed package.name config of napi config
--cargo-cwdString/process.cwd()The cwd of Cargo.toml. Specify this flag if you don't want to pass --cargo-name
--pipeString/undefinedPipe the generated .js/.d.ts files to this command, eg prettier -w
--zigBoolean/false@napi-rs/cli will use zig (opens in a new tab) as cc / cxx and linker to build your program.
--zig-abi-suffixString/''The suffix of the zig --target ABI version. Eg. --target x86_64-unknown-linux-gnu --zig-abi-suffix=2.17
--zig-link-onlyBoolean/false@napi-rs/cli will setup CC and CXX environment variables to use zig cc/zig c++ cross-compiling the C/C++ dependencies in crates. But if you've already setup C/C++ cross-compiling toolchain, you may want only use zig as the cross-compiling linker. Pass this flag to @napi-rs/cli and then it will not setup CC and CXX environment variables for your builds.

Note for --js-package-name

In the Deep dive section, we recommended you publish your package under npm scope (opens in a new tab). But if you are migrating an existed package which is not under the npm scope (opens in a new tab) or you just don't want your package under an npm scope (opens in a new tab) , you may trigger the npm spam detection (opens in a new tab) 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 (opens in a new tab) to avoid the npm spam detection (opens in a new tab). And your users don't need to care about the platform native packages in optionalDependencies. Like snappy (opens in a new tab), 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:

index.js
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:

index.js
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
    ...
}