vue-cli-plugin-electron-haunv 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# vite-plugin-electron-builder
+
+> Easily Build Your Vue 3 + Vite App For Desktop With Electron
+
+[![Node CI](https://github.com/your-username/vite-plugin-electron-builder/actions/workflows/nodeCI.yml/badge.svg)](https://github.com/your-username/vite-plugin-electron-builder/actions/workflows/nodeCI.yml)
+[![npm version](https://img.shields.io/npm/v/vite-plugin-electron-builder.svg)](https://www.npmjs.com/package/vite-plugin-electron-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+A modern replacement for `vue-cli-plugin-electron-builder`, built on top of **Vite 8**, **Electron 41**, and **electron-builder 26**. All dependencies are kept at their latest versions.
+
+---
+
+## ✨ Features
+
+- ⚡ **Vite-native** — instant HMR for the renderer process
+- 🔄 **Auto-restart** — watches your main process files and restarts Electron on change
+- 🔒 **Secure by default** — custom `app://` protocol with path traversal protection, context isolation enabled
+- 🛠 **esbuild** — fast TypeScript/ESM compilation for the main process
+- 🎭 **Playwright** — built-in E2E test helper for Electron windows
+- 📦 **electron-builder** — full packaging for Linux, macOS, and Windows
+- 🖥 **CLI** — scaffold a new project with one command
+
+---
+
+## Quick Start
+
+### Scaffold a new project
+
+```bash
+npx vite-plugin-electron-builder my-app
+cd my-app
+npm run electron:serve
+```
+
+### Add to an existing Vite + Vue project
+
+```bash
+npm install -D vite-plugin-electron-builder electron electron-builder esbuild
+```
+
+Then update your `vite.config.js`:
+
+```js
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { createElectronPlugin } from 'vite-plugin-electron-builder'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    createElectronPlugin({
+      mainProcessFile: 'src/background.js',
+      outputDir: 'dist_electron',
+    }),
+  ],
+})
+```
+
+Add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "electron:serve": "vite-electron serve",
+    "electron:build": "vite build && vite-electron build"
+  }
+}
+```
+
+---
+
+## Project Structure
+
+After scaffolding, your project will look like this:
+
+```
+my-app/
+├── src/
+│   ├── App.vue          # Vue renderer component
+│   ├── main.js          # Renderer entry point
+│   ├── background.js    # Electron main process ← edit this
+│   └── preload.js       # Preload script (contextBridge)
+├── tests/
+│   └── e2e/
+│       └── app.spec.js  # Playwright E2E tests
+├── index.html
+├── vite.config.js
+└── package.json
+```
+
+---
+
+## Plugin Options
+
+```ts
+interface ElectronBuilderOptions {
+  /** Electron main process entry file. Default: 'src/background.js' */
+  mainProcessFile?: string
+
+  /** Output dir for compiled main process. Default: 'dist_electron' */
+  outputDir?: string
+
+  /** Preload script path. Optional. */
+  preload?: string
+
+  /** Enable Node integration in renderer. Default: false */
+  nodeIntegration?: boolean
+
+  /** Enable context isolation. Default: true */
+  contextIsolation?: boolean
+
+  /** Custom protocol scheme name. Default: 'app' */
+  customFileProtocol?: string
+
+  /** Extra Electron CLI flags for development. */
+  electronCliArgs?: string[]
+
+  /** electron-builder config overrides. */
+  builderOptions?: import('electron-builder').Configuration
+
+  /** Native modules to externalize from the bundle. */
+  externals?: string[]
+}
+```
+
+---
+
+## Development
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `npm run electron:serve` | Start Vite dev server + Electron |
+| `npm run electron:build` | Build renderer + package with electron-builder |
+| `npm test` | Run Jest unit tests |
+| `npm run test:e2e` | Run Playwright E2E tests |
+| `npm run lint` | ESLint |
+
+### How it works
+
+**Development (`electron:serve`)**
+
+1. Vite starts its dev server (default `:8080`)
+2. The plugin compiles `src/background.js` with esbuild → `dist_electron/main.js`
+3. Electron is launched pointing at the Vite dev server URL
+4. chokidar watches `src/background.js` (and preload) — on change, recompiles and restarts Electron
+
+**Production (`electron:build`)**
+
+1. Vite builds the renderer to `dist/`
+2. esbuild compiles and bundles the main process to `dist_electron/main.js`
+3. electron-builder packages everything into a distributable (`.dmg`, `.exe`, `.AppImage`, etc.)
+
+---
+
+## Security
+
+This plugin follows Electron security best practices:
+
+- **Context isolation** is enabled by default (`contextIsolation: true`)
+- **Node integration** is disabled by default in the renderer
+- The custom `app://` protocol prevents path traversal attacks
+- The preload template uses `contextBridge` to expose only whitelisted APIs
+
+---
+
+## API Reference
+
+### `createElectronPlugin(options?)`
+
+Returns a Vite plugin. Add it to the `plugins` array in `vite.config.js`.
+
+### `createProtocol(scheme, basePath?)`
+
+Registers a secure Electron file protocol. Import in your main process:
+
+```js
+import { createProtocol } from 'vite-plugin-electron-builder/lib/protocol'
+
+app.whenReady().then(() => {
+  createProtocol('app')
+  win.loadURL('app://./index.html')
+})
+```
+
+### `testWithPlaywright(options?)`
+
+Launches Electron with Playwright for E2E tests:
+
+```js
+import { testWithPlaywright } from 'vite-plugin-electron-builder'
+
+let app, page, stop
+
+beforeAll(async () => {
+  ;({ app, page, stop } = await testWithPlaywright({
+    appPath: 'dist_electron/main.js',
+  }))
+})
+
+afterAll(() => stop())
+
+test('renders app', async () => {
+  const el = await page.$('#app')
+  expect(el).not.toBeNull()
+})
+```
+
+---
+
+## Package Versions
+
+All dependencies are pinned to their latest major versions:
+
+| Package | Version |
+|---|---|
+| `electron` | ^41.0.2 |
+| `electron-builder` | ^26.8.1 |
+| `vite` | ^8.0.0 |
+| `@vitejs/plugin-vue` | ^6.0.5 |
+| `esbuild` | ^0.27.4 |
+| `@playwright/test` | ^1.58.2 |
+| `chalk` | ^5.6.2 |
+| `chokidar` | ^5.0.0 |
+| `commander` | ^14.0.3 |
+| `execa` | ^9.6.1 |
+| `fs-extra` | ^11.3.4 |
+| `semver` | ^7.7.4 |
+| `concurrently` | ^9.2.1 |
+| `wait-on` | ^9.0.4 |
+
+---
+
+## Migrating from vue-cli-plugin-electron-builder
+
+| vue-cli-plugin | vite-plugin-electron-builder |
+|---|---|
+| `vue add electron-builder` | `npx vite-plugin-electron-builder my-app` |
+| `vue-cli-service electron:serve` | `vite-electron serve` |
+| `vue-cli-service electron:build` | `vite-electron build` |
+| `vue.config.js` plugin options | `vite.config.js` `createElectronPlugin({})` |
+| `background.js` | `src/background.js` (unchanged) |
+| `createProtocol` | `import { createProtocol } from 'vite-plugin-electron-builder/lib/protocol'` |
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+'use strict'
+
+const { program } = require('commander')
+const path = require('path')
+const chalk = require('chalk')
+const pkg = require('../package.json')
+
+program
+  .name('vite-electron')
+  .description('Vite Plugin Electron Builder CLI')
+  .version(pkg.version)
+
+program
+  .command('serve')
+  .description('Start the Electron development server')
+  .option('--main <file>', 'Path to main process file', 'src/background.js')
+  .option('--out <dir>', 'Output directory', 'dist_electron')
+  .action(async (opts) => {
+    const { createServer } = require('vite')
+    const { serveElectron } = require('../lib/build')
+
+    console.log(chalk.cyan('\n🚀 Starting Vite + Electron dev server...\n'))
+
+    try {
+      // Start Vite dev server
+      const viteServer = await createServer({
+        base: './',
+        server: { port: 8080 }
+      })
+      await viteServer.listen()
+      viteServer.printUrls()
+
+      // Start Electron in watch mode
+      const { stop } = await serveElectron({
+        mainProcessFile: opts.main,
+        outputDir: opts.out
+      })
+
+      // Handle graceful shutdown
+      const shutdown = async () => {
+        console.log(chalk.yellow('\n[electron-builder] Shutting down...'))
+        await stop()
+        await viteServer.close()
+        process.exit(0)
+      }
+
+      process.on('SIGINT', shutdown)
+      process.on('SIGTERM', shutdown)
+    } catch (err) {
+      console.error(chalk.red('[electron-builder] Serve failed:'), err)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('build')
+  .description('Build the app for production')
+  .option('--main <file>', 'Path to main process file', 'src/background.js')
+  .option('--out <dir>', 'Output directory', 'dist_electron')
+  .option('--platform <platform>', 'Target platform (linux|mac|win)')
+  .action(async (opts) => {
+    const { buildElectron } = require('../lib/build')
+
+    console.log(chalk.cyan('\n📦 Building for production...\n'))
+
+    try {
+      await buildElectron({
+        mainProcessFile: opts.main,
+        outputDir: opts.out,
+        builderOptions: opts.platform
+          ? { [opts.platform]: {} }
+          : {}
+      })
+    } catch (err) {
+      console.error(chalk.red('[electron-builder] Build failed:'), err)
+      process.exit(1)
+    }
+  })
+
+program.parse(process.argv)
+
+// Show help if no command given
+if (!process.argv.slice(2).length) {
+  program.outputHelp()
+}

package/generator/template/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!-- Required for Electron security -->
+    <meta http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';" />
+    <title>Vue 3 + Vite + Electron</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/generator/template/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "my-electron-vue-app",
+  "version": "0.1.0",
+  "description": "A Vue 3 + Vite + Electron desktop application",
+  "main": "dist_electron/main.js",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "electron:serve": "vite-electron serve",
+    "electron:build": "vite build && vite-electron build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.5",
+    "electron": "^41.0.2",
+    "electron-devtools-installer": "^4.0.0",
+    "vite": "^8.0.0",
+    "vite-plugin-electron-builder": "^1.0.0"
+  }
+}

package/generator/template/src/App.vue

@@ -0,0 +1,125 @@
+<template>
+  <div id="app">
+    <header class="app-header">
+      <img src="./assets/logo.svg" alt="Vue + Electron" class="logo" />
+      <h1>Vue 3 + Vite + Electron</h1>
+    </header>
+
+    <main class="app-main">
+      <p class="tagline">
+        Edit <code>src/App.vue</code> and save to see hot-reload in action.
+      </p>
+
+      <div class="info-cards">
+        <div class="card">
+          <h2>⚡ Vite</h2>
+          <p>Lightning-fast HMR during development.</p>
+        </div>
+        <div class="card">
+          <h2>🖥 Electron</h2>
+          <p>Cross-platform desktop apps with web tech.</p>
+        </div>
+        <div class="card">
+          <h2>💚 Vue 3</h2>
+          <p>Composition API, TypeScript, and more.</p>
+        </div>
+      </div>
+
+      <p class="version">Electron API available: {{ hasElectronAPI ? '✅' : '❌' }}</p>
+    </main>
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const hasElectronAPI = ref(false)
+
+onMounted(() => {
+  hasElectronAPI.value = typeof window.electronAPI !== 'undefined'
+})
+</script>
+
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  background: #0d1117;
+  color: #c9d1d9;
+  min-height: 100vh;
+}
+
+#app {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 40px 20px;
+  gap: 32px;
+}
+
+.app-header {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+}
+
+.logo { width: 80px; height: 80px; }
+
+h1 {
+  font-size: 2rem;
+  font-weight: 700;
+  background: linear-gradient(135deg, #42b883, #35495e);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+
+.tagline {
+  font-size: 1.1rem;
+  color: #8b949e;
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.tagline code {
+  background: #161b22;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-family: monospace;
+  color: #58a6ff;
+}
+
+.info-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 20px;
+  width: 100%;
+  max-width: 700px;
+}
+
+.card {
+  background: #161b22;
+  border: 1px solid #30363d;
+  border-radius: 12px;
+  padding: 24px;
+  text-align: center;
+}
+
+.card h2 { font-size: 1.3rem; margin-bottom: 8px; }
+.card p { color: #8b949e; font-size: 0.95rem; }
+
+.version {
+  margin-top: 16px;
+  font-size: 0.9rem;
+  color: #8b949e;
+}
+
+.app-main {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  width: 100%;
+  max-width: 800px;
+}
+</style>

package/generator/template/src/background.js

@@ -0,0 +1,88 @@
+'use strict'
+
+import { app, protocol, BrowserWindow } from 'electron'
+import { createProtocol } from 'vite-plugin-electron-builder/lib/protocol'
+import installExtension, { VUEJS_DEVTOOLS } from 'electron-devtools-installer'
+import path from 'path'
+
+const isDevelopment = process.env.NODE_ENV !== 'production'
+
+// Register the custom protocol before app is ready (required for security)
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: 'app',
+    privileges: {
+      secure: true,
+      standard: true
+    }
+  }
+])
+
+let win
+
+async function createWindow() {
+  win = new BrowserWindow({
+    width: 800,
+    height: 600,
+    webPreferences: {
+      // NOTE: Do NOT enable nodeIntegration in production for security
+      nodeIntegration: process.env.ELECTRON_NODE_INTEGRATION === 'true',
+      contextIsolation: !process.env.ELECTRON_NODE_INTEGRATION,
+      preload: path.join(__dirname, 'preload.js') // optional
+    }
+  })
+
+  if (isDevelopment) {
+    // Load from Vite dev server
+    await win.loadURL(process.env.VITE_DEV_SERVER_URL || 'http://localhost:8080')
+    win.webContents.openDevTools()
+  } else {
+    // Use custom protocol for production
+    createProtocol('app')
+    await win.loadURL('app://./index.html')
+  }
+
+  win.on('closed', () => {
+    win = null
+  })
+}
+
+// Install Vue Devtools in development
+app.whenReady().then(async () => {
+  if (isDevelopment && !process.env.IS_TEST) {
+    try {
+      await installExtension(VUEJS_DEVTOOLS)
+    } catch (e) {
+      console.error('Vue Devtools failed to install:', e.toString())
+    }
+  }
+  await createWindow()
+})
+
+// Quit when all windows are closed (except on macOS)
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit()
+  }
+})
+
+app.on('activate', () => {
+  if (win === null) {
+    createWindow()
+  }
+})
+
+// Exit cleanly in development mode
+if (isDevelopment) {
+  if (process.platform === 'win32') {
+    process.on('message', (data) => {
+      if (data === 'graceful-exit') {
+        app.quit()
+      }
+    })
+  } else {
+    process.on('SIGTERM', () => {
+      app.quit()
+    })
+  }
+}

