Getting started

Start from @napi-rs/cli

The recommend way.

Install cli

Copy
yarn global add @napi-rs/cli

Create project

Copy
napi new

Package name

The name filed in package.json.

Choose targets you want to support

Platforms you want support to.

Enable GitHub actions

Generate GitHub actions config for you.

Deep dive

Here it is recommended to distribute your package under npm scope because @napi-rs/cli by default appends the different platform suffixes to the npm package name as the package name for the different platform binary distribution. Using npm scope will reduce the case of package name was taken.

For example if you want publish package @cool/core, with the macOS x64, Windows x64 and Linux aarch64 supported, @napi-rs/cli will create and publish four package for you:

• @cool/core includes just JavaScript codes, which actually load the native binary from per platforms.
• @cool/core-darwin-x64 for macOS x64 platform.
• @cool/core-win32-x64 for Windows x64 platform.
• @cool/core-linux-arm64-gnu for Linux aarch64 platform.

In every platform binary package, there are cpu and os fields in there package.json:

Copy
{
  "name": "@cool/core-darwin-x64",
  "version": "1.0.0",
  "os": ["darwin"],
  "cpu": ["x64"]
}

And @cool/core using these native packages as optionalDependencies:

Copy
{
  "name": "@cool/core",
  "version": "1.0.0",
  "optionalDependencies": {
    "@cool/core-darwin-x64": "^1.0.0",
    "@cool/core-win32-x64": "^1.0.0",
    "@cool/core-linux-arm64": "^1.0.0"
  }
}

And your index.js in @cool/core will be this:

Copy
const { loadBinding } = require('@node-rs/helper')

// The first argument is the dir to load native binding file during development.
// The second argument is the package name
// The third argument is the binary name of native binding file.
module.exports = loadBinding(__dirname, '@cool/core', 'core')

The loadBinding function from @node-rs/helper will help you to load the right binary file wherever you are. And actually the loadBinding function handle two cases:

Package installed in users node_modules

To load the correct binary, the loadBinding function tries to load all possible packages for that platform (there may be multiple possible binary packages for a given system and CPU architecture), for example, on the Linux x64 platform, loadBinding tries to load @cool/core-linux-x64-gnu and @cool/core-linux-x64-musl. The package @cool/core-linux-x64-gnu will be loaded if the user is using an operating system like Ubuntu Debian with gnu libc pre-installed. And if the user is using an operating system like Alpine with musl libc pre-installed, then @cool/core-linux-x64-musl will be loaded.

Local development

The build command in package.json in the project generated by the @napi-rs/cli new command will generate the binary dynamic link library compiled from the Rust code into the current directory for debugging purposes. loadBinding will also try to load the corresponding binary from the given directory (__dirname in the index.js example above) in this case.Again using Linux x64 as an example, the loadBinding function will try to load the core.linux-x64-gnu.node and core.linux-x64-musl.node files in turn.

Start from GitHub template project

1. Go to GitHub template project
2. Click Use this template
3. Clone your project
4. rename all @napi-rs/package-template in project to your package name.
5. rename all package-template in project to you binary name.