Installation
Install the toolchain — Node, pnpm, Rust, and per-OS webview deps — and run the desktop app in development.
This page takes you from a fresh clone to a running desktop window. pnpm dev
runs tauri dev: it compiles the Rust shell and serves the Vite frontend on
port 1420, then opens the app window with hot-reload.
Prerequisites
Unlike a web template, Tauri builds a native binary, so you need the Rust toolchain and your platform's webview libraries in addition to Node.
| Tool | Version | Notes |
|---|---|---|
| Node.js | ^20.19.0 || >=22.12.0 | Required by the Vite toolchain. |
| pnpm | 11.1.3 | Pinned by packageManager in package.json. Use Corepack to stay on the pinned version. |
| Rust | stable (via rustup) | Compiles the src-tauri crate. |
| Webview deps | per-OS | See the tab below and the Tauri prerequisites guide for the authoritative package lists. |
Install the Xcode Command Line Tools and the Rust toolchain:
xcode-select --install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shThe system WKWebView ships with macOS, so no extra webview runtime is
needed.
Install the Microsoft C++ Build Tools (MSVC toolchain), the WebView2
runtime (preinstalled on Windows 11; the installer also fetches it via
downloadBootstrapper), and the Rust toolchain from
rustup.rs.
Install the WebKitGTK stack and build essentials. On Debian/Ubuntu:
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shlibayatana-appindicator3-dev backs the system tray; check the Tauri guide
for your distribution's package names.
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 installCreate local environment config.
cp .env.example .envThe sample values are enough to boot the shell. With VITE_AUTH_ENABLED
on (the default), the app validates VITE_SUPABASE_URL and
VITE_SUPABASE_PUBLISHABLE_KEY before it mounts — the placeholders in
.env.example pass, but replace them with a real Supabase project before
testing auth, profile, avatar, todos, or billing.
Start the desktop app in development.
pnpm devThe first pnpm dev compiles the entire Rust crate and can take several
minutes — this is normal, not a hang. Subsequent runs are incremental and
start in seconds.
With default flags the app boots with no backend at all when auth is off,
or against your Supabase project when it is on. dev:web (pnpm dev:web) runs
the Vite frontend alone for fast UI iteration, but it has no native surface
— commands, deep links, tray, and the keychain are unavailable there.
Backend expectations
- Default flags: auth on, auto-update on, billing off, Showcase on.
- No Supabase project yet? The shell runs on the placeholder env; sign-in simply fails against a non-existent project.
- Billing stays dark until
VITE_BILLING_ENABLED=trueand the Creem env is set (see Billing). - Auth off (
VITE_AUTH_ENABLED=false) removes every sign-in surface and the app runs as a purely local desktop tool.
Verify the installation
After the window opens, check these surfaces:
- The window opens with the frameless custom titlebar (
decorations: false) and the sidebar shell. - Home and Showcase render (Showcase appears while the flag is on).
Cmd/Ctrl+Kopens the command palette.- A Settings change (theme or locale) persists after you restart the app.
- First-run onboarding appears until you complete it.
Scripts
| Command | Purpose |
|---|---|
pnpm dev | Run tauri dev: Rust shell + Vite frontend with hot-reload. |
pnpm dev:web | Run the Vite frontend alone (no native surface). |
pnpm build | Run tauri build: full release bundle (installers). |
pnpm build:web | Type-check and build the frontend bundle only. |
pnpm preview | Preview the built frontend with Vite. |
pnpm lint / pnpm lint:check | ESLint auto-fix / gate (--max-warnings=0). |
pnpm format / pnpm format:check | Prettier write / check. |
pnpm typecheck | tsc -b --noEmit across the node and web configs. |
pnpm test | The fast core Vitest suite (test:core). |
pnpm test:all | Every Vitest config. |
pnpm rebrand | Rewrite brand name, slug, app id, scheme, and static config. |
pnpm supabase:deploy | Deploy the Supabase Edge Functions. |
pnpm tauri icon <src.png> | Regenerate app + tray icons. |
Linting here is Prettier + ESLint and the package manager is pnpm — not
Biome. There is no test:smoke script; end-to-end tests live in an isolated
WebdriverIO + tauri-driver harness under test/e2e/ with its own
package.json (see Packaging).
Full validation gate
The README quality gate before completing a change that touches app code, dependencies, Tauri config, commands/capabilities, persistence, or packaging:
pnpm format:check && pnpm lint:check && pnpm typecheck && pnpm test:unit \
&& cargo fmt --check --manifest-path src-tauri/Cargo.toml \
&& cargo clippy --manifest-path src-tauri/Cargo.toml -- -D warnings \
&& cargo test --manifest-path src-tauri/Cargo.tomlThe three cargo commands cover the Rust half; cargo test also regenerates
src/lib/bindings.ts, so binding drift fails the gate. pnpm tauri build --no-bundle is a full release compile (minutes) — run it at milestones, not per
step.
First-run failures
| Symptom | Likely cause | Fix |
|---|---|---|
Build fails before the window opens with a webkit2gtk/WebView2/linker error | Missing Rust or per-OS webview deps | Install the prerequisites for your OS (see the tabs above). |
pnpm dev seems stuck for minutes on first run | First Rust compile is slow | Wait — the initial crate compile is expected; later runs are incremental. |
| pnpm warns about the package manager | Local pnpm ≠ pnpm@11.1.3 | Run corepack enable then corepack prepare pnpm@11.1.3 --activate. |
Vite fails to bind port 1420 | Another dev session owns the port | Stop the other session; the port is fixed by devUrl in tauri.conf.json. |
| Linux: no tray icon | AppIndicator library missing | Install libayatana-appindicator3-dev and restart. |
| macOS: a keychain access prompt appears | Unsigned dev builds use the login keychain for secure storage | Expected — allow it; signed builds use the app identity normally. |