Configurando o ambiente de desenvolvimento

Este guia orienta você na configuração do ambiente de desenvolvimento do Electron para o desenvolvimento da API do Windows. Você instalará as ferramentas necessárias, inicializará o project e configurará os SDKs do Windows.

Pré-requisitos

Antes de começar, verifique se você tem:

  • Windows 11
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio com a Carga de Trabalho de Área de Trabalho Nativa - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Etapa 1: Criar um novo aplicativo Electron

Começaremos com um novo aplicativo Electron usando o Electron Forge, que fornece excelente suporte para ferramentas e empacotamento. Se você estiver começando a partir de um aplicativo existente, poderá ignorar esta etapa.

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

Quando solicitado pelo Electron Forge:

  • Bundler: Selecione Nenhum (recomendado, os complementos nativos funcionam sem configuração extra)
  • Idioma: Selecione JavaScript (este guia usa JS; TypeScript também funciona)
  • Versão do Electron: selecione a versão mais recente
  • Inicializar o git: sua preferência

Verifique se o aplicativo é executado:

npm start

Você deve ver a janela padrão do Electron Forge. Feche-o e vamos adicionar Windows funcionalidades!

Etapa 2: Instalar a CLI do winapp

O fluxo de trabalho Electron requer o pacote npm (@microsoft/winappcli), em vez da CLI autônoma instalada do winget. O pacote npm inclui helpers específicos do Node.js (como add-electron-debug-identity e create-addon) que não estão disponíveis na CLI nativa. Se você já tiver o winapp instalado pelo winget, tudo bem – o pacote npm adiciona ferramentas específicas do Node.js como uma dependência de projeto e não entra em conflito com a instalação do sistema.

npm install --save-dev @microsoft/winappcli

Etapa 3: inicializar o projeto para desenvolvimento do Windows

O winapp init comando configura tudo o que você precisa de uma só vez: manifesto do aplicativo, ativos e SDKs.

Execute o seguinte comando e siga os prompts:

npx winapp init .

Quando solicitado:

  • Nome do pacote: Pressione Enter para aceitar o padrão (my-windows-app)
  • Nome do publicador: pressione Enter para aceitar o valor padrão ou insira seu nome
  • Versão: Pressione Enter para aceitar 1.0.0.0
  • Ponto de entrada: pressione Enter para aceitar o padrão (my-windows-app.exe)
  • SDKs de instalação: selecione "SDKs estáveis"

O que faz winapp init ?

Este comando configura tudo o que você precisa para o desenvolvimento do Windows:

  1. Cria .winapp/ uma pasta que contém:

    • Cabeçalhos e bibliotecas do SDK Windows
    • Cabeçalhos e bibliotecas do SDK do Aplicativo Windows
    • Pacotes NuGet com os binários necessários

  2. Gera Package.appxmanifest - O manifesto do aplicativo necessário para a identidade do aplicativo e o empacotamento MSIX

  3. Cria Assets/ pasta – Contém ícones de aplicativo e ativos visuais para seu aplicativo

  4. Cria winapp.yaml – rastreia versões do SDK e configuração do projeto

  5. Instala SDK do Aplicativo Windows runtime – componentes de runtime necessários para APIs modernas

  6. Ativa o Modo de Desenvolvedor no Windows – Necessário para depurar nosso aplicativo

Observação

A .winapp/ pasta é adicionada .gitignore automaticamente e não deve ser verificada na origem.

Você pode abrir Package.appxmanifest para personalizar ainda mais as propriedades, como o nome de exibição, o editor e os recursos.

Dica

About the Windows SDKs:

  • Windows SDK – uma plataforma de desenvolvimento que permite criar aplicativos Win32/desktop. Ele foi projetado com base em APIs Windows acopladas a versões específicas do sistema operacional. Use isso para acessar AS APIs principais do Win32, como sistema de arquivos, rede e serviços do sistema.

  • SDK do Aplicativo Windows – uma nova plataforma de desenvolvimento que permite criar aplicativos de área de trabalho modernos que podem ser instalados em versões Windows (até Windows 10 1809). Ele fornece uma abstração conveniente e desacoplada pelo sistema operacional em torno do catálogo avançado de APIs do sistema operacional Windows. O SDK do Aplicativo Windows inclui o WinUI 3 e fornece acesso a recursos modernos, como recursos de IA (Phi Silica), notificações, gerenciamento de janelas e muito mais que recebem atualizações regulares independentemente das versões do sistema operacional Windows.

