{"id":11409,"library":"node-api-dotnet","title":"Node-API for .NET Interoperability","description":"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.","status":"active","version":"0.9.19","language":"javascript","source_language":"en","source_url":"https://github.com/microsoft/node-api-dotnet","tags":["javascript","Node-API","NAPI",".Net","dotnet","typescript"],"install":[{"cmd":"npm install node-api-dotnet","lang":"bash","label":"npm"},{"cmd":"yarn add node-api-dotnet","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-api-dotnet","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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');`","wrong":"import dotnet from 'node-api-dotnet';","symbol":"Node-API .NET root module","correct":"import * as dotnet from 'node-api-dotnet';"},{"note":"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.","wrong":"import { System } from 'node-api-dotnet'; const Console = System.Console;","symbol":"System.Console (from .NET)","correct":"import * as dotnet from 'node-api-dotnet'; const Console = dotnet.System.Console;"},{"note":"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.","wrong":"import { System } from 'node-api-dotnet'; // In a type-only context","symbol":"TypeScript types for .NET APIs","correct":"import type { System } from 'node-api-dotnet';"}],"quickstart":{"code":"import * as dotnet from 'node-api-dotnet'; // Using ESM for modern Node.js & TypeScript\n\n// 1. Accessing a static .NET class and method\nconst Console = dotnet.System.Console;\nConsole.WriteLine('Hello from .NET via JavaScript!');\n\n// 2. Accessing a static property (e.g., .NET CLR Version)\n// System.Environment.Version is a common way to get CLR version in .NET\nconst clrVersion = dotnet.System.Environment.Version.ToString();\nconsole.log(`\\n.NET CLR Version: ${clrVersion}`);\n\n// 3. Creating and using an instance of a .NET class (e.g., System.Text.StringBuilder)\nconst StringBuilder = dotnet.System.Text.StringBuilder;\nconst sb = new StringBuilder('Initial string');\nsb.Append(' appended from JS!');\nsb.Append(`\\nCurrent UTC Time: ${new Date().toISOString()}`);\nconst finalString = sb.ToString();\nconsole.log(`\\nStringBuilder output:\\n${finalString}`);\n\n// Note: Async operations are also supported, e.g., for File I/O with .NET Tasks.\n// This example focuses on synchronous interop for brevity.","lang":"typescript","description":"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."},"warnings":[{"fix":"Always refer to the official documentation and release notes for migration guides and updated API surface when upgrading to new versions.","message":"The 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.","severity":"breaking","affected_versions":">=0.9.0"},{"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.","message":"Performance overhead can occur with excessive synchronous calls or marshalling large amounts of data between JavaScript and .NET contexts. Optimize interop boundaries for efficiency.","severity":"gotcha","affected_versions":">=0.9.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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).","error":"Error: Cannot find module 'node-api-dotnet'"},{"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.","cause":"An unhandled exception originated within the invoked .NET code and propagated back to the JavaScript promise chain without being caught.","error":"UnhandledPromiseRejectionWarning: .NET Exception: <Your .NET exception message>"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'Console') or similar 'Cannot access X of undefined'"}],"ecosystem":"npm"}