ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/bootcamp/desktop.mddeleted+0-741
Changes to docs/bootcamp/desktop.md
@@ -1,741 +0,0 @@
1# Build a Desktop App
2
3This tutorial will guide you through building desktop applications with Stacks. Using Tauri integration, you can package your web application as a native desktop app for Windows, macOS, and Linux.
4
5## Overview
6
7Stacks desktop apps are powered by Tauri, which provides:
8
9- **Small Bundle Size** - Native binaries, not Electron
10- **Cross-Platform** - Windows, macOS, and Linux from a single codebase
11- **Native Features** - System tray, file dialogs, notifications, and more
12- **Security** - Rust-powered backend with strict sandboxing
13- **Web Frontend** - Use your existing Stacks frontend
14
15## Prerequisites
16
17Before building desktop apps, install the Tauri CLI:
18
19```bash
20# Install Tauri CLI
21bun add -D @tauri-apps/cli
22
23# Verify installation
24bunx tauri --version
25```
26
27You will also need Rust installed for building the native binary:
28
29```bash
30# macOS/Linux
31curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
32
33# Windows (download installer from rustup.rs)
34```
35
36## Project Setup
37
38### Initialize Tauri
39
40Initialize Tauri in your Stacks project:
41
42```bash
43buddy desktop:init
44# Or manually
45bunx tauri init
46```
47
48This creates the following structure:
49
50```
51src-tauri/
52├── Cargo.toml # Rust dependencies
53├── build.rs # Build script
54├── icons/ # App icons
55├── src/
56│ └── main.rs # Rust entry point
57└── tauri.conf.json # Tauri configuration
58```
59
60### Configuration
61
62Configure your desktop app in `src-tauri/tauri.conf.json`:
63
64```json
65{
66 "build": {
67 "beforeBuildCommand": "buddy build",
68 "beforeDevCommand": "buddy dev",
69 "devPath": "http://localhost:3000",
70 "distDir": "../dist"
71 },
72 "package": {
73 "productName": "My App",
74 "version": "1.0.0"
75 },
76 "tauri": {
77 "bundle": {
78 "active": true,
79 "identifier": "com.example.myapp",
80 "icon": [
81 "icons/32x32.png",
82 "icons/128x128.png",
83 "icons/128x128@2x.png",
84 "icons/icon.icns",
85 "icons/icon.ico"
86 ],
87 "targets": "all",
88 "category": "Productivity",
89 "shortDescription": "My awesome desktop app",
90 "longDescription": "A longer description of my app and its features."
91 },
92 "security": {
93 "csp": null
94 },
95 "windows": [
96 {
97 "title": "My App",
98 "width": 1200,
99 "height": 800,
100 "minWidth": 800,
101 "minHeight": 600,
102 "resizable": true,
103 "fullscreen": false,
104 "center": true
105 }
106 ],
107 "allowlist": {
108 "all": false,
109 "shell": {
110 "open": true
111 },
112 "dialog": {
113 "all": true
114 },
115 "fs": {
116 "all": true,
117 "scope": ["$APP/*", "$DOCUMENT/*"]
118 },
119 "notification": {
120 "all": true
121 },
122 "clipboard": {
123 "all": true
124 }
125 }
126 }
127}
128```
129
130## Window Management
131
132### Opening Windows
133
134Create and manage windows programmatically:
135
136```typescript
137// resources/functions/desktop.ts
138import { WebviewWindow } from '@tauri-apps/api/window'
139
140// Create a new window
141export async function openSettingsWindow() {
142 const settingsWindow = new WebviewWindow('settings', {
143 url: '/settings',
144 title: 'Settings',
145 width: 600,
146 height: 400,
147 center: true,
148 resizable: false,
149 })
150
151 // Listen for window events
152 settingsWindow.once('tauri://created', () => {
153 console.log('Settings window created')
154 })
155
156 settingsWindow.once('tauri://error', (e) => {
157 console.error('Failed to create window:', e)
158 })
159}
160```
161
162### Window Controls
163
164Control the current window:
165
166```typescript
167import { appWindow } from '@tauri-apps/api/window'
168
169// Minimize
170await appWindow.minimize()
171
172// Maximize
173await appWindow.maximize()
174
175// Toggle fullscreen
176await appWindow.toggleMaximize()
177
178// Close
179await appWindow.close()
180
181// Hide
182await appWindow.hide()
183
184// Show
185await appWindow.show()
186
187// Set title
188await appWindow.setTitle('New Title')
189
190// Center window
191await appWindow.center()
192
193// Set size
194await appWindow.setSize({ width: 800, height: 600 })
195
196// Set position
197await appWindow.setPosition({ x: 100, y: 100 })
198
199// Set always on top
200await appWindow.setAlwaysOnTop(true)
201```
202
203### Custom Titlebar
204
205Create a custom titlebar for a frameless window:
206
207```typescript
208// tauri.conf.json
209{
210 "tauri": {
211 "windows": [{
212 "decorations": false, // Remove native titlebar
213 "transparent": true
214 }]
215 }
216}
217```
218
219```html
220<!-- resources/components/Titlebar.stx -->
221<script server>
222import { appWindow } from '@tauri-apps/api/window'
223
224async function minimize() {
225 await appWindow.minimize()
226}
227
228async function toggleMaximize() {
229 await appWindow.toggleMaximize()
230}
231
232async function close() {
233 await appWindow.close()
234}
235</script>
236
237<div
238 data-tauri-drag-region
239 class="flex items-center justify-between px-4 h-8 bg-gray-100 dark:bg-gray-800"
240>
241 <div class="font-medium text-sm">My App</div>
242
243 <div class="flex gap-2">
244 <button onclick="minimize()" class="p-1 hover:bg-gray-200 rounded">
245 <i class="h-4 w-4 i-hugeicons-outline-minus"></i>
246 </button>
247 <button onclick="toggleMaximize()" class="p-1 hover:bg-gray-200 rounded">
248 <i class="h-4 w-4 i-hugeicons-outline-square"></i>
249 </button>
250 <button onclick="close()" class="p-1 hover:text-white hover:bg-red-500 rounded">
251 <i class="h-4 w-4 i-hugeicons-outline-x"></i>
252 </button>
253 </div>
254</div>
255```
256
257## System Tray
258
259Add a system tray icon for background apps:
260
261### Configuration
262
263```json
264// tauri.conf.json
265{
266 "tauri": {
267 "systemTray": {
268 "iconPath": "icons/tray-icon.png",
269 "iconAsTemplate": true
270 },
271 "allowlist": {
272 "systemTray": {
273 "all": true
274 }
275 }
276 }
277}
278```
279
280### Rust Implementation
281
282```rust
283// src-tauri/src/main.rs
284use tauri::{
285 CustomMenuItem, Manager, SystemTray, SystemTrayEvent, SystemTrayMenu,
286 SystemTrayMenuItem,
287};
288
289fn main() {
290 let quit = CustomMenuItem::new("quit".to*string(), "Quit");
291 let hide = CustomMenuItem::new("hide".to*string(), "Hide");
292 let show = CustomMenuItem::new("show".to*string(), "Show");
293
294 let tray*menu = SystemTrayMenu::new()
295 .add*item(show)
296 .add*item(hide)
297 .add*native*item(SystemTrayMenuItem::Separator)
298 .add*item(quit);
299
300 let system*tray = SystemTray::new().with*menu(tray*menu);
301
302 tauri::Builder::default()
303 .system*tray(system*tray)
304 .on*system*tray*event(|app, event| match event {
305 SystemTrayEvent::LeftClick { .. } => {
306 let window = app.get*window("main").unwrap();
307 window.show().unwrap();
308 window.set*focus().unwrap();
309 }
310 SystemTrayEvent::MenuItemClick { id, .. } => match id.as*str() {
311 "quit" => {
312 std::process::exit(0);
313 }
314 "hide" => {
315 let window = app.get*window("main").unwrap();
316 window.hide().unwrap();
317 }
318 "show" => {
319 let window = app.get*window("main").unwrap();
320 window.show().unwrap();
321 }
322
323 * => {}
324
325 },
326
327 * => {}
328
329 })
330 .run(tauri::generate*context!())
331 .expect("error while running tauri application");
332}
333```
334
335## Native Features
336
337### File System Access
338
339Access the file system securely:
340
341```typescript
342import { open, save } from '@tauri-apps/api/dialog'
343import { readTextFile, writeTextFile, readDir } from '@tauri-apps/api/fs'
344
345// Open file dialog
346export async function openFile() {
347 const selected = await open({
348 multiple: false,
349 filters: [{
350 name: 'Text Files',
351 extensions: ['txt', 'md', 'json'],
352 }],
353 })
354
355 if (selected) {
356 const content = await readTextFile(selected as string)
357 return content
358 }
359}
360
361// Save file dialog
362export async function saveFile(content: string) {
363 const filePath = await save({
364 filters: [{
365 name: 'Text Files',
366 extensions: ['txt'],
367 }],
368 })
369
370 if (filePath) {
371 await writeTextFile(filePath, content)
372 }
373}
374
375// Read directory
376export async function listFiles(path: string) {
377 const entries = await readDir(path)
378 return entries
379}
380```
381
382### Notifications
383
384Show system notifications:
385
386```typescript
387import {
388 isPermissionGranted,
389 requestPermission,
390 sendNotification,
391} from '@tauri-apps/api/notification'
392
393export async function notify(title: string, body: string) {
394 let permissionGranted = await isPermissionGranted()
395
396 if (!permissionGranted) {
397 const permission = await requestPermission()
398 permissionGranted = permission === 'granted'
399 }
400
401 if (permissionGranted) {
402 sendNotification({ title, body })
403 }
404}
405```
406
407### Clipboard
408
409Access the system clipboard:
410
411```typescript
412import { writeText, readText } from '@tauri-apps/api/clipboard'
413
414// Copy to clipboard
415export async function copyToClipboard(text: string) {
416 await writeText(text)
417}
418
419// Read from clipboard
420export async function pasteFromClipboard() {
421 const text = await readText()
422 return text
423}
424```
425
426### Shell Commands
427
428Execute shell commands:
429
430```typescript
431import { Command } from '@tauri-apps/api/shell'
432
433// Run a command
434export async function runCommand(command: string, args: string[]) {
435 const cmd = new Command(command, args)
436
437 cmd.on('close', (data) => {
438 console.log(`Command finished with code ${data.code}`)
439 })
440
441 cmd.on('error', (error) => {
442 console.error(`Command error: ${error}`)
443 })
444
445 cmd.stdout.on('data', (line) => {
446 console.log(`stdout: ${line}`)
447 })
448
449 const child = await cmd.spawn()
450 return child
451}
452```
453
454### Global Shortcuts
455
456Register global keyboard shortcuts:
457
458```typescript
459import { register, unregister } from '@tauri-apps/api/globalShortcut'
460
461// Register a shortcut
462export async function registerShortcuts() {
463 await register('CommandOrControl+Shift+C', () => {
464 console.log('Shortcut triggered!')
465 // Show your app window
466 })
467}
468
469// Unregister
470export async function unregisterShortcuts() {
471 await unregister('CommandOrControl+Shift+C')
472}
473```
474
475## Communication Between Frontend and Backend
476
477### Invoke Rust Commands
478
479Call Rust functions from your frontend:
480
481```rust
482// src-tauri/src/main.rs
483# [tauri::command]
484fn greet(name: &str) -> String {
485 format!("Hello, {}!", name)
486}
487
488# [tauri::command]
489async fn read*file(path: String) -> Result<String, String> {
490 std::fs::read*to*string(path).map*err(|e| e.to*string())
491}
492
493fn main() {
494 tauri::Builder::default()
495 .invoke*handler(tauri::generate*handler![greet, read*file])
496 .run(tauri::generate*context!())
497 .expect("error while running tauri application");
498}
499```
500
501```typescript
502// Frontend
503import { invoke } from '@tauri-apps/api/tauri'
504
505// Call the Rust function
506const greeting = await invoke('greet', { name: 'World' })
507console.log(greeting) // "Hello, World!"
508
509// Call async Rust function
510try {
511 const content = await invoke('read*file', { path: '/path/to/file.txt' })
512 console.log(content)
513} catch (error) {
514 console.error('Failed to read file:', error)
515}
516```
517
518### Events
519
520Send events between frontend and backend:
521
522```rust
523// Emit event from Rust
524# [tauri::command]
525fn start*processing(window: tauri::Window) {
526 std::thread::spawn(move || {
527 for i in 0..100 {
528 window.emit("progress", i).unwrap();
529 std::thread::sleep(std::time::Duration::from*millis(50));
530 }
531 window.emit("complete", "Done!").unwrap();
532 });
533}
534```
535
536```typescript
537// Listen for events in frontend
538import { listen } from '@tauri-apps/api/event'
539
540const unlistenProgress = await listen('progress', (event) => {
541 console.log(`Progress: ${event.payload}%`)
542})
543
544const unlistenComplete = await listen('complete', (event) => {
545 console.log(`Completed: ${event.payload}`)
546 unlistenProgress()
547 unlistenComplete()
548})
549```
550
551## Development and Building
552
553### Development Mode
554
555Run the desktop app in development:
556
557```bash
558buddy desktop:dev
559# Or
560bunx tauri dev
561```
562
563This starts the Stacks dev server and opens the app in a native window.
564
565### Building for Production
566
567Build distributable binaries:
568
569```bash
570buddy desktop:build
571# Or
572bunx tauri build
573```
574
575Build outputs are placed in `src-tauri/target/release/bundle/`:
576
577- **macOS**: `.app` bundle and `.dmg` installer
578- **Windows**: `.exe` and `.msi` installer
579- **Linux**: `.deb`, `.AppImage`, and `.rpm`
580
581### Platform-Specific Builds
582
583Build for specific platforms:
584
585```bash
586# macOS
587bunx tauri build --target universal-apple-darwin
588
589# Windows (from macOS/Linux requires cross-compilation setup)
590bunx tauri build --target x86*64-pc-windows-msvc
591
592# Linux
593bunx tauri build --target x86*64-unknown-linux-gnu
594```
595
596## Auto-Updates
597
598Enable automatic updates for your desktop app:
599
600### Configuration
601
602```json
603// tauri.conf.json
604{
605 "tauri": {
606 "updater": {
607 "active": true,
608 "endpoints": [
609 "https://releases.example.com/{⁠{target}}/{⁠{current*version}}"
610 ],
611 "dialog": true,
612 "pubkey": "YOUR*PUBLIC*KEY"
613 }
614 }
615}
616```
617
618### Check for Updates
619
620```typescript
621import { checkUpdate, installUpdate } from '@tauri-apps/api/updater'
622import { relaunch } from '@tauri-apps/api/process'
623
624export async function checkForUpdates() {
625 try {
626 const { shouldUpdate, manifest } = await checkUpdate()
627
628 if (shouldUpdate) {
629 console.log(`Update available: ${manifest?.version}`)
630
631 // Install the update
632 await installUpdate()
633
634 // Restart the app
635 await relaunch()
636 }
637 } catch (error) {
638 console.error('Update check failed:', error)
639 }
640}
641```
642
643## Complete Example: Note-Taking App
644
645Here is a complete example combining multiple features:
646
647```html
648<!-- resources/views/notes.stx -->
649<script server>
650import { ref } from '@stacksjs/reactivity'
651import { open, save } from '@tauri-apps/api/dialog'
652import { readTextFile, writeTextFile } from '@tauri-apps/api/fs'
653import { sendNotification } from '@tauri-apps/api/notification'
654
655const content = ref('')
656const currentFile = ref('')
657const isDirty = ref(false)
658
659async function openNote() {
660 const selected = await open({
661 filters: [{ name: 'Markdown', extensions: ['md'] }],
662 })
663
664 if (selected) {
665 content.value = await readTextFile(selected as string)
666 currentFile.value = selected as string
667 isDirty.value = false
668 }
669}
670
671async function saveNote() {
672 let path = currentFile.value
673
674 if (!path) {
675 path = await save({
676 filters: [{ name: 'Markdown', extensions: ['md'] }],
677 }) as string
678 }
679
680 if (path) {
681 await writeTextFile(path, content.value)
682 currentFile.value = path
683 isDirty.value = false
684 sendNotification({ title: 'Saved', body: 'Note saved successfully!' })
685 }
686}
687
688function handleInput(e: Event) {
689 content.value = (e.target as HTMLTextAreaElement).value
690 isDirty.value = true
691}
692</script>
693
694<div class="flex flex-col h-screen">
695 <!-- Toolbar -->
696 <div class="flex gap-4 items-center px-4 h-12 bg-gray-100 dark:bg-gray-800 border-b">
697 <button
698 onclick="openNote()"
699 class="px-3 py-1 text-white bg-blue-500 hover:bg-blue-600 rounded"
700 >
701 Open
702 </button>
703 <button
704 onclick="saveNote()"
705 class="px-3 py-1 text-white bg-green-500 hover:bg-green-600 rounded"
706 >
707 Save
708 </button>
709
710 @if(currentFile.value)
711 <span class="text-gray-600 text-sm">
712 {{ currentFile.value }}
713 @if(isDirty.value)
714 <span class="text-orange-500">*</span>
715 @endif
716 </span>
717 @endif
718 </div>
719
720 <!-- Editor -->
721 <textarea
722 value="{⁠{ content.value }}"
723 oninput="handleInput(event)"
724 class="flex-1 p-4 font-mono text-sm dark:text-white dark:bg-gray-900 focus:outline-none resize-none"
725 placeholder="Start writing..."
726 ></textarea>
727</div>
728```
729
730## Next Steps
731
732Now that you know how to build desktop apps, continue to:
733
734- [Authentication How-To](/bootcamp/how-to/authentication) - Add user authentication
735- [Testing How-To](/bootcamp/how-to/testing) - Test your desktop app
736- [Deployment How-To](/bootcamp/how-to/deploy) - Distribute your app
737
738## Related Documentation
739
740- [Tauri Documentation](https://tauri.app/v1/guides/)
741- [Tauri API Reference](https://tauri.app/v1/api/js/)