Registry / http-networking / node-api-dotnet

node-api-dotnet

library0.9.19jsnpmunverified

node-api-dotnet is a JavaScript (Node.js) library that provides high-performance, in-process interoperability with .NET applications. It enables seamless bi-directional communication, allowing JavaScript applications to load .NET assemblies and invoke .NET APIs, and conversely, enabling .NET applications to interact with JavaScript packages and APIs. The package is currently in 'Public Preview' (version 0.9.19), indicating active development with potential for minor breaking API changes in future releases. It differentiates itself by leveraging Node-API (N-API), ensuring broad compatibility across Node.js versions without recompilation and support for other Node-API compatible JavaScript runtimes. Key features include TypeScript type-definition generation for .NET APIs, robust async/await support for .NET Tasks and JavaScript Promises, and efficient handling of data streams, providing a more integrated and performant alternative to inter-process communication solutions for mixed-language applications.

http-networking serialization

npm install node-api-dotnet

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-API-DOTNET

node-api-dotnet

http-networkingjavascriptv0.9.19

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Node-API .NET root module

✓ import * as dotnet from 'node-api-dotnet';

✗ import dotnet from 'node-api-dotnet';

The module exports an object containing .NET namespaces as properties. For ESM, use a namespace import (`* as`) to access the full structure. For CommonJS, use `const dotnet = require('node-api-dotnet');`

System.Console (from .NET)

✓ import * as dotnet from 'node-api-dotnet'; const Console = dotnet.System.Console;

✗ import { System } from 'node-api-dotnet'; const Console = System.Console;

Specific .NET types like `System.Console` are exposed as nested properties of the main `node-api-dotnet` module export, not as direct named exports from the top-level module.

TypeScript types for .NET APIs

✓ import type { System } from 'node-api-dotnet';

✗ import { System } from 'node-api-dotnet'; // In a type-only context

While `node-api-dotnet` ships with TypeScript type definitions, use `import type` when only referencing types to ensure the import is optimized away during compilation and doesn't cause runtime errors if the symbol is not a live runtime export.

Demonstrates importing the .NET interop module, calling a static .NET method, accessing a static property, and instantiating/using a .NET class (StringBuilder) from JavaScript with TypeScript.

import * as dotnet from 'node-api-dotnet'; // Using ESM for modern Node.js & TypeScript // 1. Accessing a static .NET class and method const Console = dotnet.System.Console; Console.WriteLine('Hello from .NET via JavaScript!'); // 2. Accessing a static property (e.g., .NET CLR Version) // System.Environment.Version is a common way to get CLR version in .NET const clrVersion = dotnet.System.Environment.Version.ToString(); console.log(`\n.NET CLR Version: ${clrVersion}`); // 3. Creating and using an instance of a .NET class (e.g., System.Text.StringBuilder) const StringBuilder = dotnet.System.Text.StringBuilder; const sb = new StringBuilder('Initial string'); sb.Append(' appended from JS!'); sb.Append(`\nCurrent UTC Time: ${new Date().toISOString()}`); const finalString = sb.ToString(); console.log(`\nStringBuilder output:\n${finalString}`); // Note: Async operations are also supported, e.g., for File I/O with .NET Tasks. // This example focuses on synchronous interop for brevity.

Debug

Known issues

breakingThe project is currently in 'Public Preview' status. This means there may be minor breaking API changes in future releases as the project matures and stabilizes.

fix

Always refer to the official documentation and release notes for migration guides and updated API surface when upgrading to new versions.

affects: >=0.9.0

gotchaPerformance overhead can occur with excessive synchronous calls or marshalling large amounts of data between JavaScript and .NET contexts. Optimize interop boundaries for efficiency.

fix

Minimize calls across the boundary, batch operations where possible, and leverage async APIs for long-running .NET tasks to prevent blocking the Node.js event loop and maximize throughput.

affects: >=0.9.0

Errors

Common errors & fixes

Error: Cannot find module 'node-api-dotnet'

The native module 'node-api-dotnet' could not be found or loaded, often due to compilation issues, incorrect Node.js version, or an architecture mismatch (e.g., x86 vs x64).

fix

Ensure Node.js and npm are up-to-date. Try running `npm rebuild` or `npm install` again. Verify that your system architecture matches the installed package binaries. Check Node-API compatibility matrix if issues persist.

UnhandledPromiseRejectionWarning: .NET Exception: <Your .NET exception message>

An unhandled exception originated within the invoked .NET code and propagated back to the JavaScript promise chain without being caught.

fix

Implement robust error handling in your .NET code. In JavaScript, always use `.catch()` on promises returned by async .NET operations to handle .NET exceptions gracefully.

TypeError: Cannot read properties of undefined (reading 'Console') or similar 'Cannot access X of undefined'

The specific .NET namespace (e.g., 'System') or type (e.g., 'Console') was not correctly exposed or accessed from the `node-api-dotnet` module due to incorrect path or casing.

fix

Double-check the exact casing and nesting of the .NET types and namespaces you are trying to access. Consult the generated TypeScript definitions or the .NET API documentation for the correct path.

Upgrade

Version history

0.9.19latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/microsoft/node-api-dotnet ↗

packagehttps://www.npmjs.com/package/node-api-dotnet ↗