rb-hotwire-native

name	rb:hotwire-native
description	Building native iOS/Android shells with Hotwire Native: path configuration, bridge components, native navigation, Turbo Native bridges.
effort	medium
disable-model-invocation	true

Hotwire Native

Iron Laws

1. Reuse web screens first - Build in HTML/CSS before reaching for native screens.
2. Use path configuration to control routing behavior declaratively.
3. Bridge components for native upgrade - Use Strada when the web isn't enough.
4. Keep native and web in sync - Version bridge components together.
5. Test on real devices - Simulators don't catch all native behaviors.
6. Handle offline gracefully - Native apps expect resilience.

Overview

Hotwire Native wraps your web app in a native shell (iOS/Android), providing:

• Native navigation transitions between web screens
• Access to native SDKs and APIs via Bridge Components
• Push notifications, camera, location, and other native features
• App store distribution with web-first updates
• Fallback to native screens when needed

┌─────────────────────────────────────────────────────────────┐
│                    HOTWIRE NATIVE ARCHITECTURE              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐         ┌──────────────┐                 │
│  │   iOS App    │         │ Android App  │                 │
│  │  (Swift/UIKit)│        │  (Kotlin)    │                 │
│  └──────┬───────┘         └──────┬───────┘                 │
│         │                        │                          │
│         └────────┬───────────────┘                          │
│                  │                                          │
│         ┌────────▼────────┐                                 │
│         │  Turbo Native   │                                 │
│         │    Navigator    │                                 │
│         └────────┬────────┘                                 │
│                  │                                          │
│         ┌────────▼────────┐                                 │
│         │   WebView       │                                 │
│         │ (WKWebView/     │                                 │
│         │  WebChromeClient)│                                │
│         └────────┬────────┘                                 │
│                  │                                          │
│                  │  HTTP/WebSocket                         │
│                  │                                          │
│         ┌────────▼────────┐                                 │
│         │   Rails App     │                                 │
│         │  (Turbo/        │                                 │
│         │   Stimulus)     │                                 │
│         └─────────────────┘                                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Quick Start

Installation

See detailed setup guides:

• iOS Setup — Xcode, CocoaPods, Swift configuration
• Android Setup — Gradle, Kotlin, manifest configuration

Core Concepts

Path Configuration

Declarative routing rules control native vs web behavior:

{
  "rules": [
    {
      "patterns": ["/sign_in", "/sign_up"],
      "properties": { "context": "modal" }
    },
    {
      "patterns": ["/settings/*"],
      "properties": { "context": "default" }
    }
  ]
}

See Path Configuration for full reference.

Bridge Components (Strada)

Bridge components expose native SDKs to your web app:

// Web side
import { BridgeComponent } from "@hotwired/strada"

export default class extends BridgeComponent {
  static component = "datepicker"
  
  openDatePicker() {
    this.send("open", { minDate: "2024-01-01" })
  }
}

See Bridge Components for component authoring.

References

Need	Reference
iOS Hotwire Native install + project structure	${CLAUDE_SKILL_DIR}/references/ios-setup.md
Android Hotwire Native install + project structure	${CLAUDE_SKILL_DIR}/references/android-setup.md
path-configuration.json semantics + matching rules	${CLAUDE_SKILL_DIR}/references/path-configuration.md
bridge component authoring (web ↔ native messaging)	${CLAUDE_SKILL_DIR}/references/bridge-components.md
ready-made bridge components (Camera, Location, Share, Alerts)	${CLAUDE_SKILL_DIR}/references/common-components.md
native screens — when to choose native UI over web	${CLAUDE_SKILL_DIR}/references/native-screens.md
push-notification wiring (APNS / FCM)	${CLAUDE_SKILL_DIR}/references/push-notifications.md
offline-mode strategy + caching	${CLAUDE_SKILL_DIR}/references/offline-support.md
testing native flows + bridge component tests	${CLAUDE_SKILL_DIR}/references/testing.md
Hotwire-Native production best practices	${CLAUDE_SKILL_DIR}/references/best-practices.md
Hotwire-Native anti-patterns	${CLAUDE_SKILL_DIR}/references/anti-patterns.md

Key Decisions

Decision	Recommendation
Web vs Native screen	Start with web; use native for platform-specific features (camera, GPS)
Bridge component needed?	Use when HTML5 API insufficient (background location, push notifications)
Path config patterns	Use wildcards sparingly; prefer explicit paths
Testing strategy	Unit test web; integration test native flows on real devices

See Also

• hotwire-patterns — Turbo Frames, Streams, Stimulus (NL-routed)
• rails-contexts — Controllers, routing, contexts (NL-routed)
• /rb:state-audit — Audit state management