Path Configuration

Path configuration is the core routing mechanism in Turbo Desktop. It maps URL patterns to presentation rules — the same concept from turbo-ios and turbo-android.

How It Works

1. Your Rails app serves a JSON path configuration at /turbo-desktop/path-configuration.json
2. When a user navigates, turbo-desktop.js intercepts the Turbo Drive visit
3. The Rust shell checks the URL against the path configuration rules
4. The last matching rule determines how the URL is presented

Configuration

Define your rules in config/initializers/turbo_desktop.rb:

TurboDesktop.configure do |config|
  config.path_configuration = {
    settings: {
      screenshots_enabled: false
    },
    rules: [
      # Catch-all: navigate in the current window
      { patterns: ["/"], properties: { presentation: "default" } },

      # Forms open as modal overlays
      { patterns: ["/new$", "/edit$"], properties: { presentation: "modal" } },

      # Reports open in a separate window
      { patterns: ["/reports/"], properties: { presentation: "new_window" } },

      # Settings handled natively
      { patterns: ["/settings"], properties: { presentation: "native" } },
    ]
  }
end

Presentations

Presentation	Behavior	Window Size
default	Navigate in the current window (Turbo Drive)	Current window
modal	Open in a modal overlay window	800 x 600
new_window	Open in a full separate window	1200 x 800
replace	Replace the current page (no back button)	Current window
native	Emit a native-screen-requested event	N/A
none	Do nothing — handled by a Bridge Component	N/A

Pattern Matching

• Patterns are regular expressions matched against the URL path
• Last match wins — put your catch-all rule first, specific rules after
• Common patterns:
  • / — matches everything (catch-all)
  • /new$ — URLs ending in /new
  • /edit$ — URLs ending in /edit
  • /reports/ — URLs containing /reports/
  • ^http — external URLs (starting with http)

Examples

Forms as Modals

The most common pattern — any new/edit form opens as a modal overlay:

{ patterns: ["/new$", "/edit$"], properties: { presentation: "modal" } }

This means /tasks/new, /users/42/edit, etc. all open as modals without any changes to your Rails views.

Detail Pages in New Windows

{ patterns: ["/reports/\\d+$"], properties: { presentation: "new_window" } }

External Links

{ patterns: ["^http"], properties: { presentation: "new_window" } }

Native Screens

For screens you want to build entirely in Rust/native UI:

{ patterns: ["/settings"], properties: { presentation: "native" } }

The desktop shell will emit a native-screen-requested event that your Rust code can handle.