Saiba mais: O que é a diferença entre o SDK do Aplicativo Windows e o SDK do Windows?

Etapa 4: Adicione restauração ao pipeline de build

Para garantir que os SDKs de Windows estejam disponíveis quando outros desenvolvedores clonarem seu projeto ou em pipelines de CI/CD, adicione um script postinstall ao package.json:

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

Esse script é executado automaticamente após npm install e faz duas coisas:

  1. winapp restore – Baixa e restaura todos os pacotes do SDK Windows para a pasta .winapp/
  2. winapp node add-electron-debug-identity - Registra seu aplicativo Electron com a identidade de depuração (mais sobre isso nas próximas etapas)

Agora, execute npm install para disparar o script pós-instalação e configurar o ambiente Windows:

npm install

Observação

O postinstall script é executado automaticamente após cada npm install. Isso significa que o ambiente Windows será configurado automaticamente sempre que alguém clonar seu projeto e executar npm install.

💡 Desenvolvimento multiplataforma (clique para expandir)

Se você estiver criando um aplicativo Electron multiplataforma e tiver desenvolvedores trabalhando no macOS ou no Linux, você desejará executar condicionalmente a configuração específica do Windows. Aqui está a abordagem recomendada:

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

Em seguida, atualize package.json:

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

Isso garante que Windows instalação específica seja executada apenas em computadores Windows, permitindo que os desenvolvedores em outras plataformas trabalhem no projeto sem erros.

Etapa 5: Noções básicas sobre a identidade de depuração

O npm install que você executou na Etapa 4 disparou o script postinstall, que executou winapp node add-electron-debug-identity. Isso fornece ao seu aplicativo uma identidade de depuração temporária, permitindo que você teste as APIs do Windows que exigem identidade do aplicativo durante o desenvolvimento.

O que a identidade de depuração faz?

Este comando:

  1. Lê o seu Package.appxmanifest para obter detalhes e funcionalidades do aplicativo
  2. Registra electron.exe em sua node_modules com uma identidade temporária
  3. Permite testar APIs necessárias para identidade sem criar um pacote MSIX completo

A identidade de depuração foi aplicada automaticamente quando você executou npm install na Etapa 4. Doravante, ele será reaplicado sempre que alguém executar npm install.

Quando atualizar manualmente a identidade de depuração

Você precisa executar esse comando manualmente sempre que modificar Package.appxmanifest (alterar recursos, identidade ou propriedades) ou qualquer um dos ativos vinculados (ícones, mcp.json, etc.

npx winapp node add-electron-debug-identity

Testando sua configuração

Agora você pode testar seu aplicativo Electron com a identidade de depuração aplicada:

npm start

Você deve ver uma janela do aplicativo de desktop aberta (não uma guia do navegador) — é assim que os aplicativos Electron funcionam.

⚠️ Problema Conhecido: Falhas de aplicativo ou janela em branco (clique para expandir)

Há um bug de Windows conhecido com aplicativos Electron de empacotamento esparso que faz com que o aplicativo falhe no início ou não renderize o conteúdo da Web. O problema foi corrigido em Windows mas ainda não foi propagado para todos os dispositivos.

Sintomas:

  • O aplicativo falha imediatamente após a inicialização
  • A janela é aberta, mas mostra a tela branca.
  • Falha na renderização do conteúdo da Web

Solução alternativa:

Adicione o sinalizador --no-sandbox ao script de início no package.json. Isso soluciona o problema desabilitando a área restrita do Chromium, que é segura para fins de desenvolvimento.

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

Importante: Esse problema não afeta o empacotamento MSIX completo – somente a identidade de debug durante o desenvolvimento.

Para desfazer a identidade de depuração (se necessário para solução de problemas):

npx winapp node clear-electron-debug-identity

Isso restaura o executável do Electron original sem a identidade de depuração.

Próximas etapas

Agora que seu ambiente de desenvolvimento está configurado, você está pronto para criar complementos nativos e chamar APIs de Windows:

Ou retorne à Visão Geral de Introdução.

  • Last updated on