electron-react-starter-kit

A secure, typed, and production-minded Electron + React starter for building cross-platform desktop apps.

Use Template · Quick Start · Docs · Roadmap · Distribution · Auth Recipes

---

Overview

electron-react-starter-kit is a desktop application template for teams that want the Electron security and platform plumbing handled before product work begins.

It ships a preload-first architecture, typed IPC, typed config boundaries, provider-neutral auth, secure credential storage, TanStack Router and Query, route error boundaries, persisted settings, desktop-aware theming, native file dialogs, notifications, logging, tests, and packaging scripts. Use it from GitHub with the Use this template button, then adapt the app-specific pieces for your client or product. The README is the polished front door; the implementation manual lives in docs/.

Built With

Discover the core stack driving this starter template:

Technology	Badge	Purpose
Electron		Cross-platform desktop runtime
React		Component-driven renderer UI
TypeScript		Static typing across main, preload, and renderer code
Vite / electron-vite		Fast development server and production bundling
TanStack Router		Type-safe file-based routing and layouts
TanStack Query		Async state, caching, and IPC-backed queries
Tailwind CSS		Utility-first styling foundation
shadcn/ui		Accessible component primitives styled with Tailwind CSS
electron-store		Main-process persistence for normal user preferences
electron-log		Main-process diagnostics and production log files
Zod		Runtime validation for IPC payloads and settings contracts
Vitest		Unit, hook, and component tests
Biome		Formatting, linting, and import organization

Feature Highlights

Secure Electron foundation

• Secure BrowserWindow defaults with context isolation, sandboxing, and disabled renderer Node.js integration.
• Restrictive CSP, blocked navigation, filtered external URLs, and default-deny permission prompts.
• Trusted IPC sender validation before main-process handlers run.

Typed app architecture

• Preload-only window.api surface for renderer access to Electron capabilities.
• Typed IPC registrar with Zod input validation and renderer-safe error messages.
• Typed config boundaries for main runtime env, renderer public env, settings, and secure storage.
• TanStack Router file routes with (auth) and guarded (app) layout groups.
• Root, auth, and app route error/pending/not-found fallbacks.
• TanStack Query factories and hooks for IPC-backed renderer state.
• Provider-neutral auth session contract backed by a replaceable development auth provider.
• Main-process secure storage for durable provider credential metadata.

Desktop platform features

• Main-process settings persistence with electron-store.
• Desktop-aware theme switching through Electron nativeTheme.
• Native open/save dialogs, drag/drop path resolution, and reusable file upload UI.
• Native notification preference, support checks, and focus-aware delivery.
• Safe window bounds restore with off-screen fallback and debounced persistence.

Production workflow

• Scoped main-process logging and sanitized Electron event logging.
• Vitest, Testing Library, jsdom, coverage, Biome, Husky, and commitlint.
• electron-builder scripts for Windows, macOS, and Linux packages.
• Packaging guidance for Windows .exe, macOS .dmg, and Linux AppImage/Debian artifacts.
• GitHub Actions release workflow for building packages and uploading draft GitHub Release assets.

Quick Start

Prerequisites

• Node.js 22 or newer
• pnpm 10 or newer

Create From The Template

On GitHub, click Use this template to create a new repository with this starter as the base.

Direct template link:

Create a repository from this template

After creating your repository:

git clone https://github.com/<your-org>/<your-new-repo>.git
cd <your-new-repo>
pnpm install
pnpm dev

Clone This Repository Directly

Use this path only when contributing to the starter itself:

git clone https://github.com/AchuAshwath/electron-react-starter-kit.git
cd electron-react-starter-kit
pnpm install
pnpm dev

Common Scripts

pnpm dev           # Start the Electron app in development mode
pnpm build         # Typecheck and build production bundles
pnpm test          # Run unit and component tests
pnpm lint          # Run Biome checks
pnpm format:check  # Verify formatting
pnpm ci            # Run the full local verification chain

Documentation

Core docs describe features that are already wired into the starter:

• Documentation index for the full reading order.
• TanStack Router, Error Boundaries, Auth Routing, Auth Session Contract, Secure Storage, Config Boundaries, TanStack Query, and UI Foundation for renderer app architecture.
• System Info for the smallest complete IPC + Query example.
• Typed IPC and Electron Security for the main/preload/renderer boundary.
• Settings, Theme, File Dialogs and Upload, Notifications, and Window State for shipped platform features.
• Logging, Testing, and Packaging for production workflow.
• Build and Distribution explains packaging scripts, generated artifacts, app identity customization, and cross-platform build limits.

Optional recipes live in docs/examples/. They are intentionally not installed behavior because they depend on app, client, provider, backend, or deployment decisions:

• Auth-ready architecture
• Auth provider recipes
• GitHub Releases distribution
• Imported file workflow
• Auto-update
• Distribution hardening

Project Structure

.
|-- build/                   # Platform icons, entitlements, and build resources
|-- docs/                    # Core starter guides
|   `-- examples/            # Optional recipes and implementation specs
|-- resources/               # Runtime app assets
|-- src/
|   |-- main/                # Electron lifecycle, IPC handlers, platform services
|   |-- preload/             # Typed contextBridge API exposed to the renderer
|   `-- renderer/            # React app, routes, hooks, query factories, UI
|-- electron-builder.yml     # Packaging configuration
|-- electron.vite.config.ts  # Main, preload, and renderer build configuration
`-- vitest.config.ts         # Test configuration

Roadmap

The roadmap is split into core starter work and optional recipes.

Core infrastructure next:

• Reliability polish around crash recovery, abnormal exits, and support diagnostics.

Optional recipes next:

• Durable imported-file workflow.
• Auto-update flow.
• Distribution hardening checklist.

See the full roadmap.

Design Principle

Core starter features should be useful to almost every serious Electron app. Provider-specific auth, auto-update publishing, durable file imports, and distribution hardening details are documented as recipes so each client app can make the right deployment and product choices.