Configuration de l’environnement de développement

Ce guide vous guide tout au long de la configuration de votre environnement de développement Electron pour le développement d’API Windows. Vous allez installer les outils nécessaires, initialiser vos project et configurer les kits SDK Windows.

Prerequisites

Avant de commencer, assurez-vous d’avoir :

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

Étape 1 : Créer une application Electron

Nous allons commencer par une nouvelle application Electron à l’aide d’Electron Forge, qui offre un excellent support pour les outils et l'empaquetage. Si vous démarrez à partir d’une application existante, vous pouvez ignorer cette étape.

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

Lorsque vous y êtes invité par Electron Forge :

  • Bundler : Sélectionner Aucun (recommandé — Les compléments natifs fonctionnent sans configuration supplémentaire)
  • Langage : sélectionnez JavaScript (ce guide utilise JS ; TypeScript fonctionne également)
  • Version d’Electron : Sélectionner la dernière version
  • Initialiser git : Votre préférence

Vérifiez que l’application s’exécute :

npm start

Vous devriez voir la fenêtre Electron Forge par défaut. Fermez-le et ajoutons les fonctionnalités Windows !

Étape 2 : Installer winapp CLI

Le flux de travail Electron nécessite le package npm (@microsoft/winappcli) plutôt que l’interface CLI autonome installée à partir de winget. Le package npm inclut des utilitaires spécifiques à Node.js (tels que add-electron-debug-identity et create-addon) qui ne sont pas disponibles dans l’interface en ligne de commande native. Si vous avez déjà installé winapp à partir de winget, c’est correct : le package npm ajoute Node.jsoutils spécifiques en tant que dépendance de projet et n’est pas en conflit avec l’installation de votre système.

npm install --save-dev @microsoft/winappcli

Étape 3 : Initialiser le project pour le développement Windows

La winapp init commande configure tout ce dont vous avez besoin en une seule fois : manifeste d’application, ressources et kits SDK.

Exécutez la commande suivante et suivez les instructions :

npx winapp init .

Lorsque vous y êtes invité :

  • Nom du package : appuyez sur Entrée pour accepter la valeur par défaut (my-windows-app)
  • Publisher nom : appuyez sur Entrée pour accepter la valeur par défaut ou entrer votre nom
  • Version : appuyez sur Entrée pour accepter la version 1.0.0.0
  • Point d’entrée : appuyez sur Entrée pour accepter la valeur par défaut (my-windows-app.exe)
  • Kits de développement logiciel (SDK) d’installation : sélectionnez « Kits de développement logiciel (SDK) stables »

Que fait winapp init ?

Cette commande configure tout ce dont vous avez besoin pour le développement Windows :

  1. Crée un .winapp/ dossier contenant :

    • En-têtes et bibliothèques de Windows SDK
    • En-têtes et bibliothèques du SDK d'application Windows
    • Packages NuGet avec les fichiers binaires requis

  2. Génère Package.appxmanifest - Manifeste d’application requis pour l’identité de l’application et l’empaquetage MSIX

  3. Crée un Assets/ dossier - Contient des icônes d’application et des ressources visuelles pour votre application

  4. Crée winapp.yaml - Effectue le suivi des versions du SDK et de la configuration du projet

  5. Installs SDK d'application Windows runtime - Installer les composants runtime requis pour les API modernes

  6. Active le mode développeur dans Windows - Obligatoire pour le débogage de notre application

Note

Le .winapp/ dossier est automatiquement ajouté .gitignore et ne doit pas être archivé dans la source.

Vous pouvez ouvrir Package.appxmanifest pour personnaliser davantage les propriétés telles que le nom d’affichage, l’éditeur et les fonctionnalités.

Tip

About the Windows SDK :

  • Windows SDK - Plateforme de développement qui vous permet de créer des applications Win32/desktop. Il est conçu autour d’API Windows couplées à des versions particulières du système d’exploitation. Utilisez-le pour accéder aux API Win32 principales telles que le système de fichiers, la mise en réseau et les services système.

  • SDK d'application Windows : nouvelle plateforme de développement qui vous permet de créer des applications de bureau modernes qui peuvent être installées sur Windows versions (jusqu’à Windows 10 1809). Il offre une abstraction pratique, découplée du système d'exploitation, autour du riche catalogue d'API Windows. Le SDK d'application Windows inclut WinUI 3 et fournit l’accès aux fonctionnalités modernes telles que les fonctionnalités d’IA (Phi Silicon), les notifications, la gestion des fenêtres et bien plus encore qui reçoivent des mises à jour régulières indépendantes des versions de système d’exploitation Windows.

