but-napi

but-napi is used to build GitButler's Node native add-on via napi-rs.

High-level

Export types and bindings for TypeScript to be able to call our Rust API.

Purpose

• Provide the loadable .node binary for @gitbutler/but-sdk.
• Link but-api so auto-generated N-API exports are discoverable by napi-rs.
• Keep JavaScript/TypeScript consumers isolated from Rust internals behind generated bindings.

How bindings are produced

1. Rust APIs in crates/but-api are annotated with #[but_api(napi)].
2. The but_api proc macro generates *_napi wrappers (feature-gated by napi).
3. but-napi enables this with the napi-auto feature (but-api/napi) and compiles as a cdylib.
4. @napi-rs/cli builds this crate and writes JS + DTS + .node artifacts into packages/but-sdk/src/generated.

Features

• legacy (default): enables legacy APIs required by current desktop/lite workflows.
• napi-auto (default): turns on auto-generated #[but_api(napi)] exports.

Build entrypoint

From the repository root, use the but-sdk scripts (source of truth for local development flow):

pnpm --filter @gitbutler/but-sdk build

This will generate the native addon, JS loader, and type declarations (both generated by napi-rs and by but-ts) output in packages/but-sdk/src/generated.

Add a new N-API binding

1. In crates/but-api, add #[but_api(napi)] to the API function.
2. Build bindings with pnpm --filter @gitbutler/but-sdk build:napi.
3. Confirm the new *Napi function appears in packages/but-sdk/src/generated/index.d.ts.

Notes on configuration

• crates/but-napi/.napi-rs.json defines package/target metadata.
• In local development, output location is controlled by the explicit CLI flags in packages/but-sdk/package.json (build:napi).

See also

• but-sdk
• but-ts