A new way to bring native Windows APIs to JavaScript – introducing dynamic API projections for Node.js

What makes this projection different

What you can build with the projection

The generator reads Windows metadata (.winmd) rather than relying on a fixed API catalog. Supported non-UI APIs include:

• On-device AI: text generation, summarization, rewriting, text-to-table, image description, text recognition, image scaling, object extraction and removal, plus Windows ML model and execution provider catalogs
• App and content APIs: notifications, file and folder pickers, storage, and image decoding, plus rich clipboard content
• System and device APIs: networking, sensors, globalization, and cryptography

The same metadata-driven workflow can project other compatible Windows Runtime APIs, including APIs from custom WinRT components.

The open-source Electron on Windows Gallery uses these JavaScript projections for its AI scenarios. Each interactive sample includes its JavaScript source, API documentation, and setup guidance.

Both examples use JavaScript only:

• Native notifications with AppNotificationBuilder / AppNotificationManager
• Phi Silica on-device AI with LanguageModel / TextSummarizer (Copilot+ PCs)

If you’re creating a new Electron app, start with the WinApp CLI Electron setup guide. It covers project creation, prerequisites, and the full WinApp CLI workflow.

For an existing Electron app, install the CLI and initialize the project:

npm install --save-dev @microsoft/winappcli
npx winapp init . --use-defaults --add-js-bindings

winapp init creates the manifest, sets up the SDKs, adds @microsoft/dynwinrt and @microsoft/dynwinrt-codegen to package.json, and generates JavaScript wrappers and TypeScript declarations under .winapp/bindings/. It also writes a winapp.jsBindings configuration block for adding namespaces or .winmd files, including metadata from custom WinRT components.

Setup adds #winapp/bindings and #winapp/bindings/* to the package.json#imports map for the generated CommonJS, ES module, and TypeScript declaration entry points. This keeps imports independent of the source file’s location. See the file picker guide for a detailed configuration example.

Both examples require package identity. To use them during development, give the Electron executable a temporary identity:

npx winapp node add-electron-debug-identity

Run this command again whenever the manifest, Electron executable path, or identity fields change. For APIs that don’t require package identity, skip this command and start Electron normally with npm start. See the debug identity guide for more detail.

Show a rich Windows notification

Electron’s built-in notification API covers basic toasts. Windows App SDK notifications add progress bars, actions, inputs, and scenarios. This main-process example shows a progress notification:

const {
  AppNotificationBuilder,
  AppNotificationManager,
  AppNotificationProgressBar,
} = require('#winapp/bindings');

const progress = AppNotificationProgressBar
  .create()
  .setTitle('Processing with Windows AI')
  .setStatus('Running locally')
  .setValue(0.65)
  .setValueStringOverride('65%');

AppNotificationManager.default_.show(
  AppNotificationBuilder
    .create()
    .addText('Windows AI task running')
    .addText('This notification uses a native Windows progress bar.')
    .addProgressBar(progress)
    .buildNotification()
);

See the Show a notification from JavaScript guide for a full walkthrough.

Run Phi Silica on-device AI

const {
  AIFeatureReadyState, LanguageModel, TextSummarizer,
} = require('#winapp/bindings');

async function summarize() {
  const readyState = LanguageModel.getReadyState();
  if (readyState !== AIFeatureReadyState.Ready &&
      readyState !== AIFeatureReadyState.NotReady) {
    console.log('Phi Silica is not available on this device.');
    return;
  }
  if (readyState === AIFeatureReadyState.NotReady) {
    await LanguageModel.ensureReadyAsync();
  }

  const model = await LanguageModel.createAsync();
  try {
    const op = TextSummarizer
      .createInstance(model)
      .summarizeParagraphAsync('Some long paragraph...');

    // Stream partial output as the model generates it
    op.progress((partial) => {
      process.stdout.write(partial);
    });

    const result = await op;
    console.log('\nDone:', result.text);
  } finally {
    model.close();
  }
}

summarize().catch(console.error);

<rescap:Capability Name="systemAIModels" />

npx winapp node add-electron-debug-identity

See the Call Phi Silica from JavaScript guide for a full walkthrough.

