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 source path is read from Cargo.toml in cwd by default. If you are building some other crate other than the one in 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 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 generate .d.ts for you, you can disable the type-def feature in napi-derive crate.
eg. napi-derive = { veriosn = "2", default-features = false }
⚠️ If type-def features is disabled, the NAPI-RS will not generate the JavaScript binding file for you either because 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 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

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 a 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
    ...
}