napi 0.20.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. The precompiled runtime downloads automatically; application builds do not need a C/C++ toolchain.

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.