Configurando React com Electron

Configurar o React com Electron começa pela criação de um projeto React com Vite e, em seguida, pela adição de electron e electron-builder como devDependencies. No final, o projeto tem dois pontos de entrada: o aplicativo Vite para o processo de renderização e um arquivo main.js para o processo principal do Electron.

main.js é o ponto de entrada do Electron. Ele cria um BrowserWindow com as dimensões e as configurações de segurança desejadas e depois carrega o aplicativo React, apontando para localhost:5173 durante o desenvolvimento e para um caminho de arquivo compilado em produção.

electron-vite é uma ferramenta de compilação completa que integra Vite ao Electron e gerencia automaticamente a complexa configuração de compilação multiprocesso. Ele fornece configurações separadas do Vite para os processos principal, de pré-carregamento e de renderização, simplificando significativamente as compilações de desenvolvimento e de produção.

Ao configurar o Vite para Electron, é necessário definir destinos explícitos de navegador em vez de depender da detecção automática, pois o processo de renderização é executado em uma versão específica do Chromium incluída no Electron. O electron-vite faz isso automaticamente, mas configurações manuais exigem que a versão do Chrome seja especificada no destino da compilação.

Executar electron-vite dev inicia simultaneamente o servidor de desenvolvimento do Vite para o processo de renderização e o processo principal do Electron. O servidor de desenvolvimento do Vite fornece substituição a quente de módulos, portanto as alterações nos componentes React aparecem instantaneamente na janela do Electron sem uma reinicialização completa.

O HMR funciona no processo de renderização do Electron assim como em um navegador: os componentes editados são renderizados novamente instantaneamente, preservando o estado. Somente alterações em main.js ou no script de pré-carregamento exigem uma reinicialização completa do Electron, pois esses arquivos são executados fora do limite do HMR do Vite.

Projetos com Electron, React e TypeScript precisam de arquivos tsconfig separados para o processo principal, voltado para Node.js/CommonJS; o processo de pré-carregamento, voltado para um ambiente semelhante ao navegador com globais do Node; e o processo de renderização, que usa o TypeScript padrão para navegador. O electron-vite cria essas configurações automaticamente.

O script de pré-carregamento usa contextBridge.exposeInMainWorld para expor sua API personalizada ao processo de renderização. Um padrão típico é expor um espaço de nomes como "api" com funções que encapsulam chamadas a ipcRenderer.invoke, fornecendo aos componentes React uma interface assíncrona e simples para as operações do processo principal.

Em qualquer componente React, você chama window.api.myFunction() para invocar a API exposta pelo script de pré-carregamento. Usuários do TypeScript normalmente adicionam uma declaração global (window: Window & { api: MyAPI }) para obter verificação de tipos e preenchimento automático na interface exposta.

electron-vite build compila os três destinos, principal, de pré-carregamento e de renderização, na pasta dist/. Em seguida, o electron-builder empacota tudo em um instalador específico da plataforma. Em produção, main.js carrega o processo de renderização a partir do caminho de arquivo incluído no pacote, em vez da URL do servidor de desenvolvimento.

Os erros de configuração mais frequentes são: esquecer nodeIntegration:false e contextIsolation:true, o que cria falhas de segurança; carregar a URL errada em main.js, entre desenvolvimento e produção; e importar módulos do Electron diretamente no processo de renderização, o que causa falhas. Os padrões do electron-vite evitam a maioria desses problemas.

O que executar electron-vite dev realiza?

Configurar o React com Electron é mais simples com o electron-vite, que gerencia a complexidade da compilação multiprocesso. O fluxo de desenvolvimento oferece suporte completo ao HMR, o contextBridge protege a superfície da API do processo de renderização e as configurações separadas do TypeScript garantem que cada processo tenha o ambiente de tipos correto. As compilações de produção usam o electron-builder para o empacotamento específico de cada plataforma.