napi-rs/package-template

Template project for using napi-rs to build native package

@napi-rs/package-template

Template project for writing node packages with napi-rs.

Usage

1. Click Use this template.
2. Clone your project.
3. Run yarn install to install dependencies.
4. Run npx napi rename -n [name] command under the project folder to rename your package.

Install this test package

yarn add @napi-rs/package-template

Support matrix

Operating Systems

	node14	node16	node18
Windows x64	✓	✓	✓
Windows x32	✓	✓	✓
Windows arm64	✓	✓	✓
macOS x64	✓	✓	✓
macOS arm64	✓	✓	✓
Linux x64 gnu	✓	✓	✓
Linux x64 musl	✓	✓	✓
Linux arm gnu	✓	✓	✓
Linux arm64 gnu	✓	✓	✓
Linux arm64 musl	✓	✓	✓
Android arm64	✓	✓	✓
Android armv7	✓	✓	✓
FreeBSD x64	✓	✓	✓

Ability

Build

After yarn build/npm run build command, you can see package-template.[darwin|win32|linux].node file in project root. This is the native addon built from lib.rs.

Test

With ava, run yarn test/npm run test to testing native addon. You can also switch to another testing framework if you want.

CI

With GitHub Actions, each commit and pull request will be built and tested automatically in [node@14, node@16, @node18] x [macOS, Linux, Windows] matrix. You will never be afraid of the native addon broken in these platforms.

Release

Release native package is very difficult in old days. Native packages may ask developers who use it to install build toolchain like gcc/llvm, node-gyp or something more.

With GitHub actions, we can easily prebuild a binary for major platforms. And with N-API, we should never be afraid of ABI Compatible.

The other problem is how to deliver prebuild binary to users. Downloading it in postinstall script is a common way that most packages do it right now. The problem with this solution is it introduced many other packages to download binary that has not been used by runtime codes. The other problem is some users may not easily download the binary from GitHub/CDN if they are behind a private network (But in most cases, they have a private NPM mirror).

In this package, we choose a better way to solve this problem. We release different npm packages for different platforms. And add it to optionalDependencies before releasing the Major package to npm.

NPM will choose which native package should download from registry automatically. You can see npm dir for details. And you can also run yarn add @napi-rs/package-template to see how it works.

Develop requirements

• Install the latest Rust
• Install Node.js@10+ which fully supported Node-API
• Install [email protected]

Test in local

• yarn
• yarn build
• yarn test

And you will see:

$ ava --verbose

  ✔ sync function from native code
  ✔ sleep function from native code (201ms)
  ─

  2 tests passed
✨  Done in 1.12s.

Release package

Ensure you have set your NPM_TOKEN in the GitHub project setting.

In Settings -> Secrets, add NPM_TOKEN into it.

When you want to release the package:

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]

git push

GitHub actions will do the rest job for you.

package-template's Issues

请问如何修改配置文件，来选择性的支持某些平台

如题，因为一些依赖库不跨平台，所以需要屏蔽某些平台。

是只需要修改 package.json 中 napi 下的 additional ，还是说 .github/workflows/CI.yml 也需要编辑？

有没有比较简单的配置办法？ 比如修改某个配置文件，然后运行cli，模板生成CI.yml什么的

rename fail: ENOENT: no such file or directory, open 'os-rs/package.json'

npx napi rename os-rs
Internal Error: ENOENT: no such file or directory, open 'os-rs/package.json'
Error: ENOENT: no such file or directory, open 'os-rs/package.json'

Segmentation fault when workers exit

I get segfaults on node 16 and node 18 when I use these in workers.

I'm on linux gnu x64

---

Replication steps:

Just run node segfault.js with:

segfault.js

var import_worker_threads = require("worker_threads");

if (import_worker_threads.isMainThread) {
  const worker = new import_worker_threads.Worker("./segfault");
} else {
  var import_napi_rs = require("@napi-rs/package-template");
}

If the parent thread has also imported it, it seems to work fine:

segfault.js with parent import:

var import_worker_threads = require("worker_threads");
var import_napi_rs = require("@napi-rs/package-template");

if (import_worker_threads.isMainThread) {
  const worker = new import_worker_threads.Worker("./segfault");
}

why use "cdylib" as crate-type?

I have a repo which contains a rust a binary foo and a napi-rs lib bar.

foo will import bar by local path link, but cdylib can't be used as dependency

Linker -- not found

I am currently getting this error on stable - armv7-linux-androideabi - node@16 and stable - stable - aarch64-linux-android - node@16 . A few days ago it all worked, I didn't modify anything.

CI file: https://github.com/xHyroM/bun-utilities/blob/master/.github/workflows/CI.yml

Segmentation fault

I have a segmentation fault when loading my native module from a file.
Strangely if I load it from another topper file it's ok then.

I debugged via console.log the index.js entrypoint and the issue is coming when calling. getReports() fonction that lead to the segmentation fault.

So it even does not get the glibcVersionRuntime ,

If I import it elsewhere on my project it's ok and get the glibcVersionRuntime 2.28 and return false

Not sure what to do then..

Optional dependencies with Yarn issue

I have a project which use the template, I am not able or don't want to build for FREEBSD,

But magically the package.json on npm contains optionalDependencieswhich contains the FreeBDS one.