Add Windows SDK and custom APIs

By default, the WinApp CLI generates the supported Windows App SDK API surface; UI-only packages such as Microsoft.WindowsAppSDK.WinUI and Microsoft.Web.WebView2 are excluded. To include Windows SDK APIs, list the entry-point classes in package.json. For example, add the Windows Clipboard API:

{
  "winapp": {
    "jsBindings": {
      "additionalWinmds": [
        {
          "namespace": "Windows.ApplicationModel.DataTransfer",
          "classes": ["Clipboard", "HtmlFormatHelper"]
        }
      ]
    }
  }
}

npx winapp node generate-bindings

const {
  Clipboard,
  DataPackage,
  HtmlFormatHelper,
} = require('#winapp/bindings');

const html = HtmlFormatHelper.createHtmlFormat(`
  <h2>Hello from Electron</h2>
  <p>This was copied as <strong>HTML</strong> via Windows Clipboard APIs.</p>
  <p><a href="https://github.com/microsoft/winappCli">Open WinApp CLI on GitHub</a></p>
`);

const data = DataPackage.create();
data.setHtmlFormat(html);

Clipboard.setContent(data);
Clipboard.flush();

HtmlFormatHelper.createHtmlFormat wraps your markup with the CF_HTML header Windows expects, so any HTML-aware target renders it as rich text.

{
  "winapp": {
    "jsBindings": {
      "additionalWinmds": [
        {
          "winmdPath": "path/to/Foo.winmd",
          "namespace": "Foo.Bar",
          "classes": ["Baz"]
        }
      ]
    }
  }
}

Use the projection with plain Node.js

The projection also works in a plain Node.js process. To try a Windows API without packaging an MSIX, create a project and point the WinApp CLI at the existing node.exe:

mkdir my-winrt-experiment; cd my-winrt-experiment
npm init -y
npm install --save-dev @microsoft/winappcli
npx winapp init . --use-defaults --add-js-bindings

# winapp run needs an .exe inside the project. Alias .local-node to your Node install.
New-Item -ItemType Junction -Path .\.local-node -Target (Split-Path (Get-Command node).Source)

This example also uses Phi Silica, so add the same systemAIModels capability to Package.appxmanifest. Then create app.js with a short TextRewriter call:

const { roInitialize } = require('@microsoft/dynwinrt');
roInitialize(1); // MTA

const {
  AIFeatureReadyState,
  LanguageModel,
  TextRewriter,
  TextRewriteTone,
} = require('#winapp/bindings');

async function main() {
  const readyState = LanguageModel.getReadyState();
  if (readyState !== AIFeatureReadyState.Ready &&
      readyState !== AIFeatureReadyState.NotReady) {
    console.log('Phi Silica is not available on this device.');
    return;
  }
  if (readyState === AIFeatureReadyState.NotReady) {
    await LanguageModel.ensureReadyAsync();
  }

  const model = await LanguageModel.createAsync();
  try {
    const rewriter = TextRewriter.createInstance(model);
    const result = await rewriter.rewriteAsync(
      'WinApp CLI makes it easier to use Windows APIs from JavaScript.',
      TextRewriteTone.Formal
    );
    console.log(result.text);
  } finally {
    model.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

npx winapp run . --exe .local-node\node.exe --with-alias --args "app.js" --unregister-on-exit

winapp run registers the loose-layout package, launches .local-node\node.exe app.js with package identity and the Windows App SDK runtime graph, and unregisters it on exit. --with-alias routes the launch through the execution alias so stdout and stderr remain attached to the terminal.

For repeated runs with a persistent execution alias (mynode.exe app.js from any terminal), see the Plain Node.js dev-mode guide.

How the projection works

This is a public preview. If an API maps awkwardly into JavaScript, a TypeScript declaration looks wrong, or a scenario is missing, please file an issue. That feedback will help set priorities.

Where to file issues

The WinApp CLI and the underlying projection live in two different repos. File feedback in whichever fits your issue:

• CLI setup, configuration, identity, docs, and samples: microsoft/winappCli
• Runtime, code generator, type mapping, and generated TypeScript declarations: microsoft/dynwinrt