Writing Node.js Addons with .NET Native AOT: A Complete Guide

Ever wished you could write Node.js native addons in C# instead of C++? .NET Native AOT makes it possible—and practical.

---

The Problem with Traditional Node.js Addons

If you've ever built a Node.js native addon, you know the pain:

• C++ required: Even for simple functionality, you need C++ knowledge
• node-gyp complexity: Build system that's notoriously finicky
• Python dependency: Requires specific Python versions (often outdated)
• Cross-platform headaches: Different build configurations per OS

For the Microsoft C# Dev Kit team, these friction points added unnecessary complexity to their development workflow. They needed Windows Registry access from their VS Code extension—but the C++ tooling didn't align with their .NET-centric stack.

The Solution: .NET Native AOT

What if you could write Node.js addons in C#? With .NET Native AOT, you can. The C# Dev Kit team replaced their C++ addon with a C# implementation—and it worked beautifully.

Here's why this approach is groundbreaking:

1. No Python required - Just the .NET SDK
2. Modern C# features - Type safety, async/await, LINQ
3. Cross-platform - Works on Windows, Linux, and macOS
4. Smaller toolchain - One SDK for everything

---

How It Works: N-API + Native AOT

The Magic Ingredient: N-API

N-API (Node-API) is a stable, ABI-compatible C API for building Node.js addons. The key insight: N-API doesn't care what language you use.

As long as your shared library exports the napi_register_module_v1 function and uses the correct C calling convention, Node.js will load it. This makes Native AOT a perfect fit.

Native AOT Compilation

.NET Native AOT compiles your C# code directly to native machine code, producing:

• Windows: .dll shared library
• Linux: .so shared library
• macOS: .dylib shared library

Node.js treats these as native addons (rename to .node extension).

---

Step-by-Step Implementation

1. Create the Project

Create a new console app with these properties:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <PublishAot>true</PublishAot>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>
</Project>

• PublishAot enables Native AOT compilation
• AllowUnsafeBlocks needed for pointer interop with N-API

2. Define the Module Entry Point

Node.js expects your shared library to export napi_register_module_v1. We use UnmanagedCallersOnly:

public static unsafe partial class RegistryAddon
{
    [UnmanagedCallersOnly(
        EntryPoint = "napi_register_module_v1",
        CallConvs = [typeof(CallConvCdecl)])]
    public static nint Init(nint env, nint exports)
    {
        Initialize();

        // Register JavaScript functions
        RegisterFunction(
            env,
            exports,
            "readStringValue"u8,
            &ReadStringValue);

        return exports;
    }
}

Key points:

• UnmanagedCallersOnly tells the AOT compiler to export the method
• EntryPoint specifies the function name Node.js looks for
• CallConvs defines the calling convention (cdecl for most platforms)
• nint is the native-sized integer equivalent to intptr_t

3. Resolve N-API Functions Dynamically

N-API functions are exported by node.exe itself. We need to resolve them at runtime:

private static void Initialize()
{
    NativeLibrary.SetDllImportResolver(
        Assembly.GetExecutingAssembly(),
        ResolveDllImport);

    static nint ResolveDllImport(
        string libraryName,
        Assembly assembly,
        DllImportSearchPath? searchPath)
    {
        if (libraryName is not "node")
            return 0;

        // Resolve from the host process (Node.js)
        return NativeLibrary.GetMainProgramHandle();
    }
}

4. Define N-API Function Imports

Use LibraryImport (source-generated P/Invoke) for better performance:

private static partial class NativeMethods
{
    [LibraryImport("node", EntryPoint = "napi_create_string_utf8")]
    internal static partial Status CreateStringUtf8(
        nint env, ReadOnlySpan<byte> str, nuint length, out nint result);

    [LibraryImport("node", EntryPoint = "napi_create_function")]
    internal static unsafe partial Status CreateFunction(
        nint env, ReadOnlySpan<byte> utf8name, nuint length,
        delegate* unmanaged[Cdecl]<nint, nint, nint> cb,
        nint data, out nint result);

    [LibraryImport("node", EntryPoint = "napi_get_cb_info")]
    internal static unsafe partial Status GetCallbackInfo(
        nint env, nint cbinfo, ref nuint argc,
        Span<nint> argv, nint* thisArg, nint* data);
}

5. Marshal Strings Between JavaScript and C

Here's how to read a string argument from JavaScript:

