napi-rs Docs
Getting started
Getting started
Start from @napi-rs/cli
The recommend way.
Install cli
yarn global add @napi-rs/cli
Create project
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 justJavaScript
codes, which actually load the native binary from per platforms.@cool/core-darwin-x64
formacOS x64
platform.@cool/core-win32-x64
forWindows x64
platform.@cool/core-linux-arm64-gnu
forLinux aarch64
platform.
In every platform binary package, there are cpu
and os
fields in there package.json
:
{ "name": "@cool/core-darwin-x64", "version": "1.0.0", "os": ["darwin"], "cpu": ["x64"]}
And @cool/core
using these native packages as optionalDependencies
:
{ "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:
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
- Go to Github template project
- Click Use this template
- Clone your project
- rename all
@napi-rs/package-template
in project to your package name. - rename all
package-template
in project to you binary name.