Overview
A production-oriented Electron desktop starter with secure IPC, auth, billing, settings, updates, and a one-pass rebrand wired together.
The Electron template is a production-oriented desktop starter for teams shipping commercial apps on macOS, Windows, and Linux. It packages the plumbing that most desktop products need: auth, settings, auto-update wiring, logging, Creem billing, secure IPC, installer builds, and a one-pass rebrand script.
Use it as a clone-and-ship foundation. Replace the default brand, pages, demo surfaces, and business logic, then keep the Electron shell and typed process boundaries in place.
"Production-oriented" means the template gives you real desktop app plumbing, not a launch guarantee. Some surfaces are Example, Opt-in slot, or Removable demo features and should be adapted to your own product before release.
The default identity is intentionally literal while you evaluate the template:
Soar Electron, soar-electron://, and com.soarstarter.electron. Run
pnpm rebrand when you are ready to replace those values across code,
electron-builder.yml, package metadata, and app assets.
Tech stack
| Layer | Choice |
|---|---|
| Desktop runtime | Electron 40.1, electron-builder 26.7, electron-updater 6.8 |
| UI runtime | React 19.2, React DOM 19.2, React Router 7.13 |
| Language and build | TypeScript 5.9, Vite 7.3, electron-vite 5.0 |
| Styling | Tailwind CSS 4.1, shadcn-style primitives, Radix UI, CVA, sonner |
| App state | zustand 5, TanStack Query 5, react-hook-form, zod 4 |
| Backend client | Supabase JS 2.106 with typed database access |
| Billing | Creem via Supabase Edge Functions and a Supabase entitlement read model |
| Desktop shell | Conveyor IPC, Zod validation, settings store, tray, menus, shortcuts |
| Observability | electron-log, redacted diagnostics, optional @sentry/electron |
| Localization | i18next and react-i18next, English and Simplified Chinese |
| Testing | Vitest 4, Testing Library, Playwright smoke tests |
| Tooling | pnpm 11.1.3, ESLint, Prettier, bundle analyzer, rebrand script |
Feature status
Status labels used throughout this root:
- Integrated - wired into the app and available by default.
- Flag-gated - stripped or hidden by a build-time flag; defaults are called out on each page.
- Opt-in slot - dark until configured and the user opts in.
- Example - working demo code meant to be replaced with your product logic.
- Removable demo - evaluation surface marked with
[template-demo]and covered by the Showcase deletion checklist.
| Area | Status | Scope |
|---|---|---|
| Shell and IPC | Integrated | Main/preload/renderer split, sandboxed renderer, contextBridge preload, Conveyor APIs, Zod-validated IPC args and returns |
| Desktop surfaces | Integrated | Custom titlebar, sidebar shell, command palette, native menus, tray, shortcuts, logs, diagnostics, guarded external navigation |
| Settings | Integrated | Versioned JSON settings store, forward migrations, backup import/export, search, theme, locale, proxy, storage, notifications, shortcuts |
| Auto-update | Flag-gated | VITE_AUTO_UPDATE_ENABLED defaults on; background/manual checks use electron-updater and a generic self-hosted feed |
| Authentication and data | Flag-gated / Example | Supabase email auth defaults on; profile, avatar, and todos are examples that need the Supabase schema from the setup docs |
| Billing | Flag-gated | VITE_BILLING_ENABLED defaults off; Creem checkout, customer portal, license mode, and <FeatureGate> activate only when configured |
| Privacy slots | Opt-in slot | Sentry error reporting and provider-agnostic analytics no-op until configured and enabled by persisted settings |
| Showcase catalog | Removable demo | Capability catalog, component gallery, and demo routes live behind showcase flags and [template-demo] markers |
| Distribution | Integrated | macOS DMG, Windows NSIS, Linux AppImage/Snap/Deb, signing/notarization env hooks, self-hosted update metadata |
| Developer experience | Integrated | pnpm dev, quality gate scripts, colocated tests, bundle analysis, typed IPC patterns, one-pass rebrand |
App surface map
The renderer is a React SPA in a desktop shell:
- Sidebar layout - Home, Showcase, Components, Logs, Help, Settings, About, and Billing when billing is enabled.
- Authentication - Login, Register, Forgot Password, and Reset Password routes render without the shell.
- Settings center - 8 tabs today: General, Appearance, Notifications, Shortcuts, Proxy, Storage, Updates, and Advanced, plus translated search.
- Account - a separate page for signed-in user profile and avatar flows.
- Update page - streams check, download, install, error, and release-note state from the main process.
- Command palette -
Cmd/Ctrl+Kopens route actions, settings shortcuts, recent files, and Showcase actions when the demo layer is enabled. - Onboarding gate - first-run onboarding persists through the main-process settings store and can require EULA acceptance when configured.
The current renderer validates VITE_SUPABASE_URL and
VITE_SUPABASE_PUBLISHABLE_KEY before mounting. You can explore the shell
with placeholder values from .env.example, but real auth, profile, avatar,
todos, and billing flows need a Supabase project.
Start here
Follow this path for the fastest route from clone to a distributable desktop app:
Installation
Install dependencies and run the Electron app locally.
Environment Variables
Understand renderer-public config, main-process config, and Edge secrets.
Supabase Setup
Create the backend, auth redirects, storage bucket, and schema the app expects.
Billing
Enable Creem checkout and account-bound entitlements.
Packaging
Build macOS, Windows, and Linux installers.
Auto-Update
Host the generic update feed and wire release builds.