Electron + Next.js + Vite + HeroUI + Tailwind CSS Template

English | 中文 | 日本語 | Español | Français | Русский

A modern, production-ready desktop application template combining the best of web technologies. Build cross-platform desktop apps with the developer experience of web development.

✨ Features

🚀 Modern Tech Stack

• Electron 40 - Latest stable version for cross-platform desktop apps
• React 18 - Latest React with concurrent features
• TypeScript 5 - Strict mode enabled for type safety
• Vite 6 - Lightning fast HMR and optimized builds
• HeroUI v2 - Beautiful, accessible React components
• Tailwind CSS v4 - Utility-first CSS with latest features

🛠️ Developer Experience

• Hot Module Replacement - Instant updates during development
• Type Safety - Full TypeScript support with strict mode
• Modern Tooling - ESLint, Prettier configured out of the box
• Path Aliases - Clean imports with @/ prefix
• Error Boundaries - Graceful error handling

🎨 UI/UX

• Dark Mode - Built-in theme switching support
• Responsive Design - Works on all screen sizes
• Smooth Animations - Framer Motion integration
• Accessible - WCAG compliant components
• Customizable - Easy theming with Tailwind CSS

📦 Production Ready

• Installer Generation - Build for Windows, macOS, and Linux
• Cross-Platform - Single codebase for all major desktop platforms

📋 Prerequisites

Before you begin, ensure you have met the following requirements:

• Node.js >= 18.0.0
• Yarn >= 1.22.0 (recommended) or npm/pnpm
• Git

Note: If you're building native dependencies (optional), you may need platform-specific build tools (Visual Studio Build Tools for Windows, or Xcode Command Line Tools for macOS).

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/LingChen-tsjmdlc/electron-vite-heroui-template.git my-electron-app
cd my-electron-app

2. Install Dependencies

yarn install

3. Start Development Server

# Run in Electron with hot reload
yarn dev

# Or just the web preview (browser)
yarn dev:web

4. Build for Production

# Build for current platform
yarn build

# Build for specific platforms
yarn build:win    # Windows
yarn build:mac    # macOS
yarn build:linux  # Linux
yarn build:all    # All platforms

📂 Project Structure

my-electron-app/
├── electron/                 # Electron main process
│   ├── main.ts              # Main process entry
│   └── preload.ts           # Preload script for IPC
├── src/
│   ├── components/          # Reusable React components
│   ├── config/              # Configuration files
│   ├── layouts/             # Page layouts
│   ├── pages/               # Application pages
│   ├── styles/              # Global styles
│   └── types/               # TypeScript types
├── build/                   # Build configuration
├── release/                 # Generated installers
├── package.json
├── vite.config.ts
├── tsconfig.json
└── tailwind.config.js

🔧 Configuration

Customizing the Build

Edit the build section in package.json:

{
  "build": {
    "appId": "com.yourcompany.yourapp",
    "productName": "Your App Name",
    "directories": {
      "output": "release"
    }
  }
}

📝 Development Guide

Creating New Pages

1. Create a new file in src/pages/:

// src/pages/my-page.tsx
export default function MyPage() {
  return <div>My New Page</div>;
}

2. Add route in src/App.tsx:

import MyPage from "./pages/my-page";

<Route path="/my-page" element={<MyPage />} />

Styling with Tailwind CSS

Use Tailwind utility classes directly:

<div className="flex flex-col items-center justify-center min-h-screen bg-gradient-to-br from-primary-500 to-secondary-500">
  <h1 className="text-4xl font-bold text-white">Hello World</h1>
</div>

Customize in src/tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          DEFAULT: "#0070f3",
          dark: "#0056cc",
        },
      },
    },
  },
};

Using HeroUI Components

import { Button, Card, CardBody } from "@heroui/react";

<Card>
  <CardBody>
    <Button color="primary" size="lg">
      Click Me
    </Button>
  </CardBody>
</Card>;

⚠️ Important: Link Usage

When using links in this template, you must distinguish between internal navigation and external links:

For internal navigation (React Router):

import { Link } from "react-router-dom";

// ✅ Correct - No page refresh
<Link to="/docs">Documentation</Link>
<Link to="/about">About</Link>

For external websites:

import { Link } from "@heroui/link";

// ✅ Correct - Opens in browser
<Link href="https://github.com" isExternal>
  GitHub
</Link>;

❌ Common Mistake:

import { Link } from "@heroui/link";

// Wrong! This causes page refresh and breaks routing
<Link href="/docs">Documentation</Link>;

Why this matters:

• HeroUI's Link uses <a> tags which trigger page reloads
• In Electron with HashRouter, page reloads lose the route state → white screen
• Always use react-router-dom's Link for internal navigation

🔐 IPC Communication

From Renderer to Main

Preload Script (electron/preload.ts):

contextBridge.exposeInMainWorld("electronAPI", {
  sendMessage: (channel: string, data: any) => {
    ipcRenderer.send(channel, data);
  },
  onMessage: (channel: string, callback: Function) => {
    ipcRenderer.on(channel, (event, ...args) => callback(...args));
  },
});

Usage in React:

window.electronAPI.sendMessage("custom-event", { data: "value" });

🐛 Troubleshooting

Common Issues

White screen after build?

• Ensure you're using HashRouter for Electron (already configured)
• Check that all assets are included in the files array in package.json

Hot reload not working?

• Make sure you're running yarn dev not yarn build
• Check that vite.config.ts has HMR enabled

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Electron for the cross-platform framework
• HeroUI for the beautiful component library
• Vite for the blazing fast build tool
• Tailwind CSS for the utility-first CSS
• React for the UI library

📞 Support

If you found this template helpful, please consider giving it a ⭐ on GitHub!

For questions or issues:

• Open an Issue
• Start a Discussion

---

Built with ❤️ using Electron, React, Vite, and HeroUI