オプション詳細¶

electron(options) に渡す ElectronPluginOptions の全フィールドをまとめます。

ソースコードが source of truth です。型定義の最新版は src/types.ts を参照してください。

トップレベル構造¶

type ElectronPluginOptions = {
  main: ElectronMainOptions
  preload?: ElectronPreloadOptions
  debug?: ElectronDebugOptions | boolean
  renderer?: ElectronRendererOptions
}

main¶

type ElectronMainOptions = {
  entry: string
  vite?: UserConfig
}

entry は electron_main environment の rolldownOptions.input に使われます。

preload¶

type ElectronPreloadOptions = {
  entry: ElectronPreloadInput
  vite?: UserConfig
}

preload が 1 件以上ある場合にのみ electron_preload environment が登録されます。

preload entry の書式¶

preload entry は 3 つの形式で指定できます。プラグインは最終的に name → absolute source path の map に正規化して扱います。

文字列 1 件:

electron({
  main: { entry: 'electron/main.ts' },
  preload: { entry: 'electron/preload.ts' },
})

配列:

electron({
  main: { entry: 'electron/main.ts' },
  preload: {
    entry: [
      'electron/preload.ts',
      { name: 'settings', entry: 'electron/settings-preload.ts' },
    ],
  },
})

名前付き map:

electron({
  main: { entry: 'electron/main.ts' },
  preload: {
    entry: {
      preload: 'electron/preload.ts',
      settings: 'electron/settings-preload.ts',
    },
  },
})

文字列指定の場合、source path の basename から entry 名を推論します。

• electron/preload.ts → preload
• electron/settings-preload.ts → settings-preload

entry 名の制約¶

• 空文字は不可
• main は予約名のため不可
• / や \ を含む名前は不可
• 同じ entry 名の重複は不可

出力形式¶

preload entry は CommonJS で出力されます。

• main: [name].js（ESM）
• preload: [name].cjs（CJS）

debug¶

type ElectronDebugOptions = {
  enabled?: boolean
  host?: string
  port?: number
  break?: boolean
  rendererPort?: number
}

簡易指定¶

// boolean で有効化（全て既定値）
electron({ main: { entry: '...' }, debug: true })

// object で個別設定
electron({
  main: { entry: '...' },
  debug: { enabled: true, port: 9229, rendererPort: 9222 },
})

付与される CLI 引数¶

debug が有効な場合、Electron 起動時に次が付与されます。

• --inspect=host:port または --inspect-brk=host:port（break: true の場合）
• --remote-debugging-port=rendererPort

renderer¶

type ElectronRendererMode = 'internal' | 'external'

type ElectronRendererWaitForReadyMode = 'auto' | 'always' | 'off'

type ElectronRendererWaitForReadyOptions = {
  mode?: ElectronRendererWaitForReadyMode
  timeoutMs?: number
  intervalMs?: number
  requestTimeoutMs?: number
}

type ElectronRendererOptions = {
  mode?: ElectronRendererMode
  devUrl?: string
  devUrlEnvVar?: string
  waitForReady?: ElectronRendererWaitForReadyOptions
}

mode の自動推論¶

mode を省略した場合:

• devUrl があれば 'external'
• devUrl がなければ 'internal'

internal mode¶

プラグイン自身が起動した Vite dev server の URL を devUrlEnvVar で指定した環境変数に注入します。

external mode¶

外部の renderer dev server URL を devUrl で指定します。desktop package 側に index.html を置く必要はありません。プラグインが appType: 'custom' と空の仮想 client entry を使ってビルドを成立させます。

waitForReady を省略した場合でも、loopback の http / https URL では mode: 'auto' が有効になり、renderer dev server が応答可能になるまで Electron の初回起動と restart を待機します。タイムアウト時は Electron を起動せず、dev ログへエラーを出します。

waitForReady¶

• auto: external mode かつ loopback の http / https URL (localhost, 127.0.0.1, ::1) のときだけ待機します。
• always: external mode の http / https URL なら host に関係なく待機します。
• off: 起動待機を無効にします。

到達確認は HEAD 優先で行い、405 / 501 のように HEAD 非対応なサーバーには GET へフォールバックします。

electron({
  main: { entry: 'src/main.ts' },
  renderer: {
    mode: 'external',
    devUrl: 'http://localhost:5173',
    devUrlEnvVar: 'ELECTRON_RENDERER_URL',
    waitForReady: {
      mode: 'auto',
      timeoutMs: 30_000,
    },
  },
})

ビルド共通設定¶

main と preload の両方に適用されるビルド設定の既定値:

プラグインが固定する項目（ユーザーが上書きできない）:

• rolldownOptions.input — entry 解決はプラグインの責務
• output.entryFileNames — main: [name].js, preload: [name].cjs
• output.format — main: ESM, preload: CJS

main.vite / preload.vite によるオーバーライド¶

main.vite や preload.vite で UserConfig を渡すと、対応する environment のビルド設定をオーバーライドできます。ただし、プラグインが固定する項目（entry, format, entryFileNames）は configEnvironment フックの最後に再適用されるため、上書きされません。

Exported Types¶

@srymh/vite-plugin-electron から import できる型:

• ElectronPluginOptions — トップレベルオプション
• ElectronMainOptions — main 設定
• ElectronPreloadOptions — preload 設定
• ElectronPreloadEntry — 単一 preload entry（string or object）
• ElectronPreloadEntryMap — name → source path map
• ElectronPreloadInput — preload entry の union 型
• ElectronDebugOptions — debug 設定
• ElectronRendererMode — 'internal' | 'external'
• ElectronRendererOptions — renderer 設定