@tomjs/vite-plugin-electron v1.9.0

@tomjs/vite-plugin-electron

English | 中文

一个简单的 electron vite 插件，支持 esm 和 cjs

非常感谢 caoxiemeihao 的 vite-plugin-electron 和 Doubleshotjs 的 doubleshot 这两个优秀库给了我启发。我希望使用它能简化开发配置，只关注业务开发。

特性

• 使用 tsup 快速构建 main 和 preload
• 配置简单，专注业务
• 支持 main 的 热重启
• 支持 preload 的 热重载
• 支持 esm 和 cjs ，你可以在 electron v28+ 中使用 esm
• 支持 vue 和 react 等其他 vite 支持的框架
• 可选 electron-builder 简单配置打包

安装

# pnpm
pnpm add @tomjs/vite-plugin-electron -D

# yarn
yarn add @tomjs/vite-plugin-electron -D

# npm
npm i @tomjs/vite-plugin-electron --save-dev

如果使用 builder 打包应用，请安装 electron-builder

# pnpm
pnpm add electron-builder -D

# yarn
yarn add electron-builder -D

# npm
npm i electron-builder --save-dev

使用说明

推荐约定

目录结构

• 推荐 electron 和 页面 src 代码目录结构

|--electron
|  |--main        // main process code
|  |  |--index.ts
|  |--preload     // preload process code
|  |  |--index.ts
|  |--build       // electron-builder resources for electron package
|  |  |--icons
|--src            // front-end code
|  |--App.vue
|  |--main.ts

• 零配置，默认 dist 输出目录

|--dist
|  |--main
|  |  |--index.js
|  |  |--index.js.map
|  |--preload
|  |  |--index.js
|  |  |--index.js.map
|  |--renderer
|  |  |--index.html

默认配置和行为

详细查看 PluginOptions 和 recommended 参数说明

electron

electron/main/index.ts

import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { app, BrowserWindow } from 'electron';

// when package.json "type": module"
global.__dirname = dirname(fileURLToPath(import.meta.url));

const preload = join(__dirname, '../preload/index.mjs');
const url = process.env.VITE_DEV_SERVER_URL;

async function createWindow() {
  win = new BrowserWindow({
    title: 'Main window',
    width: 800,
    height: 700,
    webPreferences: {
      preload,
      nodeIntegration: true,
      contextIsolation: false,
    },
  });

  if (isDev) {
    win.loadURL(url);
  } else {
    win.loadFile(indexHtml);
  }
}

app.whenReady().then(createWindow);

vue

以使用 esm 为例，不过要求 Electron>=28

• package.json

Electron preload process 必须使用 .mjs 后缀，否则报错，查看官方文档。所以 preload 的 esm 默认输出使用 mjs 后缀。为了保持一致性，main process 也以 .mjs 结尾。

{
  "type": "module",
  "main": "dist/main/index.mjs"
}

• vite.config.ts

import { defineConfig } from 'vite';
// import renderer from 'vite-plugin-electron-renderer'; // 启用 nodeIntegration
import electron from '@tomjs/vite-plugin-electron';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [
    vue(),
    // 如使用约定的目录结构，则不需要配置
    electron(),
    // 如果自定义了目录结构，则必须根据实际情况赋值
    // electron({
    //   main: {
    //     entry: 'electron/main/index.ts',
    //   },
    //   preload: {
    //     entry: 'electron/preload/index.ts',
    //   },
    // }),
    // renderer(),
  ],
});

react

以使用 cjs 为例

• package.json

{
  // "type": "commonjs",
  "main": "dist/main/index.js"
}

• vite.config.ts

import { defineConfig } from 'vite';
import electron from '@tomjs/vite-plugin-electron';
import react from '@vitejs/plugin-react-swc';

export default defineConfig({
  plugins: [react(), electron()],
});

文档

• paka.dev 提供的 API文档.
• unpkg.com 提供的 index.d.ts.

参数

PluginOptions

recommended 选项用于设置默认配置和行为，几乎可以达到零配置使用，默认为 true 。如果你要自定义配置，请设置它为false。以下默认的前提条件是使用推荐的 项目结构。

