Electron React Boilerplate：构建跨平台桌面应用的终极起点

【免费下载链接】electron-react-boilerplate 【免费下载链接】electron-react-boilerplate 项目地址: https://gitcode.com/gh_mirrors/el/electron-react-boilerplate

Electron React Boilerplate 是一个专为构建现代化、可扩展的跨平台桌面应用而设计的强大开发起点。该项目巧妙地将 Electron 的桌面应用能力与 React 的现代化前端开发体验相结合，为开发者提供了一个功能完备、架构优雅的起点。它采用了业界领先的技术栈组合，包括 Electron、React 18+、TypeScript 和 Webpack 5，构建了一个完整的桌面应用开发生态系统。项目集成了完整的开发工具链，确保开发者能够享受流畅的开发体验，包括 TypeScript 支持、热重载（HMR）、ESLint + Prettier 代码规范以及 Jest 测试框架。

项目概述与核心特性介绍

Electron React Boilerplate 是一个专为构建现代化、可扩展的跨平台桌面应用而设计的强大开发起点。这个项目巧妙地将 Electron 的桌面应用能力与 React 的现代化前端开发体验相结合，为开发者提供了一个功能完备、架构优雅的起点。

技术栈架构

该项目采用了业界领先的技术栈组合，构建了一个完整的桌面应用开发生态系统：

mermaid

核心特性详解

1. 现代化的开发体验

项目集成了完整的开发工具链，确保开发者能够享受流畅的开发体验：

  • TypeScript 支持：完整的类型系统，提供更好的代码智能提示和错误检查
  • 热重载（HMR）：实时更新渲染进程代码，无需重启应用即可看到更改效果
  • ESLint + Prettier：统一的代码风格和格式化配置
  • Jest 测试框架：完整的单元测试和组件测试支持
2. 生产环境优化

项目内置了丰富的生产环境优化配置：

优化特性 实现方式 效果
代码分割 Webpack SplitChunks 减少初始加载时间
Tree Shaking Webpack + TypeScript 移除未使用代码
资源压缩 Terser + CSS 压缩 减小包体积
预编译 DLL 预构建 加速开发构建
3. 跨平台打包支持

项目支持一键打包为多个平台的应用程序：

mermaid

4. 安全性与稳定性

项目内置了多项安全措施和稳定性保障：

  • 主进程与渲染进程隔离：通过预加载脚本安全地暴露 API
  • 自动更新机制：集成 electron-updater 支持自动应用更新
  • 错误日志记录：使用 electron-log 记录运行时错误
  • 代码签名支持：macOS 应用公证和代码签名配置

项目结构设计

项目的目录结构经过精心设计，遵循最佳实践：

src/
├── main/           # Electron 主进程代码
│   ├── main.ts     # 应用入口点
│   ├── menu.ts     # 应用菜单配置
│   ├── preload.ts  # 预加载脚本
│   └── util.ts     # 工具函数
├── renderer/       # React 渲染进程
│   ├── App.tsx     # 主应用组件
│   ├── App.css     # 样式文件
│   ├── index.tsx   # React 入口点
│   └── index.ejs   # HTML 模板
└── __tests__/      # 测试文件

开发工作流示例

以下是一个典型的开发工作流代码示例：

// 主进程与渲染进程通信示例
// preload.ts - 安全地暴露 API
contextBridge.exposeInMainWorld('electronAPI', {
  platform: process.platform,
  versions: process.versions,
});

// 渲染进程中使用
declare global {
  interface Window {
    electronAPI: {
      platform: string;
      versions: NodeJS.ProcessVersions;
    };
  }
}

// React 组件中使用
function SystemInfo() {
  const { platform, versions } = window.electronAPI;
  
  return (
    <div>
      <p>运行平台: {platform}</p>
      <p>Node.js 版本: {versions.node}</p>
      <p>Chrome 版本: {versions.chrome}</p>
      <p>Electron 版本: {versions.electron}</p>
    </div>
  );
}

性能优化特性

项目内置了多项性能优化措施：

  • DLL 预构建：将不常变化的依赖预先构建，加速开发时构建速度
  • 生产环境代码分割：按路由分割代码，实现按需加载
  • CSS 模块化：避免样式冲突，支持 CSS-in-JS 模式
  • 资源内联优化：小图片和字体文件自动转为 base64 内联

扩展性与定制化

项目的架构设计支持高度定制化：

  • 模块化配置：Webpack 配置按环境分离，易于自定义
  • 插件系统：支持添加自定义 Webpack 插件和 loaders
  • 多环境支持：开发、测试、生产环境独立配置
  • CI/CD 集成：内置 GitHub Actions 工作流配置

