| 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
- Reuse web screens first - Build in HTML/CSS before reaching for native screens.
- Use path configuration to control routing behavior declaratively.
- Bridge components for native upgrade - Use Strada when the web isn't enough.
- Keep native and web in sync - Version bridge components together.
- Test on real devices - Simulators don't catch all native behaviors.
- 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:
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:
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
