Awesome

@tomjs/vite-plugin-electron

English | 中文

A Simple vite plugin for electron, supports esm and cjs.

Many thanks to caoxiemeihao's vite-plugin-electron and Doubleshotjs's doubleshot These two excellent libraries inspired me. I hope to use it to simplify development configuration and focus only on business development.

Features

• Fast build main and preload with tsup
• Little configuration, focus on business
• Support main's Hot Restart
• Support preload's Hot Reload
• Support esm and cjs, you can use esm in electron v28+
• Support vue and react and other frameworks supported by vite
• Optional electron-builder Simple configuration

Install

# 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

If you use builder to package your application, please install electron-builder

# pnpm
pnpm add electron-builder -D

# yarn
yarn add electron-builder -D

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

Usage

Recommended Agreement

Directory Structure

• Recommend electron and page src code directory structure

|--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

• Zero configuration, default dist output directory

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

Default configuration and behavior

See PluginOptions and recommended parameter descriptions in detail

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

Take using esm as an example, but it requires Electron>=28

• package.json

Electron preload process must use the .mjs suffix, otherwise an error will be reported, see official documentation. So the default output of esm of preload uses the .mjs suffix. For consistency, main process also ends with .mjs

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

• vite.config.ts

import { defineConfig } from 'vite';
// import renderer from 'vite-plugin-electron-renderer'; // Enable nodeIntegration
import electron from '@tomjs/vite-plugin-electron';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
  plugins: [
    vue(),
    // If you use the agreed directory structure, no configuration is required
    electron(),
    // If the directory structure is customized, the value must be assigned according to the actual situation
    // electron({
    //   main: {
    //     entry: 'electron/main/index.ts',
    //   },
    //   preload: {
    //     entry: 'electron/preload/index.ts',
    //   },
    // }),
    // renderer(),
  ],
});

react

Take using cjs as an example

• 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()],
});

Documentation

• index.d.ts provided by unpkg.com.

Parameters

PluginOptions

Notice

The recommended option is used to set the default configuration and behavior, which can be used with almost zero configuration. The default is true. If you want to customize the configuration, set it to false. The following default prerequisites are to use the recommended project structure.

• Check whether electron/main/index.ts and electron/main/index.ts exist, and if so, assign values to main.entry and preload.entry respectively. If it does not exist, main.entry must be actively assigned, and an error will be reported.
• The output directory is based on the build.outDir parameter of vite, and outputs electron/main, electron/preload and src to dist/main, dist/preload and dist/renderer respectively.
• Other behaviors to be implemented

MainOptions

Based on Options of tsup, some default values are added for ease of use.

PreloadOptions

Based on Options of tsup, some default values are added for ease of use.

BuilderOptions

When recommended and builder.enable are both true, use electron-builder to package Electron applications.

• In the build.outDir directory configured in vite, generate a new package.json based on the configuration and package.json, excluding non-dependencies.
• Execute npm install and then package.

Not suitable for everyone.

To use this function, you need to install additional electron-builder

The default configuration is as follows:

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,
  },
};

Additional Information

• Default values for main and preload when the relevant parameters are not configured

Environment Variables

Vite plugin variables

Application variables

Electron main process and renderer process use.

Debug

Web debugging

Use @tomjs/electron-devtools-installer to install the Chrome Devtools plugins and use it like web development

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 Debug

Run Debug Main Process through vscode to debug the main thread. For debugging tools, refer to Official Documentation

launch.json is configured as follows:

{
  "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 is configured as follows:

{
  "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 Debug

Use DevTools to debug the preload process.

Examples

First execute the following command to install dependencies and generate library files:

pnpm install
pnpm build

Open the examples directory, there are vue and react examples.

• react
• vue