📚 Índice

• 🚀 Quick Start
• ✨ Features
• ⚡ Stack
• 🎯 Uso
• 📁 Estrutura do Projeto
• 🧠 Arquitetura
• 🔐 Segurança
• 🧪 Desenvolvimento
• 📦 Build
• 🖥️ Gerar Executáveis
• 🛠️ Configuração
• 🤝 Contribuição
• 📜 Licença

🚀 Quick Start

# Usando npx (recomendado)
npx vite-electron-app meu-app

# Ou instale globalmente
npm install -g vite-electron-app
vite-electron-app meu-app

# Entre no projeto
cd meu-app

# Instale as dependências
pnpm install

# Inicie o desenvolvimento
pnpm dev

Nota: Este projeto recomenda o uso do pnpm como gerenciador de pacotes.

✨ Features

• 🎯 Template Minimalista - Base limpa para customização conforme necessidade
• ⚡ Scaffolding Rápido - Crie projetos Electron em segundos
• 🔷 TypeScript Nativo - Código tipado do início ao fim
• ⚛️ React Moderno - Com Vite para desenvolvimento ágil
• 🔐 Seguro por Padrão - Configurações de segurança otimizadas
• 🔗 Suporte a Links Externos - API IPC documentada para abrir URLs no navegador
• 🛡️ Proteção contra Arquivos Perigosos - Bloqueia .env, chaves, certificados
• 🧩 Electron Builder - Empacotamento para Windows, macOS e Linux
• 📁 Estrutura Organizada - Separação clara de responsabilidades
• ♻️ Hot Reload - Atualização instantânea no desenvolvimento
• 🧪 Testes Incluídos - Estrutura para testes com Vitest
• 🔄 Idempotente - Scaffolding pode ser executado múltiplas vezes sem duplicações
• 🎨 Mensagens Coloridas - Output visual com cores e ícones

⚡ Stack

| Tecnologia | Descrição | |-----------|-----------| | Electron | Framework para criar aplicações desktop nativas | | Vite | Build tool ultrarrápido | | React | Biblioteca para construção de interfaces | | TypeScript | Superset JavaScript com tipos | | Electron Builder | Empacotamento de aplicações | | Vitest | Framework de testes |

🎯 Uso

Criar um novo projeto

# Sintaxe básica
npx vite-electron-app <nome-do-projeto>

# Exemplos
npx vite-electron-app my-electron-app
npx vite-electron-app desktop-app
npx vite-electron-app agenda-eletronica

Opções do Projeto

Durante a criação, você será solicitado a:

1. Nome do projeto - Nome da pasta que será criada
2. Diretório existente - Se o diretório já existir, será perguntado se deseja sobrescrever
3. Nome do pacote (package.json) - Nome válido para o npm (opcional)
4. Template - Escolha o template inicial (React + TypeScript)

Navegação Pós-Criação

cd meu-app           # Entre no projeto
pnpm install         # Instale as dependências
pnpm dev             # Inicie o desenvolvimento

📁 Estrutura do Projeto

Após criar um novo projeto, você terá a seguinte estrutura:

meu-app/
├── electron/                    # Processo Principal (Main Process)
│   ├── main.ts                 # Entry point do Electron
│   ├── preload.ts              # Script de preload (comunicação segura)
│   ├── electron-env.d.ts       # Tipos TypeScript
│   ├── electron-builder.json5  # Configuração do Electron Builder
│   └── public/                 # Arquivos públicos do Electron
│       ├── icon.ico           # Ícone Windows
│       ├── icon.png            # Ícone Linux
│       └── icon.icns           # Ícone macOS
│
├── src/                        # Processo de Renderização (Renderer)
│   ├── App.tsx                 # Componente principal React
│   ├── App.css                 # Estilos do App
│   ├── main.tsx                # Entry point React
│   ├── globals.css             # Estilos globais
│   ├── index.css               # Estilos base
│   └── assets/                 # Assets do React
│       └── react.svg           # Logo React
│
├── public/                     # Arquivos públicos
│   └── vite.svg                # Favicon
│
├── dist/                       # Build de produção (renderer)
├── dist-electron/              # Build de produção (main/preload)
├── release/                    # Executáveis gerados
│
├── index.html                  # HTML principal
├── package.json                # Dependências e scripts
├── tsconfig.json               # Configuração TypeScript
├── vite.config.ts              # Configuração Vite
├── electron-builder.json5       # Configuração Electron Builder
└── .gitignore                 # Arquivos ignorados pelo Git

🧠 Arquitetura

Este projeto utiliza a arquitetura multi-process do Electron, separando claramente as responsabilidades:

┌─────────────────────────────────────────────────────────────┐
│                      Aplicação Electron                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────────┐         ┌──────────────────────────┐  │
│  │   Main Process   │         │     Renderer Process     │  │
│  │                  │         │                          │  │
│  │  • Janelas       │◄───────►│  • Interface React      │  │
│  │  • Menu          │   IPC   │  • UI/UX               │  │
│  │  • Tray          │         │  • Lógica de apresentação│  │
│  │  • Sistema       │         │                          │  │
│  └──────────────────┘         └──────────────────────────┘  │
│                                                              │
│  ┌──────────────────┐                                       │
│  │  Preload Script  │  Ponte de comunicação segura         │
│  │  (contextBridge) │  Expõe APIs específicas ao renderer  │
│  └──────────────────┘                                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Main Process (electron/main.ts)

