Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/electron-vite/vite-plugin-electron
:electron: Electron⚡️Vite core repo
https://github.com/electron-vite/vite-plugin-electron
electron plugin vite
Last synced: 2 days ago
JSON representation
:electron: Electron⚡️Vite core repo
- Host: GitHub
- URL: https://github.com/electron-vite/vite-plugin-electron
- Owner: electron-vite
- License: mit
- Created: 2022-04-04T22:21:38.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-20T09:40:12.000Z (4 months ago)
- Last Synced: 2024-10-29T22:53:15.618Z (3 months ago)
- Topics: electron, plugin, vite
- Language: TypeScript
- Homepage: https://github.com/electron-vite
- Size: 13.7 MB
- Stars: 684
- Watchers: 5
- Forks: 55
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-vite - vite-plugin-electron - Integrate Vite and Electron. (Plugins / Framework-agnostic Plugins)
- awesome-vite - vite-plugin-electron - Integrate Vite and Electron. (Plugins / Framework-agnostic Plugins)
README
vite-plugin-electron
Electron 🔗 Vite
English
|
简体中文
In short, `vite-plugin-electron` makes developing Electron apps as easy as normal Vite projects.
## Features
- [🔥 Hot Restart (Main process)](https://electron-vite.github.io/guide/features.html#hot-restart)
- [🔄 Hot Reload (Preload scripts)](https://electron-vite.github.io/guide/features.html#hot-reload)
- [⚡️ HMR (Renderer process)](https://electron-vite.github.io/guide/features.html#hmr)
- 🌱 Fully compatible with Vite and Vite's ecosystem (Based on Vite)
- 🔮 Full-featured [JavaScript API](https://github.com/electron-vite/vite-plugin-electron#javascript-api), really easy to integrate with complex projects.
- 🐣 Few APIs, easy to use
## Quick Setup
1. Add the following dependency to your project
```sh
npm i -D vite-plugin-electron
```
2. Add `vite-plugin-electron` to the `plugins` section of `vite.config.ts`
```js
import electron from 'vite-plugin-electron/simple'
export default {
plugins: [
electron({
main: {
// Shortcut of `build.lib.entry`
entry: 'electron/main.ts',
},
preload: {
// Shortcut of `build.rollupOptions.input`
input: 'electron/preload.ts',
},
// Optional: Use Node.js API in the Renderer process
renderer: {},
}),
],
}
```
3. Create the `electron/main.ts` file and type the following code
```js
import { app, BrowserWindow } from 'electron'
app.whenReady().then(() => {
const win = new BrowserWindow({
title: 'Main window',
})
// You can use `process.env.VITE_DEV_SERVER_URL` when the vite command is called `serve`
if (process.env.VITE_DEV_SERVER_URL) {
win.loadURL(process.env.VITE_DEV_SERVER_URL)
} else {
// Load your file
win.loadFile('dist/index.html');
}
})
```
4. Add the `main` entry to `package.json`
```diff
{
+ "main": "dist-electron/main.mjs"
}
```
That's it! You can now use Electron in your Vite app ✨
## Flat API
In most cases, the `vite-plugin-electron/simple` API is recommended. If you know very well how this plugin works or you want to use `vite-plugin-electron` API as a secondary encapsulation of low-level API, then the flat API is more suitable for you. It is also simple but more flexible. :)
The difference compared to the simple API is that it does not identify which entry represents `preload` and the adaptation to preload.
```js
import electron from 'vite-plugin-electron'
export default {
plugins: [
electron({
entry: 'electron/main.ts',
}),
],
}
```
## Flat API vs Simple API
- Simple API is based on the Flat API
- Simple API incluess some Preload scripts preset configs.
- Flat API provides some more general APIs, which you can use for secondary encapsulation, such as [nuxt-electron](https://github.com/caoxiemeihao/nuxt-electron).
## Flat API (Define)
`electron(options: ElectronOptions | ElectronOptions[])`
```ts
export interface ElectronOptions {
/**
* Shortcut of `build.lib.entry`
*/
entry?: import('vite').LibraryOptions['entry']
vite?: import('vite').InlineConfig
/**
* Triggered when Vite is built every time -- `vite serve` command only.
*
* If this `onstart` is passed, Electron App will not start automatically.
* However, you can start Electroo App via `startup` function.
*/
onstart?: (args: {
/**
* Electron App startup function.
* It will mount the Electron App child-process to `process.electronApp`.
* @param argv default value `['.', '--no-sandbox']`
* @param options options for `child_process.spawn`
* @param customElectronPkg custom electron package name (default: 'electron')
*/
startup: (argv?: string[], options?: import('node:child_process').SpawnOptions, customElectronPkg?: string) => Promise
/** Reload Electron-Renderer */
reload: () => void
}) => void | Promise
}
```
## Recommend Structure
Let's use the official [template-vanilla-ts](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-vanilla-ts) created based on `create vite` as an example
```diff
+ ├─┬ electron
+ │ └── main.ts
├─┬ src
│ ├── main.ts
│ ├── style.css
│ └── vite-env.d.ts
├── .gitignore
├── favicon.svg
├── index.html
├── package.json
├── tsconfig.json
+ └── vite.config.ts
```
## Built format
This is just the default behavior, and you can modify them at any time through custom config in the `vite.config.js`
```log
{ "type": "module" }
┏————————————————————┳——————————┳———————————┓
│ built │ format │ suffix │
┠————————————————————╂——————————╂———————————┨
│ main process │ esm │ .js │
┠————————————————————╂——————————╂———————————┨
│ preload scripts │ cjs │ .mjs │ diff
┠————————————————————╂——————————╂———————————┨
│ renderer process │ - │ .js │
┗————————————————————┸——————————┸———————————┛
{ "type": "commonjs" } - default
┏————————————————————┳——————————┳———————————┓
│ built │ format │ suffix │
┠————————————————————╂——————————╂———————————┨
│ main process │ cjs │ .js │
┠————————————————————╂——————————╂———————————┨
│ preload scripts │ cjs │ .js │ diff
┠————————————————————╂——————————╂———————————┨
│ renderer process │ - │ .js │
┗————————————————————┸——————————┸———————————┛
```
## Examples
There are many cases here 👉 [electron-vite-samples](https://github.com/caoxiemeihao/electron-vite-samples)
## JavaScript API
`vite-plugin-electron`'s JavaScript APIs are fully typed, and it's recommended to use TypeScript or enable JS type checking in VS Code to leverage the intellisense and validation.
- `ElectronOptions` - type
- `resolveViteConfig` - function, Resolve the default Vite's `InlineConfig` for build Electron-Main
- `withExternalBuiltins` - function
- `build` - function
- `startup` - function
**Example**
```js
import { build, startup } from 'vite-plugin-electron'
const isDev = process.env.NODE_ENV === 'development'
const isProd = process.env.NODE_ENV === 'production'
build({
entry: 'electron/main.ts',
vite: {
mode: process.env.NODE_ENV,
build: {
minify: isProd,
watch: isDev ? {} : null,
},
plugins: [{
name: 'plugin-start-electron',
closeBundle() {
if (isDev) {
// Startup Electron App
startup()
}
},
}],
},
})
```
**Hot Reload**
Since `v0.29.0`, when preload scripts are rebuilt, they will send an `electron-vite&type=hot-reload` event to the main process.
If your App doesn't need a renderer process, this will give you **hot-reload**.
```js
// electron/main.ts
process.on('message', (msg) => {
if (msg === 'electron-vite&type=hot-reload') {
for (const win of BrowserWindow.getAllWindows()) {
// Hot reload preload scripts
win.webContents.reload()
}
}
})
```
## How to work
It just executes the `electron .` command in the Vite build completion hook and then starts or restarts the Electron App.
## Be aware
- 🚨 By default, the files in `electron` folder will be built into the `dist-electron`
- 🚨 Currently, `"type": "module"` is not supported in Electron
## C/C++ Native
We have two ways to use C/C++ native modules
**First way**
In general, Vite may not correctly build Node.js packages, especially C/C++ native modules, but Vite can load them as external packages
So, put your Node.js package in `dependencies`. Unless you know how to properly build them with Vite
```js
export default {
plugins: [
electron({
entry: 'electron/main.ts',
vite: {
build: {
rollupOptions: {
// Here are some C/C++ modules them can't be built properly
external: [
'serialport',
'sqlite3',
],
},
},
},
}),
],
}
```
**Second way**
Use 👉 [vite-plugin-native](https://github.com/vite-plugin/vite-plugin-native)
```js
import native from 'vite-plugin-native'
export default {
plugins: [
electron({
entry: 'electron/main.ts',
vite: {
plugins: [
native(/* options */),
],
},
}),
],
}
```