@holix/electron

Electron 进程管理器,用于启动、停止和管理 Electron 应用进程。

特性

• ✅ 使用用户项目的 Electron - 自动查找用户 node_modules 中的 Electron,不捆绑 Electron
• 🎯 灵活的进程配置 - 支持自定义环境变量、命令参数
• 🔄 进程生命周期管理 - 启动、停止、重启
• 📝 完整的类型支持 - TypeScript 类型定义
• 🎨 控制台输出 - 可选的 stdio 继承

安装

pnpm add @holix/electron

注意: 你需要在项目中安装 Electron:

pnpm add electron -D

使用

基础用法

import { ElectronProcess } from '@holix/electron'

// 创建 Electron 进程管理器
const electronProcess = new ElectronProcess({
  entry: 'dist/main/main.js', // Electron 主进程入口
  env: {
    NODE_ENV: 'development'
  },
  args: ['--no-sandbox']
})

// 启动进程
await electronProcess.start()

// 停止进程
await electronProcess.stop()

// 重启进程
await electronProcess.restart()

便捷函数

import { startElectron } from '@holix/electron'

// 快速启动
const electronProcess = await startElectron({
  entry: 'dist/main/main.js',
  env: { NODE_ENV: 'development' }
})

进程生命周期回调

const electronProcess = new ElectronProcess({
  entry: 'dist/main/main.js',

  // 进程退出回调
  onExit: (code) => {
    console.log(`Electron exited with code ${code}`)
  },

  // 进程错误回调
  onError: (error) => {
    console.error('Electron error:', error)
  }
})

await electronProcess.start()

完整配置

const electronProcess = new ElectronProcess({
  // 必需: 主进程入口文件
  entry: 'dist/main/main.js',

  // 可选: 工作目录 (默认: process.cwd())
  cwd: '/path/to/project',

  // 可选: 环境变量 (会与 process.env 合并)
  env: {
    NODE_ENV: 'development',
    DEBUG: '*'
  },

  // 可选: Electron CLI 参数
  args: [
    '--no-sandbox',
    '--disable-gpu',
    '--remote-debugging-port=9222'
  ],

  // 可选: 是否在控制台输出 (默认: true)
  stdio: true,

  // 可选: 进程退出回调
  onExit: (code) => {
    console.log(`Process exited: ${code}`)
  },

  // 可选: 进程错误回调
  onError: (error) => {
    console.error('Process error:', error)
  }
})

API

ElectronProcess

Electron 进程管理器类。

构造函数

new ElectronProcess(options: ElectronProcessOptions)

方法

start(): Promise<void>

启动 Electron 进程。

await electronProcess.start()

stop(): Promise<void>

停止 Electron 进程。发送 SIGTERM 信号,如果失败则强制 SIGKILL。

await electronProcess.stop()

restart(): Promise<void>

重启 Electron 进程。先停止,等待 100ms,再启动。

await electronProcess.restart()

isRunning(): boolean

检查进程是否在运行。

if (electronProcess.isRunning()) {
  console.log('Electron is running')
}

getPid(): number | undefined

获取进程 PID。

const pid = electronProcess.getPid()
console.log(`Electron PID: ${pid}`)

startElectron(options): Promise<ElectronProcess>

便捷函数,创建并启动 Electron 进程。

const electronProcess = await startElectron({
  entry: 'dist/main/main.js'
})

ElectronProcessOptions

interface ElectronProcessOptions {
  /** Electron 主进程入口文件路径 */
  entry: string

  /** 工作目录 (默认: process.cwd()) */
  cwd?: string

  /** 环境变量 (会与 process.env 合并) */
  env?: Record<string, string>

  /** Electron CLI 参数 */
  args?: string[]

  /** 是否在控制台输出日志 (默认: true) */
  stdio?: boolean

  /** 进程退出回调 */
  onExit?: (code: number | null) => void

  /** 进程错误回调 */
  onError?: (error: Error) => void
}

与 Holix CLI 集成

在 Holix 开发模式中使用:

import { build } from '@holix/builder'
import { startElectron } from '@holix/electron'

// 构建主进程
await build(config, packageJson)

// 启动 Electron
const electronProcess = await startElectron({
  entry: 'dist/main/main.js',
  env: {
    NODE_ENV: 'development'
  }
})

// 监听文件变化,重启 Electron
watcher.on('change', async () => {
  await build(config, packageJson)
  await electronProcess.restart()
})

工作原理

1. 查找 Electron: 从用户项目的 node_modules/electron 中查找 Electron 可执行文件
2. 启动进程: 使用 execa 启动 Electron 进程
3. 环境变量: 合并 process.env 和用户提供的环境变量
4. stdio 继承: 可选择继承父进程的 stdio,显示 Electron 输出
5. 信号处理: 正确处理 SIGTERM 和 SIGKILL 信号

注意事项

• 确保用户项目已安装 Electron
• 入口文件路径是相对于 cwd 的
• stdio: false 时不会显示 Electron 的输出
• 进程会在 onExit 回调后自动清理

License

MIT