O processo principal controla:

• Ciclo de vida da aplicação
• Criação e gerenciamento de janelas
• Acesso ao sistema de arquivos
• Integração com sistema operacional
• Menus e diálogos nativos

Renderer Process (src/)

O processo de renderização é onde vive sua interface:

• Componentes React
• Estilos CSS
• Lógica de UI/UX
• Comunicação via IPC

Preload Script (electron/preload.ts)

O preload é a ponte segura entre os dois processos:

• Expõe apenas APIs necessárias
• Mantém o contexto isolado
• Permite comunicação controlada

🔐 Segurança

O template implementa as melhores práticas de segurança do Electron:

Configurações Aplicadas

// electron/main.ts
webPreferences: {
  preload: path.join(__dirname, 'preload.mjs'),
  contextIsolation: true,      // ✅ Isola o contexto
  nodeIntegration: false,    // ✅ Sem acesso direto ao Node
  sandbox: true,              // ✅ Sandbox ativado
}

O que cada configuração faz:

| Configuração | Descrição | Por que é importante | |-------------|-----------|---------------------| | contextIsolation: true | Isola o contexto do renderer | Previne acesso não autorizado ao contexto principal | | nodeIntegration: false | Desabilita require() no renderer | Impede que código malicioso acesse APIs do Node | | sandbox: true | Ativa sandbox do Chromium | Adiciona camada extra de proteção |

IPC Seguro

A comunicação entre processos é feita via contextBridge:

// electron/preload.ts
contextBridge.exposeInMainWorld('electronAPI', {
  openExternal: (url: string) => ipcRenderer.invoke('open-external', url),
})

No main process:

import { ipcMain, shell } from 'electron'

ipcMain.handle('open-external', async (_, url: string) => {
  await shell.openExternal(url)
})

No renderer:

window.electronAPI.openExternal('https://exemplo.com')

🧪 Desenvolvimento

Scripts Disponíveis

pnpm dev        # Inicia o desenvolvimento com hot reload
pnpm build      # Gera build de produção
pnpm test       # Executa os testes (inclui build automático)
pnpm preview    # Visualiza o build de produção
pnpm watch      # Watch mode para build

Fluxo de Desenvolvimento

1. Inicie o servidor de desenvolvimento:

   pnpm dev

2. O Electron abrirá automaticamente com hot reload ativado.

3. Edite os arquivos em src/ para ver as alterações em tempo real.

4. Edite arquivos do Electron em electron/ para alterar o comportamento da aplicação.

Hot Reload

• React (src/): Atualização automática ao salvar
• CSS: Atualização automática ao salvar
• Main Process: Reinicialização automática ao alterar arquivos em electron/

📦 Build

Build do Projeto

pnpm build

Este comando:

1. Executa TypeScript check
2. Faz o build do Vite (renderer)
3. Faz o bundle do Electron (main/preload)
4. Gera os arquivos em dist/ e dist-electron/

Saída do Build

dist/                  # Build do renderer (Vite)
├── index.html
├── assets/
└── ...

dist-electron/         # Build do Electron
├── main.js
└── preload.mjs

🖥️ Gerar Executáveis

O Electron Builder empacota sua aplicação para diferentes plataformas:

pnpm build

Este comando gera executáveis para:

| Plataforma | Formato | Local | |-----------|---------|-------| | Windows | NSIS (.exe) | release/win-unpacked/ | | macOS | DMG (.dmg) | release/ | | Linux | AppImage (.AppImage) | release/ |

Configuração do Build

Edite electron-builder.json5 para personalizar:

{
  "appId": "com.seu-app.id",
  "productName": "Seu App",
  "directories": {
    "output": "release"
  },
  "win": {
    "target": ["nsis"]
  },
  "mac": {
    "target": ["dmg"]
  },
  "linux": {
    "target": ["AppImage"]
  }
}

🛠️ Configuração

Variáveis de Ambiente

| Variável | Descrição | Padrão | |----------|-----------|--------| | NODE_ENV | Ambiente (development/production) | development | | VITE_DEV_SERVER_URL | URL do servidor Vite (dev) | - |

TypeScript

O projeto usa TypeScript strict mode. Edite tsconfig.json para ajustar:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext"
  }
}

Vite

Edite vite.config.ts para personalizar o build:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import electron from 'vite-plugin-electron/simple'

export default defineConfig({
  plugins: [
    react(),
    electron({
      main: { entry: 'electron/main.ts' },
      preload: { input: 'electron/preload.ts' },
    }),
  ],
})

🤝 Contribuição

Contribuições são bem-vindas! Para contribuir:

1. Fork o repositório
2. Crie uma branch para sua feature: git checkout -b feature/nova-feature
3. Commit suas mudanças: git commit -m 'feat: adiciona nova feature'
4. Push para a branch: git push origin feature/nova-feature
5. Abra um Pull Request

Development Setup

# Clone o repositório
git clone https://github.com/joaomjbraga/vite-electron-app.git
cd electron-vite-starter

# Instale dependências
pnpm install

# Execute os testes
pnpm test

# Faça o build
pnpm build

📜 Licença

Este projeto está sob a licença MIT.

👤 Autor

João Braga

• GitHub: @joaomjbraga