Electron React Boilerplate 不仅仅是一个模板项目，而是一个完整的桌面应用开发框架，它提供了从开发到部署的全套解决方案，让开发者能够专注于业务逻辑的实现，而不是基础设施的搭建。

技术栈深度解析（Electron + React + TypeScript）

Electron React Boilerplate 采用了现代前端开发中最强大的技术组合之一：Electron、React 和 TypeScript。这个技术栈的选择体现了对开发效率、代码质量和跨平台兼容性的深度考量。

Electron：桌面应用的桥梁

Electron 作为整个架构的基础，提供了将 Web 技术转换为桌面应用的能力。它基于 Chromium 和 Node.js，允许开发者使用 HTML、CSS 和 JavaScript 来构建跨平台的桌面应用程序。

mermaid

在 Electron React Boilerplate 中，主进程负责管理应用程序的生命周期和原生系统交互：

// src/main/main.ts - 主进程入口
class AppUpdater {
  constructor() {
    log.transports.file.level = 'info';
    autoUpdater.logger = log;
    autoUpdater.checkForUpdatesAndNotify();
  }
}

const createWindow = async () => {
  mainWindow = new BrowserWindow({
    show: false,
    width: 1024,
    height: 728,
    icon: getAssetPath('icon.png'),
    webPreferences: {
      preload: app.isPackaged
        ? path.join(__dirname, 'preload.js')
        : path.join(__dirname, '../../.erb/dll/preload.js'),
    },
  });
};

React：现代化的用户界面框架

React 19 提供了函数式组件和 Hooks 的现代化开发体验，结合 JSX 语法使得 UI 开发更加直观和高效。

// src/renderer/App.tsx - React 组件示例
function Hello() {
  return (
    <div>
      <div className="Hello">
        <img width="200" alt="icon" src={icon} />
      </div>
      <h1>electron-react-boilerplate</h1>
      <div className="Hello">
        <a href="https://electron-react-boilerplate.js.org/" target="_blank" rel="noreferrer">
          <button type="button">
            <span role="img" aria-label="books">📚</span>
            Read our docs
          </button>
        </a>
      </div>
    </div>
  );
}

React 在该项目中的优势包括：

  • 组件化开发：将 UI 拆分为可重用的组件
  • 虚拟 DOM：高效的 DOM 更新机制
  • Hooks 系统：状态管理和副作用处理
  • React Router：单页面应用的路由管理

TypeScript：类型安全的开发体验

TypeScript 为整个项目提供了静态类型检查，大大提高了代码的可靠性和开发效率。项目配置了严格的 TypeScript 编译选项：

// tsconfig.json 核心配置
{
  "compilerOptions": {
    "target": "es2020",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx"
  }
}

TypeScript 在项目中的典型应用：

// 类型定义和接口
export type Channels = 'ipc-example';

export type ElectronHandler = typeof electronHandler;

// 进程间通信的类型安全
ipcMain.on('ipc-example', async (event, arg) => {
  const msgTemplate = (pingPong: string) => `IPC test: ${pingPong}`;
  console.log(msgTemplate(arg));
  event.reply('ipc-example', msgTemplate('pong'));
});

技术栈协同工作流程

三个技术的完美融合创造了高效的开发体验：

mermaid

开发工具和构建配置

项目配置了完整的开发工具链：

工具 用途 配置位置
Webpack 模块打包和代码分割 .erb/configs/
ESLint 代码质量检查 .eslintrc
Prettier 代码格式化 .prettierrc
Jest 单元测试 package.json
Hot Reload 热重载开发 webpack 配置

构建配置支持多环境：

  • 开发环境：热重载、源码映射、快速迭代
  • 生产环境：代码压缩、性能优化、安全加固
  • 测试环境：模拟依赖、覆盖率报告

类型安全的进程间通信

IPC（进程间通信）是 Electron 应用的核心，TypeScript 确保了类型安全：

// preload.ts - 安全的 API 暴露
contextBridge.exposeInMainWorld('electron', {
  ipcRenderer: {
    invoke(channel: Channels, ...args: unknown[]) {
      return ipcRenderer.invoke(channel, ...args);
    },
  },
});

// 类型定义文件
interface Window {
  electron: {
    ipcRenderer: {
      invoke(channel: Channels, ...args: unknown[]): Promise<unknown>;
    };
  };
}

这种设计确保了：

  • 渲染进程只能访问白名单中的 API
  • 所有 IPC 调用都有明确的类型约束
  • 避免了常见的安全漏洞

现代化开发体验

