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)

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

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

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

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:

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

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

Installer Formats

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