|
| 1 | +# Tauri Vue3 App - AI Coding Agent Instructions |
| 2 | + |
| 3 | +## Project Architecture |
| 4 | + |
| 5 | +**Tauri v2 desktop app** with Vue 3 frontend + Rust backend for building cross-platform desktop applications. |
| 6 | + |
| 7 | +The baseline for this project's technical stack and directory structure is [tauri-vuetify-starter](https://github.com/logue/tauri-vuetify-starter). When documenting or implementing architecture-level changes, prioritize consistency with that reference. |
| 8 | + |
| 9 | +### Key Components |
| 10 | + |
| 11 | +- **Frontend**: Vue 3 + TypeScript + Vuetify + Pinia (located in `frontend/src/`) |
| 12 | +- **Backend**: Rust with Tauri v2 (located in `backend/src/`) |
| 13 | +- **Workspace**: pnpm monorepo |
| 14 | + |
| 15 | +### Rust Backend Structure |
| 16 | + |
| 17 | +``` |
| 18 | +backend/src/ |
| 19 | +├── lib.rs # Public API exports (error, logging) |
| 20 | +├── main.rs # Tauri app entry point with plugin initialization |
| 21 | +├── command.rs # Tauri commands (sample commands for demonstration) |
| 22 | +├── error.rs # AppError type with common error variants |
| 23 | +└── logging.rs # Logging system with ResultExt trait |
| 24 | +``` |
| 25 | + |
| 26 | +### Frontend Structure |
| 27 | + |
| 28 | +``` |
| 29 | +frontend/src/ |
| 30 | +├── components/ |
| 31 | +│ └── MainContent.vue # Main application component |
| 32 | +├── composables/ |
| 33 | +│ ├── useFileSystem.ts # File operations (open/save dialogs) |
| 34 | +│ ├── useLogger.ts # Frontend logging |
| 35 | +│ └── useNotification.ts # System notifications |
| 36 | +├── store/ |
| 37 | +│ ├── ConfigStore.ts # Theme, locale |
| 38 | +│ └── GlobalStore.ts # Loading, progress, messages |
| 39 | +├── locales/ # i18n translation files (6 languages) |
| 40 | +└── plugins/ |
| 41 | + ├── i18n.ts # Vue I18n configuration |
| 42 | + └── vuetify.ts # Material Design components |
| 43 | +``` |
| 44 | + |
| 45 | +## Critical Workflows |
| 46 | + |
| 47 | +### Development |
| 48 | + |
| 49 | +```bash |
| 50 | +# Install dependencies (first time) |
| 51 | +pnpm install |
| 52 | + |
| 53 | +# Run Tauri dev server (hot reload for both frontend and Rust) |
| 54 | +pnpm run dev:tauri |
| 55 | + |
| 56 | +# Run only frontend |
| 57 | +pnpm run dev |
| 58 | + |
| 59 | +# Type checking |
| 60 | +pnpm run type-check |
| 61 | + |
| 62 | +# Lint all |
| 63 | +pnpm run lint |
| 64 | +pnpm run lint:style |
| 65 | +``` |
| 66 | + |
| 67 | +### Building |
| 68 | + |
| 69 | +```bash |
| 70 | +# Build Tauri app for current platform |
| 71 | +pnpm run build:tauri |
| 72 | + |
| 73 | +# macOS build (Universal binary for both Apple Silicon and Intel) |
| 74 | +pnpm --filter frontend build:tauri:mac |
| 75 | + |
| 76 | +# Linux via Docker |
| 77 | +./scripts/docker/docker-build.sh x64 # or arm64 |
| 78 | + |
| 79 | +# Package managers |
| 80 | +pnpm run package:chocolatey # Windows |
| 81 | +pnpm run package:homebrew # macOS |
| 82 | +``` |
| 83 | + |
| 84 | +### Testing Rust code |
| 85 | + |
| 86 | +```bash |
| 87 | +cd backend |
| 88 | +cargo test |
| 89 | +cargo build --release |
| 90 | +``` |
| 91 | + |
| 92 | +## Project-Specific Conventions |
| 93 | + |
| 94 | +### Rust Code Patterns |
| 95 | + |
| 96 | +1. **Tauri Commands**: Async functions with `#[tauri::command]` attribute: |
| 97 | + |
| 98 | + ```rust |
| 99 | + #[tauri::command] |
| 100 | + async fn my_command(app: AppHandle, param: String) -> Result<String, String> { |
| 101 | + // Implementation |
| 102 | + Ok(result) |
| 103 | + } |
| 104 | + ``` |
| 105 | + |
| 106 | + Register commands in `main.rs`: |
| 107 | + |
| 108 | + ```rust |
| 109 | + tauri::Builder::default() |
| 110 | + .invoke_handler(tauri::generate_handler![my_command]) |
| 111 | + .run(tauri::generate_context!()) |
| 112 | + ``` |
| 113 | + |
| 114 | +2. **Error Handling**: Use `ResultExt` trait from `logging.rs` to auto-log errors: |
| 115 | + |
| 116 | + ```rust |
| 117 | + some_operation() |
| 118 | + .log_error(Some("Operation name")) |
| 119 | + .map_err(|e| format!("Failed: {}", e))? |
| 120 | + ``` |
| 121 | + |
| 122 | +3. **Module Exports**: `lib.rs` re-exports public API. Keep modules private, expose only what's needed. |
| 123 | + |
| 124 | +### Frontend Patterns |
| 125 | + |
| 126 | +1. **Composables Architecture**: Each concern is isolated (file operations, logging, notifications). Reusable logic as Vue composables. |
| 127 | + |
| 128 | +2. **State Management**: |
| 129 | + - `ConfigStore`: Theme and locale (persisted to localStorage via pinia-plugin-persistedstate) |
| 130 | + - `GlobalStore`: Transient UI state (loading, progress, messages) |
| 131 | + |
| 132 | +3. **Tauri Commands**: Call via `@tauri-apps/api/core`: |
| 133 | + |
| 134 | + ```typescript |
| 135 | + import { invoke } from "@tauri-apps/api/core"; |
| 136 | + const result = await invoke<string>("my_command", { param: "value" }); |
| 137 | + ``` |
| 138 | + |
| 139 | +4. **Tauri Events**: Listen for events from Rust backend: |
| 140 | + |
| 141 | + ```typescript |
| 142 | + import { listen } from "@tauri-apps/api/event"; |
| 143 | + await listen("my-event", (event) => { |
| 144 | + console.log("Received:", event.payload); |
| 145 | + }); |
| 146 | + ``` |
| 147 | + |
| 148 | +5. **i18n**: Use `vue-i18n` composable in components. Translation files are in `src/locales/*.yaml` (6 languages: en, ja, fr, ko, zhHans, zhHant). |
| 149 | + |
| 150 | +### Build Configuration |
| 151 | + |
| 152 | +1. **macOS Compatibility**: Uses `edition = "2024"`, `lto = "thin"`, `codegen-units = 16` for cross-Apple Silicon compatibility. |
| 153 | + |
| 154 | +2. **Cargo Profile**: Release profile optimizes for speed (`opt-level = 3`) with thin LTO for compatibility. |
| 155 | + |
| 156 | +3. **Vite Config**: Uses path aliases `@/` for `src/`, file-based routing, and Vuetify auto-import. |
| 157 | + |
| 158 | +4. **Environment Variables**: All application metadata is configured via `.env` file (version, app name, author, URLs, etc.). |
| 159 | + |
| 160 | +## Integration Points |
| 161 | + |
| 162 | +### Tauri ↔ Frontend Communication |
| 163 | + |
| 164 | +- **Commands** (`command.rs`): Sample commands: `echo_message()`, `get_app_version()`, `process_data()` |
| 165 | +- **Plugins**: dialog, fs, notification, opener, os (via `@tauri-apps/plugin-*`) |
| 166 | + |
| 167 | +### Platform-Specific Code |
| 168 | + |
| 169 | +- **Windows**: Uses native APIs in `target.'cfg(windows)'.dependencies` for Windows-specific optimizations. |
| 170 | +- **Linux**: Built via Docker with Debian Bookworm + WebKit2GTK. |
| 171 | +- **macOS**: Supports Universal binaries (Apple Silicon + Intel). |
| 172 | + |
| 173 | +## Key Files |
| 174 | + |
| 175 | +- [backend/src/command.rs](backend/src/command.rs) - Tauri command implementations (add your commands here) |
| 176 | +- [backend/src/main.rs](backend/src/main.rs) - Application entry point |
| 177 | +- [frontend/src/components/MainContent.vue](frontend/src/components/MainContent.vue) - Main UI component |
| 178 | +- [backend/Cargo.toml](backend/Cargo.toml) - Rust dependencies and build config |
| 179 | +- [.env](.env) - Application configuration (version, name, author, URLs) |
| 180 | + |
| 181 | +## Common Tasks |
| 182 | + |
| 183 | +- **Add new Tauri command**: Add function to `backend/src/command.rs`, register in `main.rs` |
| 184 | +- **Add UI string**: Edit `frontend/src/locales/*.yaml` for all languages (en, ja, fr, ko, zhHans, zhHant) |
| 185 | +- **Add composable**: Create new file in `frontend/src/composables/` following existing patterns |
| 186 | +- **Update configuration**: Edit `.env` file with your app name, version, URLs, etc. |
| 187 | +- **Platform-specific code**: Use `#[cfg(target_os = "macos")]` or `cfg(windows)` in Rust |
| 188 | + |
| 189 | +## Important Notes |
| 190 | + |
| 191 | +- **pnpm workspace**: Always use `pnpm --filter frontend <command>` for app-specific operations |
| 192 | +- **Rust edition**: Uses edition 2024 for modern Rust features |
| 193 | +- **Version management**: Version is in root `.env` file, synced to `Cargo.toml`, `package.json`, and `tauri.conf.json` |
| 194 | +- **Package managers**: Build scripts generate `.nuspec` (Chocolatey) and `.rb` (Homebrew) files dynamically from `.env` configuration |
| 195 | +- **Template system**: All app-specific values are in `.env` - edit this file when creating a new project from this template |
0 commit comments