Setting Up the Development Environment

This guide walks you through setting up your Electron development environment for Windows API development. You'll install the necessary tools, initialize your project, and configure Windows SDKs.

Prerequisites

Before you begin, ensure you have:

• Windows 11
• Node.js - winget install OpenJS.NodeJS --source winget
• .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
• Visual Studio with the Native Desktop Workload - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Step 1: Create a New Electron App

We'll start with a fresh Electron app using Electron Forge, which provides excellent tooling and packaging support. If you are starting from an existing app, you can skip this step.

npm create electron-app@latest my-windows-app
cd my-windows-app

When prompted by Electron Forge:

• Bundler: Select None (recommended — native addons work without extra configuration)
• Language: Select JavaScript (this guide uses JS; TypeScript works too)
• Electron version: Select latest
• Initialize git: Your preference

Verify the app runs:

npm start

You should see the default Electron Forge window. Close it and let's add Windows capabilities!

Step 2: Install winapp CLI

The Electron workflow requires the npm package (@microsoft/winappcli) rather than the standalone CLI installed from winget. The npm package includes Node.js-specific helpers (like add-electron-debug-identity and create-addon) that are not available in the native CLI. If you already have winapp installed from winget, that's fine — the npm package adds Node.js-specific tools as a project dependency and won't conflict with your system installation.

npm install --save-dev @microsoft/winappcli

Step 3: Initialize the project for Windows development

The winapp init command sets up everything you need in one go: app manifest, assets, and SDKs.

Run the following command and follow the prompts:

npx winapp init .

When prompted:

• Package name: Press Enter to accept the default (my-windows-app)
• Publisher name: Press Enter to accept the default or enter your name
• Version: Press Enter to accept 1.0.0.0
• Entry point: Press Enter to accept the default (my-windows-app.exe)
• Setup SDKs: Select "Stable SDKs"

What Does winapp init Do?

This command sets up everything you need for Windows development:

1. Creates .winapp/ folder containing:

   • Headers and libraries from the Windows SDK
   • Headers and libraries from the Windows App SDK
   • NuGet packages with the required binaries

2. Generates Package.appxmanifest - The app manifest required for app identity and MSIX packaging

3. Creates Assets/ folder - Contains app icons and visual assets for your app

4. Creates winapp.yaml - Tracks SDK versions and project configuration

5. Installs Windows App SDK runtime - Required runtime components for modern APIs

6. Enables Developer Mode in Windows - Required for debugging our application

You can open Package.appxmanifest to further customize properties like the display name, publisher, and capabilities.

Step 4: Add Restore to Your Build Pipeline

To ensure the Windows SDKs are available when other developers clone your project or in CI/CD pipelines, add a postinstall script to your package.json:

{
  "scripts": {
    "postinstall": "winapp restore && winapp node add-electron-debug-identity"
  }
}

This script automatically runs after npm install and does two things:

1. winapp restore - Downloads and restores all Windows SDK packages to the .winapp/ folder
2. winapp node add-electron-debug-identity - Registers your Electron app with debug identity (more on this in the next steps)

Now run npm install to trigger the postinstall script and configure the Windows environment:

npm install

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  try {
    execSync('npx winapp restore && npx winapp cert generate --if-exists skip && npx winapp node add-electron-debug-identity', {
      stdio: 'inherit'
    });
  } catch (error) {
    console.warn('Warning: Windows-specific setup failed. If you are not developing Windows features, you can ignore this.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

{
  "scripts": {
    "postinstall": "node scripts/postinstall.js"
  }
}

Step 5: Understanding Debug Identity

The npm install you ran in Step 4 triggered the postinstall script, which ran winapp node add-electron-debug-identity. This gives your app a temporary debug identity so you can test Windows APIs that require app identity during development.

What Does Debug Identity Do?

This command:

1. Reads your Package.appxmanifest to get app details and capabilities
2. Registers electron.exe in your node_modules with a temporary identity
3. Enables you to test identity-required APIs without creating a full MSIX package

The debug identity was applied automatically when you ran npm install in Step 4. Going forward, it will be reapplied whenever anyone runs npm install.

When to Manually Update Debug Identity

You need to run this command manually whenever you modify Package.appxmanifest (change capabilities, identity, or properties) or any of the linked assets (icons, mcp.json, etc)

npx winapp node add-electron-debug-identity

Testing Your Setup

You can now test your Electron app with the debug identity applied:

npm start

You should see a desktop application window open (not a browser tab) — this is how Electron apps run.

{
  "scripts": {
    "start": "electron-forge start -- --no-sandbox"
  }
}

npx winapp node clear-electron-debug-identity

Next Steps

Now that your development environment is set up, you're ready to create native addons and call Windows APIs:

• Creating a Phi Silica Addon - Learn how to create a C# addon that calls the Phi Silica AI API
• Creating a WinML Addon - Learn how to create a C# addon that uses Windows Machine Learning
• Packaging for Distribution - Create an MSIX package for distribution

Or return to the Getting Started Overview.