• 检查是否存在 electron/main/index.ts 和 electron/main/index.ts，如果有则分别给 main.entry 和 preload.entry 赋值。如果不存在，main.entry 必须主动赋值，负责会报错
• 输出目录根据 vite 的 build.outDir 参数， 将 electron/main、electron/preload、src 分别输出到 dist/main、dist/preload、dist/renderer
• 其他待实现的行为

MainOptions

继承自 tsup 的 Options，添加了一些默认值，方便使用。

PreloadOptions

继承自 tsup 的 Options，添加了一些默认值，方便使用。

BuilderOptions

当 recommended 和 builder.enable 都为 true 时，使用 electron-builder 打包 Electron 应用程序。

• 在vite中配置的build.outDir目录中，根据配置和package.json生成新的package.json，排除非依赖项。
• 执行npm install然后打包。

不适合所有人使用。

使用该功能，需要额外安装 electron-builder

默认配置如下

const config = {
  directories: {
    buildResources: 'electron/build',
    app: path.dirname(resolvedConfig.build.outDir),
    output: 'release/${version}',
  },
  files: ['main', 'preload', 'renderer'],
  artifactName: '${productName}-${version}-${os}-${arch}.${ext}',
  electronDownload: {
    // when npm registry mirror is 'registry.npmmirror.com'
    mirror: 'https://npmmirror.com/mirrors/electron',
  },
  electronLanguages: ['zh-CN', 'en-US'],
  win: {
    target: [
      {
        target: 'nsis',
        arch: ['x64'],
      },
    ],
  },
  mac: {
    target: ['dmg'],
  },
  linux: {
    target: ['zip'],
  },
  nsis: {
    oneClick: false,
    perMachine: false,
    allowToChangeInstallationDirectory: true,
    deleteAppDataOnUninstall: false,
  },
};

补充说明

• main 和 preload 未配置相关参数时的默认值

环境变量

vite 插件变量

应用变量

Electron main process 和 renderer process 使用。

调试

Web调试

使用 @tomjs/electron-devtools-installer 安装 Chrome Devtools 插件后像 Web 开发一样使用

import { app } from 'electron';

app.whenReady().then(() => {
  const { installExtension, REACT_DEVELOPER_TOOLS, REDUX_DEVTOOLS } = await import(
    '@tomjs/electron-devtools-installer'
  );

  installExtension([REACT_DEVELOPER_TOOLS, REDUX_DEVTOOLS])
    .then(exts => {
      console.log(
        'Added Extension: ',
        exts.map(s => s.name),
      );
    })
    .catch(err => {
      console.log('Failed to install extensions');
      console.error(err);
    });
});

Main Process 调试

通过 vscode 运行 Debug Main Process 调试主线程，调试工具参考 官方文档

launch.json 配置如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "preLaunchTask": "npm:debug",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": ["."],
      "outFiles": [
        "${workspaceFolder}/**/*.js",
        "${workspaceFolder}/**/*.cjs",
        "${workspaceFolder}/**/*.mjs",
        "!**/node_modules/**"
      ],
      "envFile": "${workspaceFolder}/node_modules/@tomjs/vite-plugin-electron/debug/.env"
    }
  ]
}

tasks.json 配置如下：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "npm:debug",
      "type": "npm",
      "script": "debug",
      "detail": "cross-env VITE_ELECTRON_DEBUG=1 vite",
      "isBackground": true,
      "problemMatcher": {
        "owner": "typescript",
        "fileLocation": "relative",
        "pattern": {
          "regexp": "^([a-zA-Z]\\:/?([\\w\\-]/?)+\\.\\w+):(\\d+):(\\d+): (ERROR|WARNING)\\: (.*)$",
          "file": 1,
          "line": 3,
          "column": 4,
          "code": 5,
          "message": 6
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "^.*VITE v.*  ready in \\d* ms.*$",
          "endsPattern": "^.*\\[tomjs:electron\\] startup electron*$"
        }
      }
    }
  ]
}

Preload Process 调试

使用 DevTools 调试 preload process.

示例

先执行以下命令安装依赖，并生成库文件：

pnpm install
pnpm build

打开 examples 目录，有 vue 和 react 示例。

• react
• vue