Skip to content

setup.md

Latest commit

 

History

History
209 lines (144 loc) · 8.07 KB

setup.md

File metadata and controls

209 lines (144 loc) · 8.07 KB

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

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

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 appxmanifest.xml - 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

Note

The .winapp/ folder is automatically added to .gitignore and should not be checked in to source.

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

💡 About the Windows SDKs:

  • Windows SDK - A development platform that lets you build Win32/desktop apps. It's designed around Windows APIs that are coupled to particular versions of the OS. Use this to access core Win32 APIs like file system, networking, and system services.

  • Windows App SDK - A new development platform that lets you build modern desktop apps that can be installed across Windows versions (down to Windows 10 1809). It provides a convenient, OS-decoupled abstraction around the rich catalogue of Windows OS APIs. The Windows App SDK includes WinUI 3 and provides access to modern features like AI capabilities (Phi Silica), notifications, window management, and more that receive regular updates independent of Windows OS releases.

Learn more: What's the difference between the Windows App SDK and the Windows SDK?

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 whenever someone runs npm install, the Windows environment is automatically configured!

💡 Cross-Platform Development (click to expand)

If you're building a cross-platform Electron app and have developers working on macOS or Linux, you'll want to conditionally run the Windows-specific setup. Here's the recommended approach:

Create scripts/postinstall.js:

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.');
}

Then update package.json:

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

This ensures Windows-specific setup only runs on Windows machines, allowing developers on other platforms to work on the project without errors.

Step 5: Understanding Debug Identity

The postinstall script in Step 4 includes the winapp node add-electron-debug-identity command, which enables you to test Windows APIs that require app identity during development.

What Does Debug Identity Do?

This command:

  1. Reads your appxmanifest.xml 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 is automatically applied when you run npm install thanks to the postinstall script.

When to Manually Update Debug Identity

You need to run this command manually whenever you modify appxmanifest.xml (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
⚠️ Known Issue: App Crashes or Blank Window (click to expand)

There is a known Windows bug with sparse packaging Electron applications which causes the app to crash on start or not render web content. The issue has been fixed in Windows but has not yet propagated to all devices.

Symptoms:

  • App crashes immediately after launch
  • Window opens but shows blank/white screen
  • Web content fails to render

Workaround:

Add the --no-sandbox flag to your start script in package.json. This works around the issue by disabling Chromium's sandbox, which is safe for development purposes.

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

Important: This issue does not affect full MSIX packaging - only debug identity during development.

To undo debug identity (if needed for troubleshooting):

npx winapp node clear-electron-debug-identity

This restores the original Electron executable without the debug identity.

Next Steps

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

Or return to the Getting Started Overview.