A wrapper around Cargo making it easier to produce prebuilt binaries targeting iOS and Android matching the prebuilt binary specification as well as napi.rs to generate bindings from annotated Rust code.
Before building, ferric build asks Cargo for the crate's resolved features for each target and fails if napi-sys has either of these enabled:
dyn-symbols, which makes napi-rs look up Node-API functions in the host process at runtime instead of linking them againstweak-node-api. That doesn't work in React Native (#331).- A
napiNfeature above Node-API version 10, the highest version the host supports.
napi enables dyn-symbols through its default features, so disable those and pick the Node-API version explicitly:
[dependencies.napi]
version = "3"
default-features = false
features = ["napi10"]From napi4 onward, napi-rs's runtime uses threadsafe functions. If your addon doesn't need them (or anything else above Node-API 3), napi3 gives a slightly smaller binary (about 5 KB for a minimal addon).
Pass --skip-feature-check to bypass the check.
Scaffold a package building a Rust Node-API module, or bring an existing package
up to what ferric build expects of it:
npx ferric init packages/my-addon
The command creates whatever is missing — package.json, Cargo.toml,
build.rs, src/lib.rs and .gitignore — and adds the package to the
pnpm-workspace.yaml or "workspaces" of the mono-repo it is initialized into.
Running it against a package which already exists updates rather than overwrites:
package.jsongains the scripts, dependencies and prebuilt artifacts it lacks, and outdated dependencies are bumped.- An existing
Cargo.tomlkeeps its comments and formatting. Outdatednapi,napi-deriveandnapi-buildversions are bumped in place, and the command points out anything elseferric buildneeds. - A
main,types,src/lib.rsorbuild.rsthat differs is skipped, printing a diff to merge by hand. Pass--forceto overwrite them instead.
A newly created Cargo.toml can be configured with:
--node-api-version <version>: thenapiNfeature to enable, defaulting to 10.--napi-crate-version,--napi-derive-crate-versionand--napi-build-crate-version: the crate versions, defaulting to those tested withferric-example. These also set what an existingCargo.tomlis bumped to.--release-profile <speed|size|none>:speed(the default) enablesltoand a single codegen unit,sizealso optimizes for size and strips symbols, andnoneleaves[profile.release]out.
The name of the crate defaults to the package name without its npm scope
(@my-org/my-addon becomes my-addon) and can be set with --name. Cargo
normalizes it to my_addon for the artifacts it produces, which is the basename
ferric build writes its outputs and entrypoint with.
Every file it updates is printed as a diff, and --dry-run prints the whole
plan without writing anything:
npx ferric init packages/my-addon --dry-run
The ferric-example package is generated by this command: run pnpm run init-ferric-example from the root of the repository after changing the templates, which CI asserts leaves no diff.