Files
Heimgeist/docs/tauri-migration.md

61 lines
4.5 KiB
Markdown
Raw Normal View History

# Tauri Migration Spike
This spike adds an isolated Tauri v2 scaffold while keeping the Electron app as the supported desktop shell.
References checked during the spike:
- Tauri Vite setup: https://v2.tauri.app/start/frontend/vite/
- Tauri JavaScript API: https://v2.tauri.app/reference/javascript/api/
- Tauri CLI: https://v2.tauri.app/reference/cli/
## Current Electron Responsibilities
| Area | Current Electron implementation | Tauri target |
| --- | --- | --- |
| Main app window | `BrowserWindow` in `electron/main.cjs`, loading Vite in dev and `dist/index.html` in production | `src-tauri/tauri.conf.json` window loading the same Vite dev URL or `../dist` |
| Settings window | Separate modal `BrowserWindow` routed to `#/settings` | Later phase: either a second Tauri webview window or in-app settings route |
| Settings persistence | JSON file under Electron `app.getPath('userData')`, with migrations and normalization | Later phase: Tauri command backed by app config/data dir with the same setting keys and migrations |
| Renderer bridge | `electron/preload.cjs` exposes `window.electronAPI`; renderer uses `src/desktop/desktopApi.js` | `desktopApi` can call Tauri commands through `window.__TAURI__.core.invoke` when running in Tauri |
| File picker | `dialog.showOpenDialog` via `pick-paths` IPC | Later phase: official Tauri dialog plugin with scoped permissions |
| Open file/path | `shell.openPath` via `open-path` IPC | Later phase: official Tauri opener plugin or a scoped Rust command |
| External links | `shell.openExternal` and `setWindowOpenHandler` | Later phase: official Tauri opener plugin and window navigation policy |
| Window focus events | Electron `focus` event forwarded to renderer | Later phase: Tauri window event listener or emitted command event |
| App menu | Electron `Menu.buildFromTemplate` | Later phase: Tauri menu API |
| UI scale | Electron `webContents.setZoomFactor` | Later phase: Tauri/webview equivalent or renderer CSS scale strategy |
| DevTools preference | Electron opens/closes DevTools in dev | Later phase: Tauri devtools behavior and persisted preference |
| Updates/changelog | Git-based update check, pull, restart, and local changelog | Later phase: replace with Tauri updater or another signed update flow |
| Backend lifecycle | External Node scripts start FastAPI in dev | Not part of this spike; later sidecar/package design |
| Packaging | Electron starts from `main` and existing npm scripts | Later phase: Tauri bundle config, icons, signing, backend sidecar |
## Scaffold Added
- `src-tauri/tauri.conf.json` points Tauri at the existing Vite renderer on `http://127.0.0.1:5173` and the existing `dist` build output.
- `src-tauri/src/main.rs` registers placeholder Tauri commands that match the current `desktopApi` surface.
- `src-tauri/capabilities/default.json` grants the main window the default core capability for this spike.
- `src-tauri/icons/icon.png` is a placeholder icon required by Tauri context generation.
- `src/desktop/desktopApi.js` still prefers Electron. When Electron is absent and Tauri is present, it invokes matching Tauri commands. Without either desktop bridge, it falls back to safe defaults so the renderer can mount.
## Running The Spike
- Normal Electron development remains `npm run dev`.
- After installing npm dependencies, Tauri development is `npm run dev:tauri`.
- The Tauri config starts only the Vite renderer; start the FastAPI backend separately when testing chat flows.
- If Vite is already running on `127.0.0.1:5173`, reuse it with `npm run tauri -- dev --config '{"build":{"beforeDevCommand":""}}'`.
## Intentional Non-Goals
- No Electron files, scripts, or IPC behavior were removed.
- No Python backend sidecar, packaging, or lifecycle work was added.
- No Tauri updater, opener, dialog, menu, or settings persistence parity was implemented.
- The Tauri settings command is in-memory only and exists to let the renderer hydrate during the spike.
## Remaining Parity Gaps
- Settings: persistent storage, migrations, normalization, UI scale side effects, DevTools preference side effects.
- File picker: native picker and path filters.
- Open path and external links: scoped native opener behavior.
- Window focus events: renderer notification equivalent.
- Update flow: startup/manual checks, changelog, restart, and signed release strategy.
- Backend lifecycle: FastAPI startup, health gating, ffmpeg/ffprobe environment, shutdown, and sidecar packaging.
- Packaging: bundle metadata, icons, signing/notarization, auto-update channel, and platform install behavior.