private static unsafe string? GetStringArg(nint env, nint cbinfo, int index)
{
    nuint argc = (nuint)(index + 1);
    Span<nint> argv = stackalloc nint[index + 1];
    NativeMethods.GetCallbackInfo(env, cbinfo, ref argc, argv, null, null);

    if ((int)argc <= index)
        return null;

    // Get the UTF-8 byte length
    NativeMethods.GetValueStringUtf8(env, argv[index], null, 0, out nuint len);

    // Allocate buffer (stack for small, pool for large)
    int bufLen = (int)len + 1;
    byte[]? rented = null;
    Span<byte> buf = bufLen <= 512
        ? stackalloc byte[bufLen]
        : (rented = ArrayPool<byte>.Shared.Rent(bufLen));

    try
    {
        fixed (byte* pBuf = buf)
            NativeMethods.GetValueStringUtf8(env, argv[index], pBuf, len + 1, out _);

        return Encoding.UTF8.GetString(buf[..(int)len)]);
    }
    finally
    {
        if (rented is not null)
            ArrayPool<byte>.Shared.Return(rented);
    }
}

6. Implement Your Exported Function

[UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
private static nint ReadStringValue(nint env, nint info)
{
    try
    {
        var keyPath = GetStringArg(env, info, 0);
        var valueName = GetStringArg(env, info, 1);

        if (keyPath is null || valueName is null)
        {
            ThrowError(env, "Expected two string arguments: keyPath, valueName");
            return 0;
        }

        // Your .NET logic here
        using var key = RegistryKey.OpenBaseKey(
            keyPath, RegistryHive.LocalMachine, RegistryView.Registry64);

        return key?.GetValue(valueName) is string value
            ? CreateString(env, value)
            : GetUndefined(env);
    }
    catch (Exception ex)
    {
        // Always handle exceptions to avoid crashing Node.js
        ThrowError(env, $"Registry read failed: {ex.Message}");
        return 0;
    }
}

7. Call from TypeScript

Build and rename the output:

dotnet publish -c Release -r win-x64
# Result: RegistryAddon.dll
# Rename to: RegistryAddon.node

Then use it in TypeScript:

interface RegistryAddon {
    readStringValue(keyPath: string, valueName: string): string | undefined;
}

const registry = require('./native/win32-x64/RegistryAddon.node') as RegistryAddon;

const sdkPath = registry.readStringValue(
    'SOFTWARE\\dotnet\\Setup\\InstalledVersions\\x64\\sdk',
    'InstallLocation');

console.log('SDK Path:', sdkPath);

---

Performance Comparison

Microsoft's C# Dev Kit team found:

Key insight: For typical addon workloads, performance is essentially identical. The GC overhead is negligible in long-running processes like VS Code extensions.

---

Real-World Benefits

Simplified Development

Before (C++ with node-gyp):

• Requirements: C++, Python 2.x, node-gyp, platform-specific build tools

After (C# with Native AOT):

• Requirements: .NET SDK, Node.js

Cross-Platform Support

The same C# code works on Windows, Linux, and macOS:

# Windows
dotnet publish -r win-x64

# Linux
dotnet publish -r linux-x64

# macOS
dotnet publish -r osx-x64

Modern Language Features

Get access to the full .NET ecosystem:

• Async/await for I/O operations
• LINQ for data processing
• Records and pattern matching
• Strong typing and IntelliSense

---

When to Use This Approach

✅ Great For:

• Cross-platform Node.js tools
• Performance-critical operations
• Teams with .NET expertise
• Replacing Python dependencies

❌ Not Ideal For:

• Very simple addons (use JavaScript instead)
• Addons requiring extensive Node.js API surface
• Projects where C++ expertise is readily available

---

Getting Started

Prerequisites

• .NET 10 SDK (or .NET 11 Preview)
• Node.js 18+ (LTS version)
• Basic C# and Node.js knowledge

Project Template

dotnet new console -n MyNodeAddon
# Edit .csproj to add PublishAot and AllowUnsafeBlocks

Publishing

dotnet publish -c Release -r win-x64
mv MyNodeAddon.dll MyNodeAddon.node

---

Conclusion

.NET Native AOT opens an exciting new frontier for Node.js addon development. By leveraging N-API's language-agnostic design, you can write native addons in C# while enjoying:

• ✅ Simpler toolchain (no Python dependency)
• ✅ Modern language features
• ✅ Cross-platform compatibility
• ✅ Comparable performance to C++

The Microsoft C# Dev Kit team has proven this approach works in production. Whether you're building developer tools, performance-critical operations, or just want to unify your tech stack, .NET Native AOT for Node.js addons is worth serious consideration.

Resources

• Microsoft DevBlogs Announcement
• Node.js N-API Documentation
• .NET Native AOT Documentation
• C# Dev Kit on VS Code Marketplace

---

This post is based on the official Microsoft announcement from April 15, 2026, written by Drew Noakes, Principal Software Engineer at Microsoft.

Follow me on LinkedIn for more .NET and JavaScript content!