技术栈的组合提供了完整的开发体验：

  1. 实时重载：代码修改立即反映在应用中
  2. 类型检查：编写时即发现潜在错误
  3. 代码分割：优化应用加载性能
  4. 自动更新：内置的自动更新机制
  5. 跨平台打包：支持 Windows、macOS、Linux

这个技术栈的选择不仅考虑了当前的技术趋势，更注重长期的维护性和扩展性。Electron 提供桌面应用能力，React 提供现代化的 UI 开发体验，TypeScript 确保代码质量，三者结合形成了一个强大而稳定的开发基础。

项目结构与目录组织分析

Electron React Boilerplate 采用精心设计的项目结构，为开发者提供了一个清晰、可扩展且易于维护的代码组织方案。该项目结构充分考虑了现代桌面应用开发的最佳实践，将 Electron 的主进程、渲染进程、构建配置和资源文件进行了合理的分离。

核心目录结构解析

项目采用分层架构设计，主要包含以下几个核心目录：

目录/文件 类型 描述
src/ 源代码目录 包含所有应用源代码
assets/ 资源文件目录 存放图标、配置文件等静态资源
.erb/ 构建配置目录 Webpack 配置和构建脚本
release/ 发布目录 打包后的应用文件
package.json 配置文件 项目依赖和脚本配置

源代码组织架构

src/ 目录是项目的核心，采用清晰的模块化设计：

mermaid

主进程代码结构 (src/main/)

主进程目录包含 Electron 应用的核心逻辑：

  • main.ts: 应用入口文件，负责创建主窗口、处理生命周期事件
  • menu.ts: 应用菜单构建器，实现原生菜单功能
  • preload.ts: 预加载脚本，提供安全的 IPC 通信桥梁
  • util.ts: 工具函数，包含路径解析等辅助功能
// main.ts 中的关键结构示例
class AppUpdater {
  constructor() {
    log.transports.file.level = 'info';
    autoUpdater.logger = log;
    autoUpdater.checkForUpdatesAndNotify();
  }
}

const createWindow = async () => {
  // 窗口创建逻辑
  mainWindow = new BrowserWindow({
    show: false,
    width: 1024,
    height: 728,
    icon: getAssetPath('icon.png'),
    webPreferences: {
      preload: app.isPackaged
        ? path.join(__dirname, 'preload.js')
        : path.join(__dirname, '../../.erb/dll/preload.js'),
    },
  });
};
渲染进程代码结构 (src/renderer/)

渲染进程采用 React 技术栈，包含现代前端开发的所有要素：

  • App.tsx: 主 React 组件，应用界面入口
  • App.css: 样式文件，支持 CSS Modules
  • index.tsx: React 应用启动文件
  • index.ejs: HTML 模板文件
  • preload.d.ts: TypeScript 类型定义文件

构建系统架构 (.erb/)

.erb/ 目录包含了完整的构建配置系统，体现了现代化的构建最佳实践：

mermaid

配置文件详解

.erb/configs/ 包含多个 Webpack 配置文件：

  • webpack.config.main.dev.ts: 主进程开发环境配置
  • webpack.config.main.prod.ts: 主进程生产环境配置
  • webpack.config.renderer.dev.ts: 渲染进程开发环境配置
  • webpack.config.renderer.prod.ts: 渲染进程生产环境配置
  • webpack.config.preload.dev.ts: 预加载脚本配置
脚本系统

.erb/scripts/ 包含各种构建和开发脚本：

  • check-native-dep.js: 检查原生依赖
  • clean.js: 清理构建目录
  • check-port-in-use.js: 端口检查
  • notarize.js: macOS 应用公证脚本

资源文件管理 (assets/)

资源目录采用多分辨率图标支持，确保应用在不同平台和设备上的显示效果：

mermaid

发布配置 (release/)

发布目录结构体现了 Electron Builder 的打包策略：

release/
├── app/
│   ├── package.json
│   └── package-lock.json
└── build/
    └── (打包后的应用文件)

开发与生产环境差异

项目通过环境变量区分开发和生产环境：

环境 构建输出 热重载 源码映射
开发环境 .erb/dll/ 支持 启用
生产环境 dist/ 不支持 禁用

类型系统集成

项目全面采用 TypeScript，类型定义文件分布在各个模块：

  • tsconfig.json: TypeScript 编译器配置
  • preload.d.ts: 预加载脚本类型定义
  • assets.d.ts: 资源文件类型定义

这种结构设计确保了类型安全性和开发体验的一致性。

测试基础设施

测试文件位于 src/__tests__/ 目录，采用 Jest 测试框架：

  • App.test.tsx: React 组件测试
  • 集成测试配置在 package.json 中定义
  • 支持 DOM 测试和模块模拟

构建流程优化

