napi 0.22.0

Generate Dart bindings for Node-API addons and WebAssembly modules.

napi

Build Node.js extensions in Dart. Export functions and classes, generate an npm package, and call it from JavaScript or TypeScript. Choose Dart Wasm or a native Node-API .node addon; both run your application code in Dart.

Requirements

• Dart 3.13.5.
• Node.js 24.19.0 or 26.11.1.
• Native builds: macOS 14 or later on arm64, or Linux x64 with glibc 2.28 or later. The precompiled runtime downloads automatically on first use. Linux needs unzip to extract that download. Application builds do not need a C/C++ toolchain or Dart SDK sources. See native builds for offline builds.

Wasm is the default target. It depends on experimental Dart compiler and interop APIs and is tied to Dart 3.13.5. Browser and Bun support is not yet verified.

Build a package

Create a Dart package and add napi:

dart create -t package dart_counter
cd dart_counter
dart pub add napi

Write lib/counter.dart:

import 'package:napi/napi.dart';

@NAPI()
class Counter {
  Counter([this.value = 0]);
  int value;
  int increment([int amount = 1]) => value += amount;
}

Create tool/build.dart:

import 'dart:io';
import 'package:napi/build.dart';

Future<void> main() async {
  await buildPackage(
    library: File('lib/counter.dart').absolute.uri,
    output: Directory('npm-package'),
    packagesPath: File('.dart_tool/package_config.json').absolute.path,
    metadata: {'name': '@scope/counter', 'version': '0.0.0'},
  );
}

Build and install the generated package in the same directory:

dart run tool/build.dart
npm init -y
npm install ./npm-package

Create example.mjs and run it with node example.mjs:

import {Counter} from '@scope/counter';

const counter = new Counter();
console.log(counter.increment());  // 1
console.log(counter.increment(2)); // 3

The package initializes when imported. TypeScript declarations are generated alongside the bindings. To use the package in another Node project, run npm pack ./npm-package and install the resulting tarball there.

For a native package, add target: BuildTarget.native to the buildPackage call. See native builds for runtime caching and offline builds, and packaging for dual-target packages and rebuilding output.

Learn more

• Export functions and classes
• Parameters and defaults · Numbers and strings
• Classes · Plain objects
• Lists, Maps and records · Shared JS collections
• Generic payloads · Concrete generic aliases
• Promises · Callbacks · Streams
• Binary data · Shared bytes
• Resource cleanup · Cancellation

Contributing

See CONTRIBUTING.md to run the tests.

License

MIT. See LICENSE. Generated packages include Dart's DART_LICENSE; keep the included license notices when distributing them.