En savoir plus : Quelle est la différence entre le SDK d'application Windows et le SDK Windows ?

Étape 4 : Ajouter une restauration à votre pipeline de build

Pour vous assurer que les sdk Windows sont disponibles lorsque d’autres développeurs clonent votre projet ou dans des pipelines CI/CD, ajoutez un script postinstall à votre package.json :

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

Ce script s’exécute automatiquement après npm install et effectue deux opérations :

  1. winapp restore - Télécharge et restaure tous les packages sdk Windows dans le dossier .winapp/
  2. winapp node add-electron-debug-identity - Inscrit votre application Electron avec l’identité de débogage (plus en détail dans les étapes suivantes)

Exécutez maintenant npm install pour déclencher le script postinstallé et configurer l’environnement Windows :

npm install

Note

Le postinstall script s’exécute automatiquement après chaque npm install. Cela signifie que l’environnement Windows sera configuré automatiquement chaque fois qu’une personne clone votre projet et s’exécute npm install.

💡 Développement multiplateforme (cliquez pour développer)

Si vous créez une application Electron multiplateforme et que les développeurs travaillent sur macOS ou Linux, vous devez exécuter de manière conditionnelle la configuration spécifique aux Windows. Voici l’approche recommandée :

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

Ensuite, mettez à jour package.json:

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

Cela garantit que la configuration spécifique à Windows s’exécute uniquement sur des machines Windows, ce qui permet aux développeurs sur d’autres plateformes de travailler sur le projet sans erreurs.

Étape 5 : Compréhension de l’identité de débogage

L’élément npm install que vous avez exécuté à l'étape 4 a déclenché le script postinstall, qui a exécuté winapp node add-electron-debug-identity. Cela donne à votre application une identité de débogage temporaire afin que vous puissiez tester les API Windows qui nécessitent une identité d'application pendant le développement.

Que fait l'identité de débogage ?

Cette commande :

  1. Lit Package.appxmanifest afin d'obtenir les détails et les fonctionnalités de l'application
  2. electron.exe est enregistré dans votre node_modules avec une identité temporaire
  3. Vous permet de tester les API requises pour l’identité sans créer de package MSIX complet

L’identité de débogage a été appliquée automatiquement lorsque vous avez exécuté npm install à l’étape 4. À l’avenir, il sera réappliqué chaque fois que quelqu’un exécute npm install.

Quand mettre à jour manuellement l’identifiant de débogage

Vous devez exécuter cette commande manuellement chaque fois que vous modifiez Package.appxmanifest (modifier les fonctionnalités, l’identité ou les propriétés) ou l’une des ressources liées (icônes, mcp.json, etc.)

npx winapp node add-electron-debug-identity

Test de votre configuration

Vous pouvez maintenant tester votre application Electron avec l’identité de débogage appliquée :

npm start

Vous devriez voir une fenêtre d’application de bureau ouverte (et non un onglet de navigateur), c’est-à-dire comment les applications Electron s’exécutent.

⚠️ Problème connu : Blocage de l’application ou fenêtre vide (cliquez pour développer)

Il existe un bogue Windows connu avec le conditionnement sparse d'applications Electron qui provoque un plantage de l'application au démarrage ou empêche le rendu du contenu web. Le problème a été résolu dans Windows mais n’a pas encore été propagé à tous les appareils.

Symptômes :

  • L’application se bloque immédiatement après le lancement
  • La fenêtre s’ouvre, mais affiche un écran vide/blanc
  • Le contenu web ne parvient pas à s’afficher

Solution de contournement :

Ajoutez l’indicateur --no-sandbox à votre script de démarrage dans package.json. Cela permet de contourner le problème en désactivant le bac à sable de Chromium, qui est sécurisé à des fins de développement.

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

Important : Ce problème n’affecte pas l’empaquetage MSIX complet — uniquement l’identité utilisée pour le débogage pendant le développement.

Pour annuler l’identité de débogage (si nécessaire pour la résolution des problèmes) :

npx winapp node clear-electron-debug-identity

Cela restaure l’exécutable Electron d’origine sans l’identité de débogage.

Prochaines étapes

Maintenant que votre environnement de développement est configuré, vous êtes prêt à créer des compléments natifs et à appeler des API Windows :

Vous pouvez également revenir à la vue d’ensemble de la prise en main.

  • Last updated on