With nom , no problem, but with yarn it will lead to an error not found and the main package will not be installed

You can try with yarn install @avahq/resampler-native-rubato

Side question but why does. it even try to download it ? Does this means that it will download all binaries in my project ? (I supposed It was more like prebuild which get the only binary needed)

yarn config with the current script `yarn-4.3.1.cjs` breaks `.yarnrc.yml

When running the command yarn config set supportedArchitectures.cpu "arm" the following will format the file incorrectly:

nodeLinker: node-modules
    
    npmAuditRegistry: "https://registry.npmjs.org"
    
    supportedArchitectures:
      cpu: arm
    
    yarnPath: .yarn/releases/yarn-4.3.1.cjs

The script in yarn-4.3.1.cjs does not format the modules correctly across all systems.

Locally and on the github action.

.

It works when using yarn-3.6.4.cjs.

Build FreeBSD failure

https://github.com/CodeEagle/flutter-resource-manager/actions/runs/3393777734/jobs/5641509806

test run project

just rename and push it to github, always build failed

node16 no longer available in FreeBSD pipeline

Hello,

I'm currently working on a project that uses napi-rs, and noticed that the FreeBSD runner is no longer able to find node16 from the package manager. To verify this, I forked this template repo and tried running the pipelines on the fork. You can find the output here:

https://github.com/traeok/package-template/actions/runs/3661652187/jobs/6190049422

Aside from that, the other stages seem to be working as intended. Thanks for maintaining such an awesome library!

MacOS tests missing from GitHub workflow

The sample workflow contains tests for Windows and multiple Linux versions, but none for MacOS. It contains a job called test-macOS-windows-binding, but the name seems misleading as it has nothing to do with MacOS: https://github.com/napi-rs/package-template/blob/main/.github/workflows/CI.yml#L212

Unknown Syntax Error: Unsupported option name ("--pipe")

yarn run v1.22.17
$ napi build --platform --release --pipe "prettier -w"
Unknown Syntax Error: Unsupported option name ("--pipe").

$ napi build [--platform] [--release] [--config,-c #0] [--cargo-name #0] [--target #0] [--features #0] [--cargo-flags #0] [--cargo-cwd #0] [destDir]
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Support nightly in docker images

Hi,

Thanks for all the work on napi-rs!

I am trying to get a publish pipeline compiling using the nightly toolchain. For the builds that don't use docker this is pretty simple but I am not sure how I could update the musl builds that use docker to compile using the nightly toolchain. Any ideas?

Also, I noticed that for the x86_64-unknown-linux-gnu target building using docker seems to be redundant as it is using an ubuntu-latest image. See: https://github.com/napi-rs/package-template/blob/main/.github/workflows/CI.yaml#L40-L47

I switched it to just yarn build and it seems good or am i missing something here?

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

cargo

Cargo.toml

• napi 2
• napi-derive 2
• napi-build 2

github-actions

.github/workflows/CI.yml

• actions/checkout v4
• actions/setup-node v4
• actions/cache v4
• goto-bus-stop/setup-zig v2
• addnab/docker-run-action v3
• actions/upload-artifact v4
• actions/checkout v4
• cross-platform-actions/action v0.25.0
• actions/upload-artifact v4
• actions/checkout v4
• actions/setup-node v4
• actions/download-artifact v4
• actions/checkout v4
• actions/setup-node v4
• actions/download-artifact v4
• actions/checkout v4
• actions/setup-node v4
• actions/download-artifact v4
• actions/checkout v4
• actions/download-artifact v4
• docker/setup-qemu-action v3
• addnab/docker-run-action v3
• actions/checkout v4
• actions/download-artifact v4
• docker/setup-qemu-action v3
• addnab/docker-run-action v3
• actions/checkout v4
• actions/download-artifact v4
• docker/setup-qemu-action v3
• addnab/docker-run-action v3
• actions/checkout v4
• actions/setup-node v4
• actions/download-artifact v4

.github/workflows/lint.yml

• actions/checkout v4
• actions/setup-node v4

npm

npm/android-arm-eabi/package.json

• node >= 10

npm/android-arm64/package.json

• node >= 10

npm/darwin-arm64/package.json

• node >= 10

npm/darwin-x64/package.json

• node >= 10

npm/freebsd-x64/package.json

• node >= 10

npm/linux-arm-gnueabihf/package.json

• node >= 10

npm/linux-arm64-gnu/package.json

• node >= 10

npm/linux-arm64-musl/package.json

• node >= 10

npm/linux-x64-gnu/package.json

• node >= 10

npm/linux-x64-musl/package.json

• node >= 10

npm/win32-arm64-msvc/package.json

• node >= 10

npm/win32-ia32-msvc/package.json

• node >= 10

npm/win32-x64-msvc/package.json

• node >= 10

package.json

• @napi-rs/cli ^2.18.4
• @swc-node/register ^1.10.6
• @swc/core ^1.6.13
• @taplo/cli ^0.7.0
• ava ^6.1.3
• chalk ^5.3.0
• husky ^9.0.11
• lint-staged ^15.2.7
• npm-run-all2 ^6.2.2
• oxlint ^0.7.0
• prettier ^3.3.3
• tinybench ^2.8.0
• typescript ^5.5.3
• node >= 10
• yarn 4.4.0

---

• Check this box to trigger a request for Renovate to run again on this repository