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

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`