Electron App Template
๐
**A modern Electron app boilerplate with React v19, TypeScript v5, TailwindCSS v3, Ant Design v5, SQLite3 database, and automated GitHub releases.**
## โจ Features
### ๐ Core Features
๐ฅ **Fast and Ready-to-go** with a well-thought-out structure
๐ **Hot reload** for main process and **Fast Refresh** for renderer
๐ **React Router DOM** for seamless navigation
๐ **Preload (context bridge)** already configured
๐ฎ **Automated GitHub releases** for **Windows**, **Mac** and **Linux**
๐๏ธ **SQLite3 database** with **TypeORM** integration
๐ **Internationalization (i18n)** with **react-i18next**
๐จ **Modern UI** with **Ant Design** components
### ๐ ๏ธ Technologies
๐ **Electron** v36.3.2
โ๏ธ **React** v19.1.0
๐ **React Router DOM** v7.6.1
๐ **TypeScript** v5.8.3
๐ฆ **Electron Forge** v7.8.1
โจ **TailwindCSS** v3.4.17
๐จ **Ant Design** v5.25.4
๐๏ธ **better-sqlite3** v11.10.0 + **TypeORM** v0.3.24
๐ **i18next** v25.2.1 + **react-i18next** v15.5.2
๐ซ **ESLint** + **Prettier** with **TailwindCSS** plugin
๐ฎ **GitHub Actions** for automated releases
## ๐๏ธ Project Architecture
This project follows a well-structured layered architecture pattern:
## ๐ Inter-Process Communication (IPC)
This template provides a type-safe, structured approach for Renderer-Main process communication. Here's how it works:
### ๐ Step-by-Step Guide
Here's the IPC communication flow visualized with UML:
```mermaid
sequenceDiagram
participant Renderer as Renderer Process
participant Preload as Preload Script
participant Main as Main Process
participant Handler as IPC Handler
participant Service as Welcome Service
Renderer->>Preload: 1. Call window.electron.welcome.getWelcome()
Preload->>Main: 2. Send IPC message
Main->>Handler: 3. Route to welcome.ipc.ts
Handler->>Service: 4. Execute welcomeService.getWelcome()
Service-->>Handler:
Handler-->>Main:
Main-->>Preload: 5. Return response
Preload-->>Renderer:
```
1. **Declare interfaces** in `src/types/electron.d.ts`:
```ts
declare global {
interface Window {
electron: {
welcome: {
getWelcome: () => Promise;
};
};
}
}
```
2. **Configure IPC channels** in `src/shared/config.ts`:
```ts
export const config = {
welcome: {
getWelcome: createIpcChannel('welcome/getWelcome'),
},
};
```
3. **Implement handler** in `src/main/ipc/`:
```ts
// welcome.ipc.ts
config.welcome.getWelcome.handle(async () => {
return welcomeService.getWelcome();
});
```
4. **Call from Renderer**:
```ts
const welcome = await window.electron.welcome.getWelcome();
```
### ๐ Key Benefits
- **Type Safety**: Full TypeScript support end-to-end
- **Separation of Concerns**: Handlers stay in main process
- **Discoverability**: All IPC endpoints in shared config
- **Testability**: Handlers are pure functions
### ๐ ๏ธ Best Practices
- Group related methods under namespaces
- Keep handlers thin - delegate to services
- Use JSDoc for complex parameter types
- Add error handling in services
```
Windows Layer โ IPC Layer โ IPC Layout โ Service Layout โ Repository Layout
```
### ๐ **Project Structure**
```bash
src/
โโโ main/
โ โโโ database/ # Database configuration and entities
โ โโโ ipc/ # Inter-Process Communication handlers
โ โโโ main.ts # Main process entry point
โ โโโ services/ # Business logic and service layer
โ โโโ utils/ # Utility functions and helpers
โ โโโ windows/ # Window management and creation
โโโ preload/
โ โโโ preload.ts # Preload scripts for secure context bridge
โโโ renderer/
โ โโโ App.tsx # Main React application component
โ โโโ assets/ # Static assets (images, icons, etc.)
โ โโโ config/ # Frontend configuration
โ โโโ i18n/ # Internationalization files
โ โโโ layout/ # UI layout components
โ โโโ pages/ # Application pages/screens
โ โโโ renderer.css # Global styles
โ โโโ renderer.html # HTML template
โ โโโ renderer.ts # Renderer process entry point
โ โโโ styles/ # CSS/SCSS style files
โโโ shared/
โ โโโ config-utils.ts # Shared configuration utilities
โ โโโ config.ts # Application configuration
โ โโโ ipc-channel.ts # IPC channel definitions
โ โโโ ipc-subscription.ts # IPC event subscriptions
โโโ types/
โโโ custom.d.ts # Custom type definitions
โโโ electron.d.ts # Electron-specific types
```
### ๐ **Architecture Flow**
1. **๐ช Windows Layer**: Manages application windows and their lifecycle
2. **๐ก IPC Layer**: Handles communication between main and renderer processes
3. **๐จ IPC Layout**: Organizes IPC communication patterns and data flow
4. **โ๏ธ Service Layer**: Contains business logic and application services
5. **๐๏ธ Repository Layer**: Manages data access and database operations
## โ๏ธ Requirements
- **Node.js** 20+
- **npm** 10+
## ๐ Quick Start
```bash
# Create a new project
npx @wuchuheng/electron my-app
cd my-app
# Install dependencies
npm install
# Start development
npm run start
```
> **Note**: After creating your project, update the `package.json` file with your project details (name, description, author, etc.).
## ๐ ๏ธ Development
```bash
# Start development server
npm run start
# Format code
npm run format
# Lint code
npm run lint
# Generate app icons
npm run gen:logo
```
## ๐ฆ Distribution
> **Note**: Check [Electron Forge docs](https://www.electronforge.io/) for more information
### Build for all platforms
```bash
npm run make
```
### Build for specific platform
```bash
# Windows
npm run make --platform=win32
# macOS
npm run make --platform=darwin
# Linux
npm run make --platform=linux
```
### Package without distribution
```bash
npm run package
```
The built applications will be available in the `out` folder.
## ๐ค Contributing
> **Note**: contributions are always welcome, but always **ask first**, โ please โ before work on a PR.
That said, there's a bunch of ways you can contribute to this project, like by:
๐ชฒ **Reporting a bug**
๐ **Improving this documentation**
๐จ **Sharing this project** and recommending it to your friends
๐ต **Supporting this project** on GitHub Sponsors
๐ **Giving a star** on this repository
## ๐ License
**MIT** ยฉ [Wuchuheng](https://github.com/wuchuheng)
## ๐ค Author
**Wuchuheng**
- Website: https://wuchuheng.com
- Github: [@wuchuheng](https://github.com/wuchuheng)
## ๐ Show your support
Give a โญ๏ธ if this project helped you!