curiositech/cross-platform-desktop

Cross-Platform Desktop Development

Build desktop applications that ship on macOS AND Windows. This skill covers the platform differences that break your app, the abstraction strategies that save your sanity, and the CI/CD discipline that catches problems before users do.

When to Use / Do NOT Use For

Use for: Desktop apps targeting macOS + Windows, framework evaluation (Tauri vs Electron vs Flutter), platform-convention-aware UI design, multi-platform CI/CD, debugging cross-platform rendering/behavior.

Do NOT use for: Web-only apps | Mobile apps | Single-platform native (SwiftUI/WinUI) | Linux-only desktop

Framework Decision Matrix (2025-2026)

| Factor | Tauri v2 | Electron | Flutter Desktop | |--------|----------|----------|-----------------| | Bundle size | 2-10 MB | 80-150 MB | 15-30 MB | | Idle memory | 30-40 MB | 150-300 MB | 60-100 MB | | Rendering | Native webview (varies per OS) | Bundled Chromium (identical) | Skia engine (identical) | | Backend | Rust | Node.js | Dart | | Plugin ecosystem | Growing (50+ official) | Mature (thousands) | Moderate | | Security model | Deny-by-default | Open by default | Sandboxed | | Cross-platform rendering | WebKit (macOS) vs Chromium (Windows) | Chromium everywhere | Skia everywhere | | Best for | Performance, security, small bundle | Web teams, pixel-perfect parity | Custom UI, animation |

Choose Tauri when performance and security matter and you accept rendering differences. Choose Electron when pixel-identical rendering across platforms is non-negotiable. Choose Flutter when you also target mobile and want one widget toolkit everywhere.

Platform Differences That Break Apps

File Paths

| Concern | macOS | Windows | |---------|-------|---------| | Separator | / | \ (but / works in most APIs) | | App data | ~/Library/Application Support/com.app.id/ | %APPDATA%\AppName\ | | Temp dir | $TMPDIR | %TEMP% | | Home dir | $HOME (~) | %USERPROFILE% | | Case sensitivity | No by default (APFS) | No (NTFS) | | Max path length | 1024 chars | 260 chars default, 32767 with opt-in | | Reserved names | None | CON, PRN, AUX, NUL, COM1-9, LPT1-9 |

Never hardcode paths. Use platform APIs:

// Rust: dirs crate
let config = dirs::config_dir().unwrap();
// macOS: ~/Library/Application Support
// Windows: C:\Users\<user>\AppData\Roaming

let data = dirs::data_dir().unwrap();
let cache = dirs::cache_dir().unwrap();

// Tauri JS API
import { appDataDir, homeDir, tempDir } from "@tauri-apps/api/path";

const dataDir = await appDataDir(); // Platform-correct automatically

Keyboard Shortcuts

| Action | macOS | Windows/Linux | |--------|-------|---------------| | Copy | Cmd+C | Ctrl+C | | Paste | Cmd+V | Ctrl+V | | Undo | Cmd+Z | Ctrl+Z | | Redo | Cmd+Shift+Z | Ctrl+Y | | Preferences | Cmd+, | Ctrl+, (or Edit > Preferences) | | Quit app | Cmd+Q | Alt+F4 | | Close window | Cmd+W | Ctrl+W or Alt+F4 | | Find | Cmd+F | Ctrl+F | | Save | Cmd+S | Ctrl+S |

Abstraction pattern:

const isMac = navigator.platform.includes("Mac");

function formatShortcut(key: string): string {
  const mod = isMac ? "\u2318" : "Ctrl+";
  return `${mod}${key.toUpperCase()}`;
}

function isModKey(e: KeyboardEvent): boolean {
  return isMac ? e.metaKey : e.ctrlKey;
}

// Usage
document.addEventListener("keydown", (e) => {
  if (isModKey(e) && e.key === "s") {
    e.preventDefault();
    saveDocument();
  }
});

Window Chrome and Menus

| Element | macOS | Windows | |---------|-------|---------| | Menu bar location | Top of screen (global) | Top of window | | Window controls | Top-left (close/minimize/zoom) | Top-right (minimize/maximize/close) | | System tray | Menu bar area (top-right) | Notification area (bottom-right) | | Close last window | App keeps running | App quits | | Quit app | Cmd+Q or menu | Closing last window or Alt+F4 | | Native dialogs | Sheet (slides from title bar) | Modal (centered on window) | | Dark mode | NSAppearance / system | prefers-color-scheme + registry | | Default font | SF Pro (system) | Segoe UI (system) |

