Build

Flags list

Flag	Type/Defualt Value	Description
`--platform`	`Boolean`/`false`	Add platform triple to the `.node` file. [name].linux-x64-gnu.node for example.
`--release`	`Boolean`/`false`	Bypass to cargo build --release
`--config` or `-c`	`String`/`package.json`	napi config path, only JSON format accepted. Default to package.json
`--cargo-name`	`String`/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`.
`--target`	`String`/`undefined`	Bypass 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.
`--features`	`String`/`undefined`	Bypass to cargo build --features
`--bin`	`String`/`undefined`	Bypass to cargo build --bin
`--const-enum`	`Boolean`/`true`	Generate `const enum` in `.d.ts` file or not.
`--dts`	`String`/`index.d.ts`	The 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 = { version = "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*.
`-p`	`String`/`undefined`	By pass to cargo build -p
`--cargo-flags`	`String`/`''`	All the others flag bypass to cargo build command.
`--js`	`String`/`index.js`	The 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-name`	`String`/`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-cwd`	`String`/`process.cwd()`	The cwd of `Cargo.toml`. Specify this flag if you don't want to pass --cargo-name
`--pipe`	`String`/`undefined`	Pipe the generated .js/.d.ts files to this command, eg `prettier -w`
`--zig`	`Boolean`/`false`	`@napi-rs/cli` will use zig (opens in a new tab) as `cc` / `cxx` and `linker` to build your program.
`--zig-abi-suffix`	`String`/`''`	The suffix of the `zig --target` ABI version. Eg. `--target x86_64-unknown-linux-gnu` --zig-abi-suffix=2.17
`--zig-link-only`	`Boolean/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
    ...
}

Registering module Artifacts

Build

Flags list

Note for --js-package-name

Note for `--js-package-name`