vite-electron-plugin

vite-electron-plugin

High-performance, esbuild-based Vite Electron plugin

• 🚀 High-performance _{^{(Not Bundle, based on esbuild)}}
• 🎯 Support Plugin _{^{(Like Vite's plugin)}}
• 🌱 What you see is what you get
• 🔥 Hot restart

Quick Setup

• Add dependency to project

npm i -D vite-electron-plugin

• Add vite-electron-plugin into vite.config.ts

import electron from 'vite-electron-plugin'

export default {
  plugins: [
    electron({
      include: [
        // The Electron source codes directory
        'electron',
      ],
    }),
  ],
}

• Create electron/main.ts and type the following code

import { app, BrowserWindow } from 'electron'

app.whenReady().then(() => {
  const win = new BrowserWindow()

  if (process.env.VITE_DEV_SERVER_URL) {
    win.loadURL(process.env.VITE_DEV_SERVER_URL)
  } else {
    win.loadFile('dist/index.html')
  }
})

• Add entry into package.json

{
+ "main": "dist-electron/main.js"
}

Examples

• quick-start

Recommend Structure

Let's use the official template-vanilla-ts created based on create vite as an example

+ ├─┬ electron
+ │ └── main.ts
  ├─┬ src
  │ ├── main.ts
  │ ├── style.css
  │ └── vite-env.d.ts
  ├── .gitignore
  ├── favicon.svg
  ├── index.html
  ├── package.json
  ├── tsconfig.json
+ └── vite.config.ts

Conventions

• Any file ending with reload.ext (e.g. foo.reload.js, preload.ts) after an update,
  will trigger a reload of the Electron-Renderer process, instead of an entire Electron App restart.
  Which is useful when updating Preload-Scripts.

Configuration

electron(config: Configuration)

Key	Type	Description	Required	Default
include	Array	directory or filename or glob Array. Must be a relative path, which will be calculated based on the root. If it is an absolute path, it can only be a subpath of root. Otherwise it will cause the output file path to be calculated incorrectly.	✅
root	string			process.cwd()
outDir	string	Output Directory.		dist-electron
api	Record<string, any>	Useful if you want to pass some payload to the plugin.
plugins	Plugin[]	See the Plugin API.
logger	{ [type: string], (...message: string[]) => void }	Custom log. If logger is passed, all logs will be input this option
transformOptions	import('esbuild').TransformOptions	Options of esbuild.transform()
watch	import('chokidar').WatchOptions	Options of chokidar.watch()

Plugin API

The design of plugin is similar to Vite's plugin. But simpler, only 4 hooks in total.

configResolved

• Type: (config: ResolvedConfig) => void | Promise<void>
• Kind: async, sequential

You can freely modify the config argument in ths hooks or use.

onwatch _{^{serve only}}

• Type: (envet: 'add' | 'change' | 'addDir' | 'unlink' | 'unlinkDir', path: string) => void
• Kind: async, parallel

Triggered by include file changes. You can emit some files in this hooks. Even restart the Electron App.

transform

• Type: (args: { filename: string, code: string, done: () => void }) => string | import('esbuild').TransformResult | void | Promise<string | import('esbuild').TransformResult | void>
• Kind: async, sequential

Triggered by changes in extensions files in include.

ondone

• Type: (args: { filename: string, distname: string }) => void
• Kind: async, parallel

Triggered when transform() ends or a file in extensions is removed.

Builtin Plugin

import path from 'node:path'
import electron from 'vite-electron-plugin'
import {
  alias,
  copy,
  dest,
  esmodule,
  customStart,
  loadViteEnv,
} from 'vite-electron-plugin/plugin'

export default {
  plugins: [
    electron({
      plugins: [
        alias([
          // `replacement` is recommented to use absolute path, 
          // it will be automatically calculated as relative path.
          { find: '@', replacement: path.join(__dirname, 'src') },
        ]),

        copy([
          // filename, glob
          { from: 'foo/*.ext', to: 'dest' },
        ]),

        // Dynamic change the build dist path.
        dest((_from, to) => to?.replace('dist-electron', 'dist-other')),

        customStart(({ startup }) => {
          // If you want to control the launch of Electron App yourself.
          startup()
        }),

        // Support use ESM npm-package in Electron-Main.  
        esmodule({
          // e.g. `execa`, `node-fetch`, `got`, etc.
          include: ['execa', 'node-fetch', 'got'],
        }),

        // https://vitejs.dev/guide/env-and-mode.html#env-files
        // Support use `import.meta.env.VITE_SOME_KEY` in Electron-Main
        loadViteEnv(),
      ],
    }),
  ],
}

JavaScript API

import {
  type Configuration,
  type ResolvedConfig,
  type Plugin,
  build,
  watch,
  startup,
  defineConfig,
  default as electron,
} from 'vite-electron-plugin'

Example

// dev
watch({
  include: [
    // The Electron source codes directory
    'electron',
  ],
  plugins: [
    {
      name: 'plugin-electron-startup',
      ondone() {
        // Startup Electron App
        startup()
      },
    },
  ],
})

// build
build({
  include: ['electron'],
})

Changelog

0.8.3 (2023-12-03)

• 0a33562 feat(plugin/alias): add acornOptions for #59
• a45237c chore: bump vite-plugin-electron to 0.14.1
• 30acf9c chore(deps): optional esbuild