The close-vs-quit behavior is the most common cross-platform bug. Handle it explicitly:

// Tauri: platform-correct close behavior
app.on_window_event(|window, event| {
    if let tauri::WindowEvent::CloseRequested { api, .. } = event {
        #[cfg(target_os = "macos")]
        {
            // macOS convention: hide, do not quit
            window.hide().unwrap();
            api.prevent_close();
        }
        // Windows: default close-and-quit is correct
    }
});

Rendering Differences (Tauri-Specific)

Tauri uses native webviews per platform. This causes subtle differences:

| Issue | macOS (WebKit) | Windows (WebView2/Chromium) | |-------|----------------|------------------------------| | Font rendering | Sub-pixel antialiasing | ClearType / grayscale | | Default system font | SF Pro | Segoe UI | | Emoji rendering | Apple Color Emoji | Segoe UI Emoji | | Scrollbar styling | WebKit-specific | Chromium-specific | | CSS container queries | Check WebKit version | Generally supported | | Date/time input | Native WebKit picker | Chromium picker |

Electron avoids these entirely by bundling Chromium on all platforms. If rendering parity is critical, this is the strongest argument for Electron.

Mitigation for Tauri:

/* Cross-platform font stack */
body {
  font-family:
    -apple-system,        /* macOS SF Pro */
    BlinkMacSystemFont,   /* macOS Chrome fallback */
    "Segoe UI",           /* Windows */
    Roboto,               /* Android/Linux */
    system-ui,
    sans-serif;
}

/* Normalize scrollbars */
::-webkit-scrollbar {
  width: 8px;
}
::-webkit-scrollbar-thumb {
  background-color: rgba(0, 0, 0, 0.3);
  border-radius: 4px;
}

DPI and Display Scaling

| Factor | macOS | Windows | |--------|-------|---------| | Default scale | 2x (Retina) | 1x, 1.25x, 1.5x, 2x (user configurable) | | Scaling method | Integer (2x only on most displays) | Fractional (125%, 150%) | | Common gotcha | None (2x is standard) | 125% scaling causes blurry rendering |

Fix: Use CSS logical units, SVG icons (not bitmaps), and test at 100%, 125%, and 150% scaling on Windows.

Installer Formats

| Format | Platform | Tool | Use Case | |--------|----------|------|----------| | DMG | macOS | create-dmg, Tauri bundler | Standard drag-to-Applications | | .app bundle | macOS | cargo tauri build | The application itself | | MSI | Windows | WiX (via Tauri) | Enterprise, Group Policy | | NSIS EXE | Windows | NSIS (via Tauri) | Consumer apps, custom UI | | AppImage | Linux | Tauri bundler | Universal portable binary | | .deb | Linux | Tauri bundler | Debian/Ubuntu |

Tauri config for all formats:

{
  "bundle": {
    "targets": ["dmg", "nsis", "msi", "deb", "appimage"],
    "macOS": {
      "minimumSystemVersion": "10.15",
      "dmg": {
        "appPosition": { "x": 180, "y": 170 },
        "applicationFolderPosition": { "x": 480, "y": 170 }
      }
    },
    "windows": {
      "nsis": {
        "installMode": "both",
        "displayLanguageSelector": true
      },
      "wix": {
        "language": "en-US"
      }
    }
  }
}

CI/CD: GitHub Actions Matrix Build

Use a matrix strategy to build on native runners for each platform. The full pipeline YAML is in rust-app-distribution -- the key pattern:

strategy:
  fail-fast: false
  matrix:
    include:
      - platform: macos-latest     # ARM Mac (M-series)
        target: aarch64-apple-darwin
      - platform: macos-13         # Intel Mac
        target: x86_64-apple-darwin
      - platform: windows-latest
        target: x86_64-pc-windows-msvc
runs-on: ${{ matrix.platform }}

macOS universal binary (ARM + Intel in one): use target universal-apple-darwin with rustup target add aarch64-apple-darwin x86_64-apple-darwin.

Platform-Specific Code Patterns

Rust: cfg(target_os) Guards

