In Hotwire Native, how do the iOS and Android shells turn a Turbo web app's link taps into native screens, and what stays web?
answer
- content is web, navigation is native
- a native Turbo adapter receives visit proposals
- push a screen, render in a web view
- other domains open in an in-app browser
- successor to Turbo Native and Strada
basics
~20 sHotwire Native registers its own Turbo adapter, so a link tap becomes a visit proposal to native code, which pushes a native screen rendering the server's HTML in a web view. Pages stay web; navigation and gestures are native.
solid answer
~50 sThe shell is a native app whose screens display your Rails pages. Turbo runs inside the web view, and Hotwire Native installs a Turbo adapter there with `Turbo.registerAdapter`, so a tap on an internal link is handed to native code as a visit proposal instead of navigating the web view. The navigator pushes a native screen with the platform animation, and that screen renders the page through a web view shared by its navigation stack (on iOS one session for the main stack and one for modals). Going back pops natively, using a cached screenshot, and links to other domains open in `SFSafariViewController` or Custom Tabs. Everything rendered stays web, so a deploy updates the app without a store release. Path configuration, bridge components and native screens refine that default. Hotwire Native replaced the separate Turbo Native libraries and Strada.
code
swift · 19 lines// SceneDelegate.swift
import HotwireNative
import UIKit
let rootURL = URL(string: "https://habits.example.com")!
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
var window: UIWindow?
private let navigator = Navigator(configuration: .init(
name: "main",
startLocation: rootURL
))
func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
options connectionOptions: UIScene.ConnectionOptions) {
window?.rootViewController = navigator.rootViewController
navigator.start()
}
}go deeper
Recall that the pages stay web while navigation, transitions and modals are native, and that a deploy updates the content.
Explain the native Turbo adapter, visit proposals, the per-stack web view and the default push, replace and pop behaviour.
Know what still needs a native release, how the server detects the app, and how predecessor Turbo Native code keeps working.
Frame Hotwire Native as progressive enhancement of a web app, and plan where native code earns its cost.
## Content is web, navigation is native **Hotwire Native** is a pair of libraries, one for iOS (Swift) and one for Android (Kotlin), that wrap a Turbo-powered web app in a native shell. Its documentation sums it up as "content is all web, navigation is all native". For a habit tracker built in Rails, the list of habits, the habit form and the streak history are ordinary ERB pages; the navigation bar, screen transitions, back gesture, tab bar and modals are real platform components. ## What happens on a link tap 1. The page is running **Turbo** in a web view. Hotwire Native injects a script that calls `Turbo.registerAdapter`, replacing Turbo's browser adapter with a native one. 2. When the user taps an internal link, Turbo asks its adapter to visit; the native adapter forwards that **visit proposal** to native code instead of navigating in place. 3. The **navigator** consults the path configuration, then pushes a new native screen onto the stack with the platform's animation and shows a spinner. 4. The screen renders the page in a **web view**. On iOS the navigator keeps one Turbo session for the main stack and another for modals, reusing each web view as screens change rather than creating a browser per screen. 5. Going back pops the native screen, showing a cached screenshot while the earlier page is restored, so the interactive pop gesture feels native. Two defaults are worth knowing: visiting the current page's URL again **replaces** the screen instead of pushing a duplicate, and visiting the previous screen's URL **pops** back to it. ## What is decided where | concern | where it lives | |---|---| | page content, forms, validation errors | the Rails app, as HTML | | push, modal, replace, pull to refresh | path configuration rules, a JSON file the app loads | | native buttons or menus on a web screen | bridge components (a Stimulus controller plus native code) | | a fully native screen | a Swift or Kotlin screen mapped to a URL | | other domains | in-app browser: `SFSafariViewController` on iOS, Custom Tabs on Android | Because the content is web, shipping a new habit field or fixing a typo is a server deploy; the installed apps pick it up on the next visit without an app store submission. Only native code, such as a new bridge component or native screen, needs a release. ## How the server knows The native web views send a user agent containing `Hotwire Native iOS;` or `Hotwire Native Android;`, and also `Turbo Native iOS;` or `Turbo Native Android;` for older server code, followed by the list of bridge components the build supports. turbo-rails turns that into `hotwire_native_app?`, which views use to hide web-only chrome such as a duplicate navigation bar. ## The Turbo Native predecessors Before Hotwire Native, the same idea shipped as separate **Turbo Native** libraries for iOS and Android, with **Strada** as a separate add-on for web-to-native components. Hotwire Native merged them: - Strada components became **bridge components**, built in by default; the injected bridge still falls back to a legacy `window.Strada` object on the page. - turbo-rails keeps `turbo_native_app?` as an alias of `hotwire_native_app?`, and its check matches either `Turbo Native` or `Hotwire Native` in the user agent. - The native user agent keeps the old `Turbo Native` marker, so servers written for the predecessors still recognise the new apps. ## Where the model stops The shell is not a native rewrite. Screens rendered in a web view still need a network for fresh content, still behave like web pages (forms, scrolling, text selection), and still depend on the Rails app's mobile layout. Teams move individual screens or controls to native code only where the web version falls short, which is a later and deliberate decision.
- Why can a typo fix ship to the native apps without an app store release?The screens render HTML fetched from the Rails app at visit time, so a server deploy changes what every installed app shows on its next visit. Only native code, such as bridge components, native screens or a bundled path configuration, needs a new build.
- What happens when the habit tracker links to a page on another domain?Hotwire Native treats it as external and does not route it through the app's navigator. By default iOS opens it in an `SFSafariViewController` and Android in a Custom Tab; schemes such as `mailto:` go to the system. Route decision handlers can change that.
- How does code written for Turbo Native keep working with Hotwire Native apps?The new apps still put `Turbo Native iOS;` or `Turbo Native Android;` in their user agent, and turbo-rails keeps `turbo_native_app?` as an alias whose check accepts either name, so older views and controllers still detect the app.
A Hotwire Native app is a native picture frame around web pictures: the frame, its hinges and the way you flip between pictures are built by the platform, while every picture is painted on the server and can be repainted at any time without rebuilding the frame.
- Hotwire Native renders each page as native views, translating HTML into UIKit or Android widgets
- Every page change in the shell requires a new app store release
- Tapping an internal link navigates the web view in place, like a mobile browser
- Hotwire Native needs a separate JSON API alongside the HTML views
- Strada must be added as a separate dependency for bridge components
Assumes Hotwire Native 1.3 for iOS and Android (tag 1.3.1) with Turbo 8 and turbo-rails 2.0; earlier apps used the separate Turbo Native libraries and Strada.