{"id":33311314,"url":"https://github.com/awe-templates/electron-vite-starter","last_synced_at":"2026-06-13T17:32:10.768Z","repository":{"id":324314655,"uuid":"1096762923","full_name":"awe-templates/electron-vite-starter","owner":"awe-templates","description":"Modern, type-safe Electron starter template with Vite, TypeScript","archived":false,"fork":false,"pushed_at":"2026-03-18T08:30:10.000Z","size":630,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-19T00:04:18.380Z","etag":null,"topics":["electron","electron-starter","electron-starter-template","electron-vite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awe-templates.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-14T22:59:48.000Z","updated_at":"2026-03-18T08:30:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/awe-templates/electron-vite-starter","commit_stats":null,"previous_names":["awe-templates/electron-vite-starter"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/awe-templates/electron-vite-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awe-templates%2Felectron-vite-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awe-templates%2Felectron-vite-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awe-templates%2Felectron-vite-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awe-templates%2Felectron-vite-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awe-templates","download_url":"https://codeload.github.com/awe-templates/electron-vite-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awe-templates%2Felectron-vite-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34294410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","electron-starter","electron-starter-template","electron-vite"],"created_at":"2025-11-19T05:00:38.114Z","updated_at":"2026-06-13T17:32:10.750Z","avatar_url":"https://github.com/awe-templates.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Electron Vite Starter\n\nA modern, type-safe Electron starter template with Vite and TypeScript.\n\n![CI Test Status](https://github.com/awe-templates/electron-vite-starter/workflows/test/badge.svg)\n![Electron Version](https://img.shields.io/github/package-json/dependency-version/awe-templates/electron-vite-starter/dev/electron)\n![TypeScript Version](https://img.shields.io/github/package-json/dependency-version/awe-templates/electron-vite-starter/dev/typescript)\n![Vite Version](https://img.shields.io/github/package-json/dependency-version/awe-templates/electron-vite-starter/dev/vite)\n![Vitest Version](https://img.shields.io/github/package-json/dependency-version/awe-templates/electron-vite-starter/dev/vitest)\n![PostCSS Version](https://img.shields.io/github/package-json/dependency-version/awe-templates/electron-vite-starter/dev/postcss)\n\n- [Electron Vite Starter](#electron-vite-starter)\n  - [✨ Features](#-features)\n  - [🔒 Security Features](#-security-features)\n  - [📁 Project Structure](#-project-structure)\n  - [🚀 Getting Started](#-getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Installation](#installation)\n    - [Development](#development)\n    - [Building](#building)\n    - [Testing](#testing)\n    - [Linting \\\u0026 Formatting](#linting--formatting)\n  - [🔌 Type-Safe IPC Communication](#-type-safe-ipc-communication)\n    - [Defining IPC Routes](#defining-ipc-routes)\n    - [Registering Handlers (Main Process)](#registering-handlers-main-process)\n    - [Exposing API (Preload Script)](#exposing-api-preload-script)\n    - [Using in Renderer Process](#using-in-renderer-process)\n  - [🗺️ Path Aliases](#️-path-aliases)\n  - [🔄 Development Workflow](#-development-workflow)\n  - [📝 Conventional Commits](#-conventional-commits)\n    - [Commit Message Format](#commit-message-format)\n    - [Allowed Types](#allowed-types)\n    - [Examples](#examples)\n    - [Git Hooks](#git-hooks)\n  - [📂 Directory Organization](#-directory-organization)\n  - [⚠️ Error Handling](#️-error-handling)\n  - [💻 VSCode Integration](#-vscode-integration)\n  - [📦 Package Scripts](#-package-scripts)\n  - [🏗️ Building for Distribution](#️-building-for-distribution)\n    - [Prerequisites](#prerequisites-1)\n    - [Build Configuration](#build-configuration)\n    - [Packaging Commands](#packaging-commands)\n    - [Build Outputs](#build-outputs)\n    - [Customizing the Build](#customizing-the-build)\n    - [Code Signing](#code-signing)\n  - [📄 License](#-license)\n  - [🤝 Contributing](#-contributing)\n\n## ✨ Features\n\n- **[Electron](https://electronjs.org/)** - Latest stable version for cross-platform desktop apps\n- **[TypeScript](https://www.typescriptlang.org/)** - Full type safety with strict mode enabled\n- **[Vite](https://vite.dev/)** - Lightning-fast build tool with HMR\n- **[@egoist/tipc](https://github.com/egoist/tipc)** - Type-safe IPC communication\n- **[@electron-toolkit](https://github.com/alex8088/electron-toolkit)** - Utilities for Electron development (utils, preload, tsconfig)\n- **[ESLint](https://eslint.org/)** - Code linting with flat config\n- **[Prettier](https://prettier.io/)** - Code formatting\n- **[Vitest](https://vitest.dev/)** - Fast unit testing with Electron API mocks\n- **[PostCSS](https://postcss.org/)** - CSS processing with Autoprefixer\n- **[Commitlint](https://commitlint.js.org/)** - Conventional commit message validation\n- **[Husky](https://typicode.github.io/husky/)** - Git hooks for automated quality checks\n- **[GitHub Actions](https://github.com/features/actions)** - CI/CD workflow for automated testing across platforms\n\n## 🔒 Security Features\n\nThis template follows Electron security best practices:\n\n- ✅ Context isolation enabled\n- ✅ Node integration disabled in renderer\n- ✅ Preload script with controlled API exposure\n- ✅ Content Security Policy (CSP) headers\n- ✅ Navigation and window creation restrictions\n- ✅ External links open in default browser\n- ✅ Single instance lock\n\n## 📁 Project Structure\n\n```txt\nelectron-vite-starter/\n├── electron/              # Electron-specific code\n│   ├── main/              # Main process\n│   │   ├── main.ts        # Entry point\n│   │   ├── window.ts      # Window management\n│   │   ├── menu.ts        # Application menu\n│   │   └── ipc.ts         # IPC handlers\n│   ├── preload/           # Preload scripts\n│   │   └── preload.ts     # API exposure\n│   └── shared/            # Shared IPC definitions\n│       └── ipc.ts         # IPC route definitions\n├── src/                   # Application code (renderer)\n│   ├── index.html         # HTML template\n│   ├── main.ts            # TypeScript entry point\n│   └── styles.css         # Styles\n├── types/                 # Type definitions\n│   └── vite-env.d.ts      # Vite and Electron API types\n├── tests/                 # Test files\n│   ├── setup.ts           # Test setup and mocks\n│   ├── main/              # Main process tests\n│   └── renderer/          # Renderer process tests\n├── build/                 # Build resources\n│   ├── README.md          # Icon setup instructions\n│   ├── icon.icns          # macOS icon (add this)\n│   ├── icon.ico           # Windows icon (add this)\n│   └── icons/             # Linux icons (add these)\n├── .scripts/              # Build scripts\n│   └── dev.mjs            # Development script\n├── .github/               # GitHub configuration\n│   └── workflows/         # CI/CD workflows\n│       └── ci.yml         # Continuous integration\n├── .husky/                # Git hooks\n│   ├── pre-commit         # Pre-commit hook (lint, type-check, test)\n│   └── commit-msg         # Commit message validation\n├── vite.main.config.ts    # Vite config for main process\n├── vite.renderer.config.ts # Vite config for renderer\n├── tsconfig.json          # Base TypeScript config\n├── tsconfig.main.json     # Main process TS config\n├── tsconfig.renderer.json # Renderer process TS config\n├── electron-builder.yml   # electron-builder config\n├── eslint.config.mjs      # ESLint flat config\n├── commitlint.config.mjs  # Commitlint config\n├── .prettierrc            # Prettier config\n├── .gitattributes         # Git attributes for consistent line endings\n└── vitest.config.ts       # Vitest config\n```\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Node.js 22 or higher\n- pnpm (recommended) or npm\n\n### Installation\n\n```bash\n# Clone or download this template\ngit clone \u003crepository-url\u003e\n\n# Install dependencies\npnpm install\n```\n\n### Development\n\nStart the development server with hot reload:\n\n```bash\npnpm dev\n```\n\nThis will:\n\n1. Start Vite dev server for the renderer process (\u003chttp://localhost:5173\u003e)\n2. Build and watch the main process\n3. Launch Electron with DevTools open\n\n### Building\n\nBuild for production:\n\n```bash\npnpm build\n```\n\nThis creates optimized builds for both main and renderer processes in the `dist/` directory.\n\n### Testing\n\nRun tests:\n\n```bash\n# Run all tests\npnpm test\n\n# Run tests with UI\npnpm test:ui\n```\n\n### Linting \u0026 Formatting\n\n```bash\n# Run ESLint\npnpm lint\n\n# Fix ESLint issues\npnpm lint:fix\n\n# Format code with Prettier\npnpm format\n\n# Check formatting\npnpm format:check\n\n# Type check\npnpm type-check\n```\n\n## 🔌 Type-Safe IPC Communication\n\nThis template uses [@egoist/tipc](https://github.com/egoist/tipc) for fully type-safe IPC communication.\n\n### Defining IPC Routes\n\nDefine your IPC routes in `electron/shared/ipc.ts`:\n\n```typescript\nimport { tipc } from '@egoist/tipc/main';\nimport os from 'os';\n\nexport const router = {\n  // Get app version\n  getAppVersion: tipc.create().procedure.action(async () =\u003e {\n    const { app } = await import('electron');\n    return app.getVersion();\n  }),\n\n  // Complex query with structured response\n  getSystemInfo: tipc\n    .create()\n    .procedure.action(async () =\u003e {\n      return {\n        platform: os.platform(),\n        arch: os.arch(),\n        version: os.release(),\n        hostname: os.hostname(),\n      };\n    }),\n};\n\nexport type AppRouter = typeof router;\n```\n\n### Registering Handlers (Main Process)\n\nRegister the router in `electron/main/ipc.ts`:\n\n```typescript\nimport { registerIpcMain } from '@egoist/tipc/main';\nimport { router } from '@shared/ipc';\n\n// Register IPC handlers\nregisterIpcMain(router);\n```\n\n### Exposing API (Preload Script)\n\nThe preload script (`electron/preload/preload.ts`) creates a type-safe client and exposes individual methods to the renderer:\n\n```typescript\nimport { contextBridge, ipcRenderer } from 'electron';\nimport { createClient } from '@egoist/tipc/renderer';\nimport type { AppRouter } from '@shared/ipc';\n\n// Create type-safe IPC client\nconst api = createClient\u003cAppRouter\u003e({\n  ipcInvoke: ipcRenderer.invoke.bind(ipcRenderer),\n});\n\n// Expose individual API methods (Proxy objects cannot be cloned by contextBridge)\ncontextBridge.exposeInMainWorld('electronAPI', {\n  api: {\n    getAppVersion: () =\u003e api.getAppVersion(),\n    saveData: (input: { key: string; value: unknown }) =\u003e api.saveData(input),\n    getSystemInfo: () =\u003e api.getSystemInfo(),\n    getVersions: () =\u003e api.getVersions(),\n  },\n  platform: process.platform,\n});\n```\n\n### Using in Renderer Process\n\nUse the exposed API in your TypeScript code:\n\n```typescript\n// Fully type-safe! TypeScript knows the parameter and return types\nconst version = await window.electronAPI.api.getAppVersion();\nconsole.log('App version:', version);\n\n// Example with button\nconst button = document.getElementById('my-button');\nbutton?.addEventListener('click', async () =\u003e {\n  const info = await window.electronAPI.api.getSystemInfo();\n  console.log(info);\n});\n```\n\n## 🗺️ Path Aliases\n\nThe following path aliases are configured:\n\n- `@main/*` → `electron/main/*`\n- `@app/*` → `src/*`\n- `@shared/*` → `electron/shared/*`\n- `@preload/*` → `electron/preload/*`\n- `@types/*` → `types/*`\n\nExample usage:\n\n```typescript\n// In Electron code\nimport { router } from '@shared/ipc';\nimport { createMainWindow } from '@main/window';\n\n// Import types\nimport type { ElectronAPI } from '@preload/preload';\n```\n\n## 🔄 Development Workflow\n\n1. **Add new IPC routes**: Define routes in `electron/shared/ipc.ts`\n2. **Implement handlers**: Add handlers in `electron/main/ipc.ts`\n3. **Use in renderer**: Call the type-safe API from your TypeScript code in `src/`\n4. **Test**: Write tests in `tests/` directory\n5. **Build**: Run `pnpm build` for production\n\n## 📝 Conventional Commits\n\nThis project uses [Conventional Commits](https://www.conventionalcommits.org/) with automated validation via commitlint and husky.\n\n### Commit Message Format\n\n```markdown\n\u003ctype\u003e(\u003coptional scope\u003e): \u003csubject\u003e\n\n\u003coptional body\u003e\n\n\u003coptional footer\u003e\n```\n\n### Allowed Types\n\n- `feat` - New feature\n- `fix` - Bug fix\n- `docs` - Documentation only changes\n- `style` - Code style changes (formatting, etc.)\n- `refactor` - Code refactoring\n- `perf` - Performance improvements\n- `test` - Adding or updating tests\n- `build` - Build system or dependency changes\n- `ci` - CI configuration changes\n- `chore` - Other changes that don't modify src or test files\n- `revert` - Reverts a previous commit\n\n### Examples\n\n```bash\nfeat: add dark mode toggle\nfix(auth): resolve login timeout issue\ndocs: update README with installation steps\ntest: add unit tests for IPC handlers\n```\n\n### Git Hooks\n\nThe project uses husky to run automated checks:\n\n- **pre-commit**: Runs `pnpm lint`, `pnpm type-check`, and `pnpm test` before allowing commits\n- **commit-msg**: Validates commit messages follow conventional commit format\n\n## 📂 Directory Organization\n\n- **`electron/`** - All Electron-specific code (main process, preload, IPC definitions)\n- **`src/`** - Your application code (renderer process, UI, business logic)\n- **`tests/`** - Test files mirroring the structure\n- **`.scripts/`** - Build and development scripts\n\n## ⚠️ Error Handling\n\nExample of error handling in IPC:\n\n```typescript\n// In electron/shared/ipc.ts\nsaveData: tipc\n  .create()\n  .procedure.input\u003c{ key: string; value: unknown }\u003e()\n  .action(async ({ input }) =\u003e {\n    try {\n      await saveToDatabase(input.key, input.value);\n      return { success: true, message: 'Saved successfully' };\n    } catch (error) {\n      return {\n        success: false,\n        message: error instanceof Error ? error.message : 'Unknown error',\n      };\n    }\n  }),\n\n// Renderer process\nconst result = await window.electronAPI.api.saveData({\n  key: 'myKey',\n  value: 'myValue',\n});\n\nif (result.success) {\n  console.log('Success:', result.message);\n} else {\n  console.error('Error:', result.message);\n}\n```\n\n## 💻 VSCode Integration\n\nRecommended extensions (defined in `.vscode/extensions.json`):\n\n- ESLint\n- Prettier\n- TypeScript\n- Vitest\n\nSettings are pre-configured in `.vscode/settings.json` for:\n\n- Format on save\n- Auto-fix ESLint issues\n- TypeScript workspace version\n\n## 📦 Package Scripts\n\n| Script | Description |\n|--------|-------------|\n| `pnpm dev` | Start development server with hot reload |\n| `pnpm build` | Build for production |\n| `pnpm build:main` | Build main process only |\n| `pnpm build:renderer` | Build renderer process only |\n| `pnpm package` | Build and package for current platform |\n| `pnpm package:mac` | Build and package for macOS |\n| `pnpm package:win` | Build and package for Windows |\n| `pnpm package:linux` | Build and package for Linux |\n| `pnpm test` | Run all tests |\n| `pnpm test:ui` | Run tests with UI |\n| `pnpm lint` | Run ESLint |\n| `pnpm lint:fix` | Fix ESLint issues |\n| `pnpm format` | Format code with Prettier |\n| `pnpm format:check` | Check code formatting |\n| `pnpm type-check` | Run TypeScript compiler checks |\n\n## 🏗️ Building for Distribution\n\nThis template comes with electron-builder pre-configured for packaging and distributing your application.\n\n### Prerequisites\n\nBefore building for distribution, you need to provide application icons. See [`build/README.md`](build/README.md) for detailed instructions on creating and adding icons for each platform.\n\n### Build Configuration\n\nThe electron-builder configuration is already set up in `electron-builder.yml` with sensible defaults:\n\n- **appId**: `com.electron.app` (change this to your app's identifier)\n- **productName**: `Electron Vite Starter` (change this to your app's name)\n- **Output directory**: `release/`\n- **Build resources**: `build/` (place icons here)\n\n### Packaging Commands\n\n```bash\n# Package for current platform\npnpm package\n\n# Package for specific platforms\npnpm package:mac     # Creates DMG and ZIP for macOS\npnpm package:win     # Creates NSIS installer and portable EXE for Windows\npnpm package:linux   # Creates AppImage and DEB for Linux\n```\n\n### Build Outputs\n\nAfter packaging, you'll find the installers in the `release/` directory:\n\n**macOS**\n\n- `.dmg` - Disk image installer\n- `.zip` - Compressed application\n\n**Windows**\n\n- `.exe` - NSIS installer\n- `.exe` (portable) - Standalone executable\n\n**Linux**\n\n- `.AppImage` - Universal Linux application\n- `.deb` - Debian package\n\n### Customizing the Build\n\nEdit `electron-builder.yml` to customize your build configuration:\n\n```yaml\nappId: com.yourcompany.yourapp\nproductName: Your App Name\ncopyright: Copyright © 2025 Your Company\n\nmac:\n  category: public.app-category.productivity\n\nwin:\n  target:\n    - nsis\n    - portable\n    - zip\n\nlinux:\n  target:\n    - AppImage\n    - deb\n    - rpm\n  category: Utility\n```\n\n### Code Signing\n\nFor production releases, you should code sign your applications:\n\n**macOS**: Set up Apple Developer certificates and add to `electron-builder.yml`:\n\n```yaml\nmac:\n  identity: Developer ID Application: Your Name (TEAM_ID)\n```\n\n**Windows**: Obtain a code signing certificate and configure in `electron-builder.yml`:\n\n```yaml\nwin:\n  certificateFile: path/to/cert.pfx\n  certificatePassword: password\n```\n\nSee [electron-builder documentation](https://www.electron.build/) for comprehensive configuration options and platform-specific details.\n\n## 📄 License\n\nMIT\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawe-templates%2Felectron-vite-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawe-templates%2Felectron-vite-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawe-templates%2Felectron-vite-starter/lists"}