#[cfg(target_os = "macos")]
fn platform_init(app: &tauri::App) {
    // macOS-specific: dock icon, activation policy
    app.set_activation_policy(tauri::ActivationPolicy::Regular);
}

#[cfg(target_os = "windows")]
fn platform_init(app: &tauri::App) {
    // Windows-specific: jump list, toast notification setup
}

// Always provide a fallback
#[cfg(not(any(target_os = "macos", target_os = "windows")))]
fn platform_init(_app: &tauri::App) {}

TypeScript: Runtime Platform Detection

import { platform } from "@tauri-apps/plugin-os";

const os = await platform(); // "macos" | "windows" | "linux"

// Conditional UI
function ShortcutHint({ action }: { action: string }) {
  const mod = os === "macos" ? "\u2318" : "Ctrl";
  return <kbd>{mod}+{action}</kbd>;
}

CSS: Platform-Aware Styling

/* Tauri injects data-platform attribute (configure in setup) */
[data-platform="macos"] .titlebar {
  padding-left: 80px; /* Space for traffic lights */
}

[data-platform="windows"] .titlebar {
  padding-right: 140px; /* Space for min/max/close */
}

Testing Across Platforms

Local Development

• Primary dev machine: Build and test natively
• Secondary platform: VM (Parallels/VMware for Windows on Mac, or vice versa), or dedicated hardware
• Quick check: CI runners catch build failures even without local testing

Automated Testing in CI

# Run tests on both platforms in CI
test:
  strategy:
    matrix:
      os: [macos-latest, windows-latest]
  runs-on: ${{ matrix.os }}
  steps:
    - uses: actions/checkout@v4
    - run: cargo test --manifest-path src-tauri/Cargo.toml
    - run: npm ci && npm test

Screenshot Comparison

Use headless browser testing (Playwright) in CI to screenshot the app on each platform and diff the results. Catches rendering regressions across WebKit/WebView2.

Anti-Patterns

1. Hardcoded Paths

Symptom: fs.readFile("/Users/...") or fs.readFile("C:\\Users\\...") Fix: Use dirs crate (Rust) or @tauri-apps/api/path (JS). Never assume separators.

2. Testing on One Platform Only

Symptom: "Works on my Mac" ships broken on Windows. Fix: CI matrix builds on both platforms. Period.

3. Ignoring Close-vs-Quit Semantics

Symptom: macOS users expect app to stay running when closing window. Windows users expect it to quit. Fix: Follow each platform's convention explicitly.

4. Platform-Specific Fonts Without Fallbacks

Symptom: "SF Pro" renders as Times New Roman on Windows. Fix: Full font stack: -apple-system, "Segoe UI", Roboto, sans-serif.

5. Pixel-Based Layouts That Break at Fractional Scaling

Symptom: UI looks fine on macOS Retina, misaligned at 125%/150% on Windows. Fix: Use logical CSS units, SVG icons, test at multiple DPI settings.

6. Assuming WebKit Behavior on Windows

Symptom: CSS or JS works on macOS (WebKit) but breaks on Windows (Chromium). Fix: Test both. Use feature detection. Check compat tables.

7. One Giant Installer for All Platforms

Symptom: Trying to create a universal artifact. Fix: Each platform gets its own format: DMG (macOS), NSIS/MSI (Windows).

8. Not Handling Windows Long Path Limits

Symptom: File operations fail on deeply nested directories. Fix: Check path length, or use \\?\ extended-length prefix on Windows.

Quality Checklist

[ ] App builds and runs on both macOS and Windows
[ ] CI/CD matrix builds both platforms on every push
[ ] Keyboard shortcuts use Cmd on macOS, Ctrl on Windows
[ ] Shortcut hints in UI reflect current platform dynamically
[ ] Close button follows platform convention (hide on macOS, quit on Windows)
[ ] Menu bar is global on macOS, in-window on Windows
[ ] System tray works on both platforms
[ ] File paths resolved via platform APIs (never hardcoded)
[ ] Font stack includes fallbacks for both platforms
[ ] Dark mode detected and applied on both platforms
[ ] Tested at 1x, 1.25x, 1.5x, and 2x display scaling
[ ] Installers generated: DMG for macOS, NSIS or MSI for Windows
[ ] Code signing configured for both platforms (see rust-app-distribution)
[ ] No platform-specific CSS without feature detection
[ ] Window state (size, position) persisted correctly per platform