package/generator/template/src/main.js

@@ -0,0 +1,4 @@
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')

package/generator/template/src/preload.js

@@ -0,0 +1,31 @@
+'use strict'
+
+/**
+ * Preload script - runs in a privileged context before the renderer.
+ * Use contextBridge to safely expose APIs to the renderer.
+ *
+ * Docs: https://www.electronjs.org/docs/latest/tutorial/context-isolation
+ */
+const { contextBridge, ipcRenderer } = require('electron')
+
+// Expose a safe API to the renderer process via window.electronAPI
+contextBridge.exposeInMainWorld('electronAPI', {
+  // Example: send a message to the main process
+  sendMessage: (channel, data) => {
+    const allowedChannels = ['app:minimize', 'app:maximize', 'app:close', 'app:ready']
+    if (allowedChannels.includes(channel)) {
+      ipcRenderer.send(channel, data)
+    }
+  },
+
+  // Example: receive a message from the main process
+  onMessage: (channel, callback) => {
+    const allowedChannels = ['app:update-available', 'app:update-downloaded']
+    if (allowedChannels.includes(channel)) {
+      ipcRenderer.on(channel, (_event, ...args) => callback(...args))
+    }
+  },
+
+  // Expose app version
+  getVersion: () => ipcRenderer.invoke('app:get-version'),
+})

package/generator/template/vite.config.js

@@ -0,0 +1,36 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { createElectronPlugin } from 'vite-plugin-electron-builder'
+import path from 'path'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    vue(),
+    createElectronPlugin({
+      // Path to Electron main process entry
+      mainProcessFile: 'src/background.js',
+
+      // Output directory for compiled main process
+      outputDir: 'dist_electron',
+
+      // Optional: path to preload script
+      preload: 'src/preload.js',
+
+      // Optional: electron-builder overrides
+      builderOptions: {
+        appId: 'com.example.myapp',
+        productName: 'My Vue Electron App',
+        linux: { target: ['AppImage', 'deb'] },
+        win: { target: ['nsis'] },
+        mac: { target: ['dmg'] },
+      },
+    }),
+  ],
+
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+    },
+  },
+})