From 458694315de822f7a6eee2694a05b5557f798fe6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=8D=89=E9=9E=8B=E6=B2=A1=E5=8F=B7?= <308487730@qq.com> Date: Fri, 10 Jun 2022 09:16:43 +0800 Subject: [PATCH] docs: v2.0.0 --- README.md | 74 +++------------------------ README.zh-CN.md | 132 +++++++++--------------------------------------- 2 files changed, 32 insertions(+), 174 deletions(-) diff --git a/README.md b/README.md index 922a269..c100b37 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,20 @@ # electron-vite-react +[![awesome-vite](https://awesome.re/mentioned-badge.svg)](https://github.com/vitejs/awesome-vite) ![GitHub stars](https://img.shields.io/github/stars/caoxiemeihao/vite-react-electron?color=fa6470&style=flat) ![GitHub issues](https://img.shields.io/github/issues/caoxiemeihao/vite-react-electron?color=d8b22d&style=flat) ![GitHub license](https://img.shields.io/github/license/caoxiemeihao/vite-react-electron?style=flat) [![Required Node.JS >= v14.17.0](https://img.shields.io/static/v1?label=node&message=%3E=14.17.0&logo=node.js&color=3f893e&style=flat)](https://nodejs.org/about/releases) -**English | [简体中文](README.zh-CN.md)** +English | [简体中文](README.zh-CN.md) ## Overview -This is a `Vite`-integrated `Electron` template built with simplification in mind. - -The repo contains only the most basic files, dependencies and functionalities to ensure flexibility for various scenarios. - -You need a basic understanding of `Electron` and `Vite` to get started. But that's not mandatory - you can learn almost all the details by reading through the source code. Trust me, this repo is not that complex. 😋 +📦 Out of the box +💪 Support C/C++ addons +🔩 Support Use Electron、Node.js API in Renderer-process +🌱 Simple directory structure，real flexible +🖥 It's easy to implement multiple windows ## Quick start @@ -29,7 +30,7 @@ npm create electron-vite ## Directory structure -Once `dev` or `build` npm-script is executed, the `dist` folder will be generated. It has the same structure as the project, the purpose of this design is to ensure the correct path calculation. +*🚨 By default, the files in `electron` folder will be built into the `dist/electron`* ```tree ├── electron Electron-related code @@ -50,65 +51,6 @@ Once `dev` or `build` npm-script is executed, the `dist` folder will be generate └── src Renderer source code, your React application ``` -## Use Electron and NodeJS API - -> 🚧 By default, Electron doesn't support the use of API related to Electron and NodeJS in the Renderer process, but someone might need to use it. If so, you can see the template 👉 **[electron-vite-boilerplate](https://github.com/electron-vite/electron-vite-boilerplate)** - -#### Invoke Electron and NodeJS API in `Preload-script` - -- **electron/preload/index.ts** - - ```typescript - import fs from "fs"; - import { contextBridge, ipcRenderer } from "electron"; - - // --------- Expose some API to Renderer-process. --------- - contextBridge.exposeInMainWorld("fs", fs); - contextBridge.exposeInMainWorld("ipcRenderer", ipcRenderer); - ``` - -- **src/global.d.ts** - - ```typescript - // Defined in the window - interface Window { - fs: typeof import("fs"); - ipcRenderer: import("electron").IpcRenderer; - } - ``` - -- **src/main.ts** - - ```typescript - // Use Electron and NodeJS API in the Renderer-process - console.log("fs", window.fs); - console.log("ipcRenderer", window.ipcRenderer); - ``` - -## Use SerialPort, SQLite3, or other node-native addons in the Main-process - -- First, you need to make sure that the dependencies in the `package.json` are NOT in the "devDependencies". Because the project will need them after packaged. - -- Main-process, Preload-script are also built with Vite, and they're built as [build.lib](https://vitejs.dev/config/#build-lib). - So they just need to configure Rollup. - -```js -export default { - build: { - // built lib for Main-process, Preload-script - lib: { - entry: "index.ts", - formats: ["cjs"], - fileName: () => "[name].js", - }, - rollupOptions: { - // configuration here - external: ["serialport", "sqlite3"], - }, - }, -}; -``` - ## `dependencies` vs `devDependencies` - First, you need to know if your dependencies are needed after the application is packaged. diff --git a/README.zh-CN.md b/README.zh-CN.md index cdf3cec..79a2ecb 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,21 +1,20 @@ # vite-react-electron +[![awesome-vite](https://awesome.re/mentioned-badge.svg)](https://github.com/vitejs/awesome-vite) ![GitHub stars](https://img.shields.io/github/stars/caoxiemeihao/vite-react-electron?color=fa6470&style=flat) ![GitHub issues](https://img.shields.io/github/issues/caoxiemeihao/vite-react-electron?color=d8b22d&style=flat) ![GitHub license](https://img.shields.io/github/license/caoxiemeihao/vite-react-electron?style=flat) [![Required Node.JS >= v14.17.0](https://img.shields.io/static/v1?label=node&message=%3E=14.17.0&logo=node.js&color=3f893e&style=flat)](https://nodejs.org/about/releases) -**[English](README.md) | 简体中文** +[English](README.md) | 简体中文 ## 概述 -  这是一个追求精简的`Electron`类整合模板，只保持最基本的文件、最基本的依赖、最基本的功能；而不是大而全的、臃肿的设计。这样做的目的是能确保模板足够灵活。 - -所以说如果你是对 -- 工程模板追求精简的 Coder，或者刚入世的小白想弄明白`Electron`整合类模板最基础的工作原理，亦或者你是大神只是想偷懒少干点活；那么这个模板最合适你不过了。 - -尽管如此，我还是希望你对`Electron` `Vite`有一定的基础；因为除了项目结构简单外，这份`README`也显得 “精简” 。 - -模板的具体实现细节我相信你看两遍源码就能把它吃透了 😋 +📦 开箱即用 +💪 支持 C/C++ 模块 +🔩 支持在渲染进程中使用 Electron、Node.js API +🌱 结构清晰，可塑性强 +🖥 很容易实现多窗口 ## 快速开始 @@ -23,62 +22,33 @@ npm create electron-vite ``` -![electron-vite-react.gif](https://github.com/electron-vite/electron-vite-react/blob/main/packages/renderer/public/electron-vite-react.gif?raw=true) +![electron-vite-react.gif](https://github.com/electron-vite/electron-vite-react/blob/main/public/electron-vite-react.gif?raw=true) ## 调试 -![electron-vite-react-debug.gif](https://github.com/electron-vite/electron-vite-react/blob/main/packages/renderer/public/electron-vite-react-debug.gif?raw=true) - - +![electron-vite-react-debug.gif](https://github.com/electron-vite/electron-vite-react/blob/main/public/electron-vite-react-debug.gif?raw=true) ## 目录 -一旦启动或打包脚本执行过，会在根目录产生 **`dist` 文件夹，里面的文件夹同 `packages` 一模一样**；在使用一些路径计算时，尤其是相对路径计算；`dist` 与 `packages` 里面保持相同的目录结构能避开好多问题 +*🚨 默认情况下, `electron` 文件夹下的文件将会被构建到 `dist/electron`* ```tree -├── build 用于生产构建的资源 -| ├── icon.icns 应用图标(macOS) -| ├── icon.ico 应用图标 -| ├── installerIcon.ico 安装图标 -| └── uninstallerIcon.ico 卸载图标 +├── electron Electron 源码文件夹 +| ├── main Main-process 源码 +| ├── preload Preload-script 源码 +| └── resources 应用打包的资源文件夹 +| ├── icon.icns 应用图标(macOS) +| ├── icon.ico 应用图标 +| ├── installerIcon.ico 安装图标 +| └── uninstallerIcon.ico 卸载图标 | -├── dist 构建后，根据 packages 目录生成 -| ├── main -| ├── preload -| └── renderer +├── release 构建后生成程序目录 +| └──{version} +| ├── {os}-unpacked 未打包的程序(绿色运行版) +| └── Setup.{ext} 应用安装文件 | -├── release 在生产构建后生成，包含可执行文件 -| └── {version} -| ├── win-unpacked 包含未打包的应用程序可执行文件 -| └── Setup.exe 应用程序的安装程序 -| -├── scripts -| ├── build.mjs 项目开发脚本 npm run build -| └── watch.mjs 项目开发脚本 npm run dev -| -├── packages -| ├── main 主进程源码 -| | └── vite.config.ts -| ├── preload 预加载脚本源码 -| | └── vite.config.ts -| └── renderer 渲染进程源码 -| └── vite.config.ts +├── public 同 Vite 模板的 public +└── src 渲染进程源码、React代码 ``` ## 依赖放到 dependencies 还是 devDependencies @@ -92,57 +62,3 @@ electron-builder 打包时候会将 dependencies 中的包打包到 app.asar 里 现实情况 vue、react 放到 dependencies 或 devDependencies 中都可以被正确构建； 但是放到 dependencies 会被 electron-builder 打包到 app.asar 里面导致包体变大； 所以放到 devDependencies 既能被正确构建还可以减小 app.asar 体积，一举两得 - -## 渲染进程使用 NodeJs API - -> 🚧 因为安全的原因 Electron 默认不支持在 渲染进程 中使用 NodeJs API，但是有些小沙雕就是想这么干，拦都拦不住；实在想那么干的话，用另一个模板更方便 👉 **[electron-vite-boilerplate](https://github.com/caoxiemeihao/electron-vite-boilerplate)** - -**推荐所有的 NodeJs、Electron API 通过 `Preload-script` 注入到 渲染进程中，例如：** - -* **packages/preload/index.ts** - - ```typescript - import fs from 'fs' - import { contextBridge, ipcRenderer } from 'electron' - - // --------- Expose some API to Renderer-process. --------- - contextBridge.exposeInMainWorld('fs', fs) - contextBridge.exposeInMainWorld('ipcRenderer', ipcRenderer) - ``` - -* **packages/renderer/src/global.d.ts** - - ```typescript - // Defined on the window - interface Window { - fs: typeof import('fs') - ipcRenderer: import('electron').IpcRenderer - } - ``` - -* **packages/renderer/main.ts** - - ```typescript - // Use Electron, NodeJs API in Renderer-process - console.log('fs', window.fs) - console.log('ipcRenderer', window.ipcRenderer) - ``` - -**如果你真的在这个模板中开启了 `nodeIntegration: true` `contextIsolation: false` 我不拦着 -🚧 但是要提醒你做两件事儿** - -1. `preload/index.ts` 中的 `exposeInMainWorld` 删掉，已经没有用了 - - ```diff - - contextBridge.exposeInMainWorld('fs', fs) - - contextBridge.exposeInMainWorld('ipcRenderer', ipcRenderer) - ``` - -2. `configs/vite-renderer.config` 中有个 `resolveElectron` **最好了解下** -👉 这里有个 `issues` [请教一下vite-renderer.config中的resolveElectron函数](https://github.com/caoxiemeihao/electron-vue-vite/issues/52) - -