Installation
Install dependencies and run the desktop app in development.
This page takes you from a fresh clone to the Electron development window. The development command runs electron-vite in watch mode and launches the main, preload, and renderer bundles together.
Prerequisites
| Tool | Version | Notes |
|---|---|---|
| Node.js | `^20.19.0 | |
| pnpm | 11.1.3 | Pinned by packageManager in package.json. Use Corepack to stay on the pinned version. |
No platform SDK is required for normal development. Signing, notarization, and target-specific installer validation come later on the Packaging page.
Install and run
Clone the template and enter the project directory.
git clone <your-repo-url> my-desktop-app
cd my-desktop-appInstall dependencies.
pnpm installThe postinstall script runs electron-builder install-app-deps so native
Electron dependencies are rebuilt for your local platform.
Create local environment config.
cp .env.example .envThe current renderer validates VITE_SUPABASE_URL and
VITE_SUPABASE_PUBLISHABLE_KEY before it mounts. Leave the sample values
only for a shell-only first look; replace them with a real Supabase project
before testing auth, profile, avatar, todos, or billing.
Start the Electron development app.
pnpm devscripts/dev.mjs wraps electron-vite dev -w. On Linux it sets
ELECTRON_DISABLE_SANDBOX=1 for developer machines that do not have the
Electron SUID sandbox helper installed.
With default feature flags, auth and auto-update surfaces are on, billing is
off, and the Showcase demo is on. Billing stays hidden until
VITE_BILLING_ENABLED=true; the Supabase-backed auth/data examples need real
Supabase values before they are useful.
Verify the installation
After pnpm dev starts, check these surfaces:
- The desktop window opens with the custom titlebar and sidebar shell.
- Home renders, and the Showcase plus Components entries appear while showcase flags are enabled.
Cmd/Ctrl+Kopens the command palette.- Settings persists a change, such as theme or locale, after restart.
- First-run onboarding appears until completed.
- Logs and About render diagnostics without exposing secrets.
Scripts
| Command | Purpose |
|---|---|
pnpm dev | Start Electron and Vite in watch mode. |
pnpm start | Preview a built app with electron-vite preview. |
pnpm lint | Run ESLint and auto-fix. |
pnpm lint:check | Run ESLint with --max-warnings=0. |
pnpm typecheck | Run tsc -b --noEmit across the node and web configs. |
pnpm test | Run the core Vitest suite. |
pnpm test:all | Run all Vitest configs. |
pnpm test:smoke | Build the app and run Playwright smoke tests with VITE_E2E_BYPASS_AUTH=true. |
pnpm build:mac | Build a macOS distributable with electron-builder. |
pnpm build:win | Build a Windows NSIS installer. |
pnpm build:linux | Build Linux AppImage, Snap, and Deb artifacts. |
pnpm build:unpack | Build an unpacked app directory without installer packaging. |
pnpm supabase:deploy | Deploy the Supabase Edge Functions in supabase/functions. |
pnpm analyze:bundle | Inspect Electron/Vite bundle output. |
pnpm rebrand | Rewrite product name, slug, app id, scheme, and related assets. |
Minimum validation before changing the template:
pnpm lint:check
pnpm typecheck
pnpm testRun pnpm test:smoke when you change routing, shell behavior, auth gates, or
desktop IPC surfaces.
First-run failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Vite or electron-vite refuses to start | Node is below the supported range | Install Node ^20.19.0 or >=22.12.0. |
| pnpm warns about the package manager | Local pnpm does not match pnpm@11.1.3 | Enable Corepack and run corepack prepare pnpm@11.1.3 --activate. |
| Native module rebuild errors | postinstall could not complete | Re-run pnpm install; if needed, delete node_modules and reinstall with the supported Node version. |
| Supabase configuration screen appears | Missing or invalid VITE_SUPABASE_URL / VITE_SUPABASE_PUBLISHABLE_KEY | Copy .env.example to .env, set both values, and restart pnpm dev. |
| Linux fails before the window opens | Local sandbox helper is unavailable | Use pnpm dev; the wrapper sets ELECTRON_DISABLE_SANDBOX=1 only on Linux development machines. |
| The dev server port is already used | Another Vite/Electron session is running | Stop the old session, or find and kill the process that owns the port. |