项目的构建系统经过精心优化，支持：

  1. 并行构建: 主进程和渲染进程同时编译
  2. DLL 预构建: 提高开发环境构建速度
  3. 代码分割: 优化生产环境包大小
  4. Tree Shaking: 移除未使用代码
  5. 缓存策略: 加速重复构建

这种目录组织结构不仅提供了清晰的代码分离，还为项目的可维护性和可扩展性奠定了坚实基础。每个模块都有明确的职责边界，使得团队协作和功能扩展变得更加高效。

快速开始与开发环境搭建

Electron React Boilerplate 提供了一个精心配置的开发环境，让您能够立即开始构建跨平台桌面应用程序。本节将详细介绍如何快速搭建开发环境并启动您的第一个 Electron + React 应用。

环境要求与前置准备

在开始之前，请确保您的系统满足以下最低要求：

组件 最低版本 推荐版本
Node.js 14.x 18.x 或更高
npm 7.x 10.x 或更高
Git 2.x 最新版本

您可以通过以下命令检查当前环境版本：

node --version
npm --version
git --version

如果尚未安装 Node.js，建议从 Node.js 官网 下载并安装 LTS 版本。

项目克隆与初始化

首先，克隆项目仓库到本地。推荐使用深度克隆以节省时间和磁盘空间：

git clone --depth 1 --branch main https://gitcode.com/gh_mirrors/el/electron-react-boilerplate.git your-project-name
cd your-project-name

项目结构采用模块化设计，主要包含以下核心目录：

mermaid

依赖安装与配置

安装项目依赖是启动开发的关键步骤：

npm install

这个命令会执行以下操作：

  1. 安装所有 package.json 中定义的依赖包
  2. 运行 postinstall 脚本进行环境检查
  3. 构建开发所需的动态链接库（DLL）
  4. 安装 Electron 应用依赖

安装过程中，项目会自动执行环境验证，确保所有原生依赖正确配置。如果遇到权限问题，请确保使用适当的权限运行命令。

启动开发服务器

安装完成后，使用以下命令启动开发环境：

npm start

这个命令会启动完整的开发工作流：

mermaid

开发服务器启动后，您将看到 Electron 应用程序窗口，其中运行着基于 React 的用户界面。默认应用包含一个简单的计数器示例和 IPC 通信演示。

开发工作流特性

Electron React Boilerplate 提供了强大的开发体验：

热重载功能：修改 React 组件时，界面会自动更新而无需刷新整个应用 TypeScript 支持：完整的类型检查和智能提示 开发工具集成：自动安装 React Developer Tools 进程隔离：清晰的主进程与渲染进程分离架构

常见问题排查

如果在启动过程中遇到问题，可以参考以下解决方案：

端口冲突：开发服务器默认使用 1212 端口，如果被占用会自动选择其他端口 依赖安装失败：尝试清除 npm 缓存：npm cache clean --force 后重新安装 权限问题：在 Linux/macOS 上可能需要使用 sudo，但建议配置正确的权限

下一步开发建议

成功启动开发环境后，您可以：

  1. 修改 src/renderer/App.tsx 开始定制您的应用界面
  2. 在 src/main/main.ts 中添加主进程功能
  3. 使用 src/main/preload.ts 定义安全的 IPC 通信接口
  4. 通过 npm run lint 检查代码质量

开发环境现已准备就绪，您可以开始构建功能丰富的跨平台桌面应用程序了。

总结

Electron React Boilerplate 提供了一个精心配置、功能完备的开发环境，让开发者能够立即开始构建跨平台桌面应用程序。通过详细的环境要求说明、项目克隆与初始化指南、依赖安装配置步骤以及开发服务器启动流程，该项目确保了顺畅的开发体验。它集成了热重载、TypeScript 支持、开发工具集成和进程隔离等强大特性，为开发者提供了从环境搭建到应用开发的完整解决方案。成功启动开发环境后，开发者可以轻松开始定制应用界面、添加主进程功能、定义安全的 IPC 通信接口，从而快速构建功能丰富的跨平台桌面应用程序。

【免费下载链接】electron-react-boilerplate 【免费下载链接】electron-react-boilerplate 项目地址: https://gitcode.com/gh_mirrors/el/electron-react-boilerplate

Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

cover

触觉智能Purple Pi OH开发板已适配OpenHarmony6.1，将作为LTS长期支持版，附API参考说明

avatar 开源鸿蒙跨平台开发者社区
cover

Flutter for OpenHarmony三方库适配实战：location 位置服务

avatar 开源鸿蒙跨平台开发者社区
cover

Flutter for OpenHarmony三方库适配实战：camera 相机功能详解

avatar 开源鸿蒙跨平台开发者社区