npm package: @holix/electron
Description: Electron process manager for Holix
Author: zhaogongchengsi
Latest version: 1.0.3

# @holix/electron

Electron 进程管理器,用于启动、停止和管理 Electron 应用进程。

## 特性

- ✅ **使用用户项目的 Electron** - 自动查找用户 `node_modules` 中的 Electron,不捆绑 Electron
- 🎯 **灵活的进程配置** - 支持自定义环境变量、命令参数
- 🔄 **进程生命周期管理** - 启动、停止、重启
- 📝 **完整的类型支持** - TypeScript 类型定义
- 🎨 **控制台输出** - 可选的 stdio 继承

## 安装

```bash
pnpm add @holix/electron
```

**注意**: 你需要在项目中安装 Electron:

```bash
pnpm add electron -D
```

## 使用

### 基础用法

```typescript
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()
```

### 便捷函数

```typescript
import { startElectron } from '@holix/electron'

// 快速启动
const electronProcess = await startElectron({
  entry: 'dist/main/main.js',
  env: { NODE_ENV: 'development' }
})
```

### 进程生命周期回调

```typescript
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()
```

### 完整配置

```typescript
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 进程管理器类。

#### 构造函数

```typescript
new ElectronProcess(options: ElectronProcessOptions)
```

#### 方法

##### `start(): Promise<void>`

启动 Electron 进程。

```typescript
await electronProcess.start()
```

##### `stop(): Promise<void>`

停止 Electron 进程。发送 SIGTERM 信号,如果失败则强制 SIGKILL。

```typescript
await electronProcess.stop()
```

##### `restart(): Promise<void>`

重启 Electron 进程。先停止,等待 100ms,再启动。

```typescript
await electronProcess.restart()
```

##### `isRunning(): boolean`

检查进程是否在运行。

```typescript
if (electronProcess.isRunning()) {
  console.log('Electron is running')
}
```

##### `getPid(): number | undefined`

获取进程 PID。

```typescript
const pid = electronProcess.getPid()
console.log(`Electron PID: ${pid}`)
```

### `startElectron(options): Promise<ElectronProcess>`

便捷函数,创建并启动 Electron 进程。

```typescript
const electronProcess = await startElectron({
  entry: 'dist/main/main.js'
})
```

## ElectronProcessOptions

```typescript
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 开发模式中使用:

```typescript
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