electron-shadcn：基于 Electron + shadcn/ui 的桌面应用开发模板

本文介绍 electron-shadcn，一个基于 Electron + React + shadcn/ui 的现代化桌面应用开发模板。该项目在 GitHub 上已获得 725 stars 和 116 forks，提供完整的桌面应用开发解决方案。

项目简介

electron-shadcn 是一个精心设计的 Electron 桌面应用开发模板，集成了现代化的前端技术栈。它提供了开箱即用的开发体验，包括预配置的 UI 组件、自动更新、类型安全等特性，帮助开发者快速构建美观的桌面应用程序。

核心特性

Electron 40 + Vite 7：最新版本的 Electron 配合 Vite 快速构建
React 19.2 + TypeScript 5.9：现代化 React 开发体验
shadcn/ui + Tailwind 4：美观的 UI 组件和样式系统
自动更新支持：基于 GitHub Releases 的自动更新机制
自定义标题栏：隐藏原生标题栏，实现自定义窗口控制
上下文隔离：启用 Context isolation 确保安全性
开发工具集成：默认集成 React DevTools

技术栈

核心框架

Electron 40 - 跨平台桌面应用框架
Vite 7 - 快速构建工具
React 19.2 - UI 库
TypeScript 5.9 - 类型安全

UI 与样式

Tailwind CSS 4 - 原子化 CSS 框架
shadcn/ui - 可复用的 React 组件库
Geist 字体 - 现代无衬线字体
Lucide - 图标库

路由与状态

TanStack Router - 类型安全的路由
React Query - 服务端状态管理
i18next - 国际化支持

开发与测试

oRPC - 类型安全的 API 调用
Zod 4 - 模式验证
Vitest - 单元测试
Playwright - E2E 测试
React Testing Library - 组件测试

构建与部署

Electron Forge - 应用打包和分发
GitHub Actions - CI/CD 自动化

安装指南

前置要求

Node.js >= 20
npm 或 pnpm

快速开始

bash

# 克隆项目
git clone https://github.com/LuanRoger/electron-shadcn.git

# 进入项目目录
cd electron-shadcn

# 安装依赖
npm install

# 启动开发服务器
npm run start

项目结构

text

electron-shadcn/
├── src/
│   ├── routes/           # 页面路由
│   │   ├── index.tsx     # 主页面
│   │   └── second.tsx    # 示例页面（可删除）
│   ├── components/       # 共享组件
│   ├── lib/              # 工具函数
│   └── main.ts           # Electron 主进程
├── forge.config.ts       # Electron Forge 配置
├── vite.main.config.ts   # Vite 主进程配置
├── vite.renderer.config.ts  # Vite 渲染进程配置
└── package.json

使用示例

自定义主页面

编辑 src/routes/index.tsx 来自定义应用主界面：

tsx

import { Button } from "@/components/ui/button"

export default function Home() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold">我的桌面应用</h1>
      <Button>点击我</Button>
    </div>
  )
}

添加新页面

在 src/routes/ 下创建新的路由文件
使用 TanStack Router 配置路由
添加导航链接

使用 shadcn/ui 组件

tsx

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
import { Button } from "@/components/ui/button"

export function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>卡片标题</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>操作按钮</Button>
      </CardContent>
    </Card>
  )
}

开发命令

命令	说明
`npm run start`	启动开发服务器
`npm run build`	构建生产版本
`npm run test`	运行测试
`npm run lint`	运行代码检查
`npm run package`	打包应用
`npm run make`	创建分发包

打包与发布

项目使用 Electron Forge 进行打包：