Turbo Desktop

The Problem

Rails developers already have Hotwire Native (turbo-ios and turbo-android) to wrap their web apps in native mobile shells. But there has been nothing for desktop.

If you want to ship a macOS, Windows, or Linux app that talks to your existing Rails backend, you have been forced to either build a full Electron app from scratch or cobble together a custom WebView wrapper with no conventions.

Turbo Desktop fills this gap. It gives you a thin, native desktop shell powered by Tauri 2 that treats your Rails app as the single source of truth — the same pattern you already know from Hotwire Native, but for the desktop.

Architecture

Three layers that mirror the Hotwire Native pattern:

How It Works

// main.rs — startup
let app_config = window::load_config(None);
let url: url::Url = server_url.parse().expect("Invalid server URL");
main_window.eval(&format!("window.location.replace('{}')", url));

// main.rs — injection
.on_page_load(|webview, payload| {
    if let PageLoadEvent::Finished = payload.event() {
        let js = include_str!("../../src/turbo-desktop.js");
        let _ = webview.eval(js);
    }
})

// turbo-desktop.js
document.addEventListener("turbo:before-visit", async (event) => {
  const url = event.detail.url;
  const response = await TurboDesktop.proposeVisit(url, "advance");

  // If the native shell handled it, cancel the Turbo visit
  if (response.action === "none") {
    event.preventDefault();
  }
});

// navigation.rs
match properties.presentation {
    Presentation::Default  => /* navigate in current window */,
    Presentation::Modal    => /* open a new modal window */,
    Presentation::NewWindow => /* open a separate window */,
    Presentation::Replace  => /* replace, no back navigation */,
    Presentation::Native   => /* emit event for native screen */,
    Presentation::None     => /* do nothing (bridge handles it) */,
}

Path Configuration

The path configuration is a JSON file that maps URL patterns to presentation rules. This is the same concept from turbo-ios and turbo-android — the native shell consults it for every navigation to decide how to display each page.

{
  "settings": {
    "screenshots_enabled": true,
    "pull_to_refresh_enabled": false
  },
  "rules": [
    {
      "patterns": ["/"],
      "properties": { "presentation": "default" }
    },
    {
      "patterns": ["/new$", "/edit$"],
      "properties": {
        "presentation": "modal",
        "title": "Edit"
      }
    },
    {
      "patterns": ["/reports/"],
      "properties": { "presentation": "new_window" }
    },
    {
      "patterns": ["/settings"],
      "properties": { "presentation": "native" }
    }
  ]
}

Presentation Types

Rule Matching

Patterns are regular expressions matched against the URL path. Rules are evaluated in order and the last match wins — identical to Hotwire Native. This lets you set broad defaults early and add specific overrides later.

Bridge Components

The Bridge is the desktop equivalent of Strada. It lets your web components talk to native OS features through structured message passing.

The Flow

1. A Stimulus controller on the web page extends BridgeComponent
2. It calls this.send("connect", { title: "Export" })
3. turbo-desktop.js forwards this to Rust via Tauri's invoke
4. Rust handles it (e.g., registers a native menu item)
5. When the native side triggers (e.g., menu clicked), it emits a response back
6. The web component receives it via onReceive(message)

Built-in Components

Unknown component names are automatically forwarded as bridge-message events, making the system fully extensible without modifying Rust code.

JavaScript: Stimulus Bridge

import { Controller } from "@hotwired/stimulus"

export default class extends TurboDesktop.stimulusBridge(Controller, "notification") {
  connect() {
    super.connect()
    this.sendBridge("connect", { title: "My App" })
  }

  notify(event) {
    this.sendBridge("connect", {
      title: "New Message",
      body:  event.target.dataset.body
    })
  }

  receiveBridge(message) {
    console.log("Native says:", message)
  }
}

Rust: Handling Bridge Messages

#[tauri::command]
pub async fn handle_bridge_message(
    app: tauri::AppHandle,
    message: BridgeMessage,
) -> Result<serde_json::Value, String> {
    match message.component.as_str() {
        "notification" => handle_notification(&app, &message).await,
        "menu-item"   => handle_menu_item(&app, &message).await,
        "file-picker" => handle_file_picker(&app, &message).await,
        "badge"       => handle_badge(&app, &message).await,
        "shortcut"    => handle_shortcut(&app, &message).await,
        _ => {
            // Forward unknown components as events
            app.emit("bridge-message", &message)?;
            Ok(serde_json::json!({ "status": "forwarded" }))
        }
    }
}

Rails: View Helpers

<%# Attach bridge data attributes to any element %>
<%= tag.button "Export PDF",
    **turbo_desktop_bridge("menu-item",
      title: "Export PDF",
      shortcut: "Cmd+E"
    ) %>

Rails Gem

The turbo_desktop-rails gem gives your Rails app awareness of the desktop shell, exactly like turbo-rails does for Turbo Native mobile apps.

Detection

The gem detects desktop app requests by inspecting the User-Agent header. The Tauri shell sends a UA string like Turbo Desktop/0.2.5 (macOS; aarch64).

View Helpers

Usage Examples

<%# Hide the web navbar inside the desktop app %>
<% turbo_web_only do %>
  <nav class="web-navbar">...</nav>
<% end %>

<%# Show a native-only sidebar button %>
<% turbo_desktop_only do %>
  <button data-controller="sidebar">Toggle Sidebar</button>
<% end %>

<%# Platform-specific styles %>
<% if turbo_desktop_platform == "macos" %>
  <body class="desktop macos">
<% end %>

Quick Start

git clone https://github.com/aguspe/turbo_desktop.git
cd turbo_desktop
cargo install tauri-cli
npm install

{
  "server_url": "http://localhost:3000",
  "app_name": "My App",
  "path_configuration_url": "http://localhost:3000/turbo-desktop/path-configuration.json"
}

# Gemfile
gem "turbo_desktop-rails"

bundle install
rails generate turbo_desktop:install

# config/routes.rb
mount TurboDesktop::Engine, at: "/turbo-desktop"

# Start your Rails server in one terminal
bin/rails server

# Start the Tauri desktop app in another
cargo tauri dev

How It Relates to turbo-ios and turbo-android

Turbo Desktop is the third leg of the Hotwire Native story. Same patterns, different platform.

The key insight is that every concept transfers directly: if you already know how to structure a Hotwire Native mobile app with path configuration and Strada bridge components, you already know how to use Turbo Desktop. The only difference is that the native shell is written in Rust (via Tauri) instead of Swift or Kotlin.