dynwinrt

Call any Windows Runtime (WinRT) API from JavaScript or TypeScript — without writing a native addon.

Why dynwinrt?

If you've ever tried to call a modern Windows API (WinAppSDK, Windows AI, notifications, file pickers, sensors, …) from an Electron, Node, or Python app, you've probably hit one of these walls:

• Writing a C++ node-addon-api addon — needs node-gyp, MSVC, Python, the matching Windows SDK, and a CI matrix per Electron version.
• Writing a C# addon via node-api-dotnet — needs the .NET SDK, a csproj build step, and a hand-maintained wrapper for every API surface you want to expose.
• Waiting for an official projection — Windows ships .winmd metadata months before any JavaScript- or Python-friendly projection appears in a published package.

dynwinrt removes all of that. It reads the same .winmd metadata your Windows SDK / WinAppSDK NuGet packages already ship and calls the underlying COM vtables dynamically at runtime via libffi. The codegen emits typed .js + .d.ts wrappers; the runtime invokes them through dynwinrt's native binary. No MSBuild step in your app, no node-gyp, no per-Windows-version recompile.

import { LanguageModel } from './bindings/winrt';

const model = await LanguageModel.createAsync();
const result = await model.generateResponseAsync('Tell me a joke');
console.log(result.text);

That's the whole story: install, generate, import, call.

Scope — dynwinrt targets data-style WinRT APIs (AI, storage, networking, notifications, globalization, cryptography, sensors, …). It is not built for XAML / WinUI hosting — those need composable-class aggregation and a UI thread the library doesn't model. For everything else, it is the easiest path from JavaScript / TypeScript to native Windows.

Quick start

npm install @microsoft/dynwinrt
npm install -D @microsoft/dynwinrt-codegen

# Generate a binding for one class (auto-detects the Windows SDK winmd)
npx dynwinrt-codegen generate \
  --namespace Windows.Foundation \
  --class-name Uri \
  --output ./generated

const { roInitialize } = require('@microsoft/dynwinrt');
const { Uri } = require('./generated');

roInitialize(1);                                       // MTA
const uri = Uri.createUri('https://example.com/path?q=1');
console.log(uri.host);                                 // "example.com"

Generated bindings include async + progress support, generic collections (IVector<T>, IMap<K,V>), structs, enums, and delegates — see tools/dynwinrt-codegen/npm/README.md for the full feature list.

Repository layout

dynwinrt/
├── crates/dynwinrt/          # Core Rust runtime (FFI, metadata, async, delegates, collections)
├── bindings/
│   ├── js/                   # @microsoft/dynwinrt — JS / TS bindings (napi-rs)
│   └── py/                   # Python bindings (PyO3, experimental — not published)
├── tools/
│   └── dynwinrt-codegen/     # @microsoft/dynwinrt-codegen — typed-binding generator
├── tests/                    # Integration tests + sample E2E projects
└── bench-electron/           # Electron benchmark app

Build from source

# Core library
cargo build -p dynwinrt
cargo test  -p dynwinrt

# JS bindings (napi-rs)
cd bindings/js && npm install && npx napi build --no-const-enum --platform --release -o dist

# Python bindings (PyO3 + maturin) — experimental, not published to PyPI
cd bindings/py && maturin develop && pytest

# Codegen tool
cargo build -p dynwinrt-codegen --release
cargo run   -p dynwinrt-codegen -- generate --namespace Windows.Foundation --class-name Uri --output ./generated

Codegen CLI reference

Argument	Required	Description
--winmd PATH[;PATH...]	No	Path to .winmd file(s) (auto-detects Windows SDK if omitted)
--folder PATH	No	Directory containing .winmd files
--namespace NAMESPACE	No	WinRT namespace to generate (omit for all non-Windows.* namespaces)
--class-name CLASS	No	Specific class (transitively pulls in dependencies)
--ref PATH	No	Additional .winmd files for type resolution only (no code emitted)
--lang js	No	Target language (currently js only — emits .js + .d.ts)
--output DIR	No	Output directory (default ./generated)
--dry-run	No	Validate input, don't write files

For each WinRT class the codegen emits a typed wrapper, factory, interface registration, async + progress support, generic collections, structs, enums, delegates, and an index.js / index.d.ts that re-exports every emitted symbol.

Local development — fix import paths in generated files

Generated files import from '@microsoft/dynwinrt'. When iterating against a locally-built runtime, rewrite imports to the relative path:

find generated -name "*.js" -exec sed -i "s|from '@microsoft/dynwinrt'|from '../../dist/index.js'|g" {} +

Troubleshooting

Problem	Solution
cargo build fails with libffi errors	Ensure you have a C compiler (MSVC) and the Windows SDK installed
cargo test -p dynwinrt fails	Windows SDK must be installed at the default path with Windows.winmd
JS bindings won't build	Run npm install first; requires Node.js 18+
Python bindings won't build	Requires Python 3.8+ and maturin (pip install maturin)
Codegen snapshot tests fail	Line-ending differences — run cargo test -p dynwinrt-codegen -- --include-ignored to regenerate

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

License

This project is licensed under the MIT License.