RailsFast Native - Android

RailsFast Android is a thin Hotwire Native Android shell around your RailsFast Base app. This page gets you from git clone to a running app pointed at your Rails server, then walks the two-activity architecture, native tabs, bridge components, base URL config, deep links, backup rules, and the rename script you run to make the project yours.

Clone, Point, Run

You need three things before the app does anything useful:

1. A running RailsFast Base server (your "product brain"). The shell is not standalone — it renders Rails screens.
2. Android Studio with a recent toolchain. The project uses AGP 9.1.0 and Kotlin 2.2.10, and compileSdk uses the newer release(36) { minorApiLevel = 1 } DSL. An older Android Studio may not parse the build files, so update Android Studio first if Gradle sync fails.
3. An emulator or device on minSdk 28 or higher (targetSdk / compileSdk are 36, Java 11).

Once your Rails server is up, install and run the debug build:

# from the railsfast-android repo root
./gradlew installDebug

Or just press Run in Android Studio. The app launches into /native/entry, Rails decides where to send you, and the shell takes it from there.

To point the build at a different host (a remote dev box, staging, production), pass the base URL as a Gradle property:

./gradlew installDebug -PrailsfastBaseUrl=https://app.example.com

Version Pin

Hotwire Native Android is pinned to 1.2.8 via the hotwireNative version ref in gradle/libs.versions.toml. Both dev.hotwire:core and dev.hotwire:navigation-fragments share that single ref, so they always move together.

# gradle/libs.versions.toml
hotwireNative = "1.2.8"

The Two-Activity Architecture

RailsFast Android uses two activities, both HotwireActivity subclasses that implement NativeShellHost:

• AuthActivity — the signed-out / standalone shell. A single navigator named standalone, hosting /native/entry, the welcome screen, auth sheets, and onboarding that must run outside tabs.
• MainActivity — the signed-in tab shell. Bottom navigation with one navigator host per tab.

This maps directly to the shell states Rails publishes: auth and onboarding live in AuthActivity; tabs lives in MainActivity.

The two-shell split keeps auth and setup from feeling trapped inside the main app tabs.

When Rails signals a shell-state change, the current activity starts the other one and finish()es itself, with activity transition animations suppressed (ActivityTransitions.kt) so the swap reads as a root replacement, not a screen navigation.

AuthActivity is the only entrypoint. It is exported=true, the MAIN/LAUNCHER activity, and the VIEW/BROWSABLE/DEFAULT deep-link target. MainActivity is exported=false with no intent filters — it is only ever reached via the AuthActivity handoff or an explicit intent.

Main Files

App bootstrap:

• app/src/main/java/com/railsfast/android/RailsFastApplication.kt — all Hotwire setup happens once in onCreate
• app/src/main/java/com/railsfast/android/AppConfiguration.kt — base URL, derived URLs, launch-location canonicalization
• app/src/main/assets/json/path-configuration.json — bundled fallback path config

Signed-out shell:

• app/src/main/java/com/railsfast/android/AuthActivity.kt
• app/src/main/res/layout/activity_auth.xml
• app/src/main/java/com/railsfast/android/AuthSheetFragment.kt

Signed-in tab shell:

• app/src/main/java/com/railsfast/android/MainActivity.kt
• app/src/main/res/layout/activity_main.xml
• app/src/main/java/com/railsfast/android/MainTabs.kt — the compile-time tab catalog and route-family matching
• app/src/main/java/com/railsfast/android/TabShellRouteDecisionHandler.kt — the cross-tab router
• app/src/main/java/com/railsfast/android/NativeShellConfiguration.kt — parses settings.shell from path config

Shell, fragments, bridge, and infrastructure:

• app/src/main/java/com/railsfast/android/WebFragment.kt
• app/src/main/java/com/railsfast/android/NativeShellHost.kt, NativeShellState.kt, ActivityTransitions.kt
• app/src/main/java/com/railsfast/android/NativeHttpClient.kt — cookie-forwarding GET client for native screens
• app/src/main/java/com/railsfast/android/NativeTabSelectionAware.kt — defers work on eagerly-created tab roots
• app/src/main/java/com/railsfast/android/bridge/ — NativeShellComponent, MenuComponent, OverflowMenuComponent, ToastComponent
• app/src/main/java/com/railsfast/android/features/me/ — the Compose-native Account screen

What RailsFastApplication Sets Up

All Hotwire configuration is centralized in RailsFastApplication.onCreate() via configureHotwire(), following the official Android demo shape rather than per-activity setup. It wires up:

• Path configuration — both the local asset (json/path-configuration.json) and the remote URL ($baseUrl/native/configurations/android/v1.json).
• Debug flags — debugLoggingEnabled and webViewDebuggingEnabled track BuildConfig.DEBUG.
• The user-agent prefix (see below).
• The default fragment destination — WebFragment.
• Route decision handlers (see below).
• Fragment destinations — WebFragment, AuthSheetFragment, NativeMeFragment.
• Bridge components — native-shell, menu, overflow-menu, toast.

Keeping both local and remote path configuration is intentional. The local file is your safe fallback when the remote contract is unavailable, stale, or has not loaded yet.

Tabs Are Native

RailsFast Android uses the stock Hotwire Native bottom tab system (HotwireBottomNavigationController, Hotwire 1.2+). Tabs are not bridge components — the tab bar is a native shell concern, while bridge components are for progressive native enhancements and app-shell signals.

Hotwire ships no built-in authed-vs-signed-out shell, so the two-activity pattern and the tab catalog are the app-layer contract that fills that gap.

How Tab Ownership Works

This is one of the most important concepts in the Android app.

Tabs are not owned only by their start URL. They are owned by route families.

The default tabs and the route families they own:

• home — /dashboard family (^/dashboard(?:/.*)?$), starts at /dashboard
• account — /native/me family (^/native/me(?:/.*)?$), starts at /native/me (the native Compose screen)
• settings — /settings, /organizations, /memberships, /invitations, and /billing families, starts at /settings

Each family is a regex matched against the URL path only. Query strings are stripped first, so /settings?return_to=/dashboard still belongs to the settings tab. The settings tab deliberately owns the whole ^/billing(?:/.*)?$ family (and the org/membership/invitation families) so those pages stay in the Settings navigator instead of flickering between tabs.

MainTabs.Catalog.tabFor(location) returns null when no route pattern claims the URL. That is a meaningful value: it means tab-agnostic — push the URL onto the tab the user is currently on rather than forcing a jump to the default tab. The stock AppNavigationRouteDecisionHandler does that in-tab push.

The Route Decision Handler Order

Hotwire.registerRouteDecisionHandlers(...) replaces the entire handler list — it does not append. The Router stops at the first matching handler, so order is load-bearing:

// app/src/main/java/com/railsfast/android/RailsFastApplication.kt
Hotwire.registerRouteDecisionHandlers(
    TabShellRouteDecisionHandler(),        // custom — MUST be first
    AppNavigationRouteDecisionHandler(),   // stock — normal in-app push
    BrowserTabRouteDecisionHandler(),      // stock — external links in a Custom Tab
    SystemNavigationRouteDecisionHandler() // stock — system navigation
)

TabShellRouteDecisionHandler only matches when the source navigator's tab differs from the tab that owns the target URL. On a match it routes cross-tab inside MainActivity and cancels the stock navigation; otherwise it falls through.

Bridge Components

RailsFastApplication registers four bridge components. Rails renders the matching hidden markup only when the component is advertised in the user agent (see User Agent), so these are gated by capability, not platform.

native-shell

NativeShellComponent listens for the connect event and reads {state, handoff, location}. State maps via NativeShellState.from() to AUTH / ONBOARDING / TABS, then the activity swaps shells. It ignores modal destinations unless handoff=true (the auth-success handoff document is the one modal allowed to reshape the root), ignores invisible fragments, and rejects updates from a navigator that is not the currently accepted one. This is the app-defined shell contract Hotwire does not provide out of the box.

toast

ToastComponent listens for show with the shared payload:

{
  "message": "Saved",
  "severity": "success"
}

Platform mapping:

• success (and unknown/legacy severities) → a short Android Toast
• error, warning, info → a Material Snackbar anchored on the fragment's own view, with an OK dismiss action

Non-success snackbars are LENGTH_INDEFINITE on purpose: auth and validation messages can appear while the keyboard or a sheet is up, and short durations are easy to miss. Snackbars anchor on the fragment view (never android.R.id.content) to stay visible above modals and sheets. The severity vocabulary (success/error/warning/info) mirrors the Rails HotwireNativeHelper flash normalization and the iOS toast component.

menu

MenuComponent listens for display with {title, items: [{title, index}]} and renders a Material BottomSheetDialog. On selection it replies {selectedIndex: <index>} with the server-provided index — the web stays the source of truth for what each action does. RailsFast Base uses this for the session-actions menu (Sign out).

overflow-menu

OverflowMenuComponent listens for connect with {label}, makes the toolbar's overflow item (inflated from R.menu.web) visible with that label, and replies connect when tapped so the web page can trigger the menu. The web page decides whether the overflow affordance exists; native only presents it.

References:

• Hotwire Native Android bridge components
• Android Snackbars
• Material Snackbars

The Native Account Screen (Compose)

The Account tab is the reference recipe for a fully native screen. Copy this split for any new native screen instead of putting networking or route parsing inside Compose:

• NativeMeFragment (a HotwireFragment, also NativeTabSelectionAware) hosts a ComposeView and owns the Hotwire destination.
• NativeMeViewModel owns loading / retry / unauthorized state and fetches off the Compose tree.
• NativeMeScreen is the pure Compose UI.

The view model builds a .json URL via AppConfiguration.jsonLocation(location) and fetches it through NativeHttpClient.get(...) on Dispatchers.IO. A 401 routes back to /native/entry (the session is gone, so converge on the auth shell). Because Android eagerly creates every tab root, the fetch is deferred to NativeTabSelectionAware.onTabSelected rather than firing while the tab is still hidden.

The JSON shape Rails serves at /native/me.json:

{
  "user": { "email": "...", "confirmed": true, "created_at": "2026-05-28T00:00:00Z" },
  "organization": { "name": "Acme" },
  "account": { "plan_name": "Free", "credits": 0, "onboarding": false }
}

Cookie Forwarding Is Manual on Android

NativeHttpClient is the load-bearing auth-continuity detail for native screens:

• It ships get, plus postJson / patchJson write helpers (verb-agnostic execute() with an optional per-call timeout). But cookie sync only solves authentication, not CSRF — a native write still needs a server-side CSRF policy before it will succeed (see the native write contract). Until you add that, treat reads as the safe default.
• OkHttp does not reuse the WebView's cookies automatically (unlike WebView-backed screens), so the client manually copies the Cookie header from CookieManager.getInstance().getCookie(location) onto each request.

// app/src/main/java/com/railsfast/android/NativeHttpClient.kt
val cookieHeader = cookies.getCookie(location)
cookieHeader?.let { requestBuilder.header("Cookie", it) }

Auth Sheets

Sign up and sign in both route through a single Android rule — hotwire://fragment/web/modal/auth-sheet — handled by AuthSheetFragment (a HotwireWebBottomSheetFragment).

The signed-out welcome screen stays web-rendered underneath the sheet, so dismissing it can briefly repaint the underlying WebView.

User Agent

The Android template prefix is:

// app/src/main/java/com/railsfast/android/RailsFastApplication.kt
"${BuildConfig.APPLICATION_NAME} Android; RailsFast Native Android;"

Hotwire Native appends the framework identity and bridge component list after the prefix:

{AppName} Android; RailsFast Native Android; Hotwire Native Android; Turbo Native Android; bridge-components: [...]

Do not duplicate the framework strings in the app prefix. The prefix is layered so Rails can feature-detect at three levels:

• hotwire_native_app? — any Hotwire app (framework level)
• railsfast_native_app? — any RailsFast native app (template level, the RailsFast Native Android segment)
• the app-specific {AppName} segment — your specific app

Base URL and Build Identity

Base URL resolution happens in app/build.gradle.kts:

1. The -PrailsfastBaseUrl=... Gradle property wins if present.
2. Otherwise railsfastDefaultBaseUrl, which derives from a railsfast.yml domain as https://<domain> (unless the domain is the placeholder example.com), and otherwise falls back to the gradle.properties value (http://10.0.2.2:3000).

The resolved value is exposed as BuildConfig.BASE_URL. AppConfiguration.baseUrl strips the trailing slash, and from it derives nativeEntryLocation (+ /native/entry) and androidPathConfigurationUrl (+ /native/configurations/android/v1.json).

Deep Links and App Links

AuthActivity is both the launcher and the app-link entrypoint. Its VIEW intent filter uses Gradle manifestPlaceholders derived from the base URL (deepLinkScheme, deepLinkHost) and android:autoVerify="${deepLinkAutoVerify}".

deepLinkAutoVerify is computed in Gradle and is true only when the scheme is https, the host is not localhost / 127.0.0.1 / 10.0.2.2, and the host is not a raw IPv4 address.

AppConfiguration.launchLocation canonicalizes the incoming URL: host-less paths get a leading /, same-host URLs pass through, localhost/127.0.0.1 are rewritten to the base host (so Hotwire does not treat dev hosts as external), and any other host is rejected as external.

Backup Rules

RailsFast Android keeps the WebView browser profile out of Android backup and device-transfer payloads. This is configured in the manifest and the res/xml/ rule files, not in the Hotwire bootstrap:

• app/src/main/AndroidManifest.xml — allowBackup=true with fullBackupContent=@xml/backup_rules and dataExtractionRules=@xml/data_extraction_rules
• app/src/main/res/xml/backup_rules.xml — excludes app_webview/ from the root domain (legacy full-backup)
• app/src/main/res/xml/data_extraction_rules.xml — excludes app_webview/ under both <cloud-backup> and <device-transfer> (Android 12+)

Reference: Android Auto Backup include/exclude rules.

Make the Project Yours: bin/rename

The template ships with the placeholder package com.railsfast.android. The code namespace stays on that placeholder until you rename the source tree. Run the rename script to make the project yours:

bin/rename

It prompts for (or accepts as flags) --package, --app-name, --base-url, --railsfast-config, --commit, and --yes. It:

• validates the package name against a Java-package regex
• upserts railsfastNamespace, railsfastApplicationId, railsfastApplicationName, and railsfastDefaultBaseUrl in gradle.properties
• physically moves the Kotlin package tree under app/src/{main,test,androidTest}/java
• rewrites package references in all .kt / .java files
• can optionally update native.android.package_name in a railsfast.yml
• can git-commit the rename when --commit is passed

Where To Customize Android

Change the base URL

Edit gradle.properties (railsfastDefaultBaseUrl) for the committed default, or pass -PrailsfastBaseUrl=... per build. AppConfiguration.kt derives everything else from BuildConfig.BASE_URL.

Change the launcher icon and splash screen

Use App Icons and Launch Screens for the complete workflow. Android needs separate adaptive foreground/background layers, a monochrome layer for themed icons, generated legacy mipmaps, and intentional day/night splash colors. Do not reuse the already-masked iOS icon as the Android adaptive foreground.

Change the supported native tabs

Edit MainTabs.kt, activity_main.xml (the navigator hosts), and the local fallback path-configuration.json if your default shell policy changes. Use this when adding a tab, changing tab titles or icons, or adding navigator hosts.

Change shell handoff behavior

Edit AuthActivity.kt, MainActivity.kt, and ActivityTransitions.kt — only if the app's shell architecture actually changes.

Change Android-only presentation behavior

Edit WebFragment.kt (toolbar visibility, server-driven hide_navigation_bar) and AuthSheetFragment.kt (sheet sizing). Use this for genuinely Android-only fragment behavior.

Native title fonts

Most of what you see on a tab root is your Rails HTML, so it already uses whatever fonts your web app loads — there is nothing to do on the Android side for that chrome.

The surfaces that are actually native Android views, and therefore render in the system font, are narrow: the bottom-tab labels and the pushed-screen toolbar title.

If you do want to brand those native labels, it is plain Android theming, not a RailsFast mechanism: drop your .ttf/.otf into res/font, point your toolbar/tab textAppearance at it in your theme, and use a shared Typography for any Compose-native screens. Reach for this only if matching the native labels to your web type is worth carrying the font in the binary — for most apps the system font next to your web header looks perfectly native.

When To Put Something In Android Instead of Rails

Put it in Android only when it is a true Android container concern.

Belongs in Android: activity structure, fragments, bottom navigation, Android-only transitions, Android-only native UI.

Belongs in RailsFast Base instead: route ownership rules, tab policy, product onboarding rules, billing/pricing policy. When in doubt, ask the question from the overview — is this a product rule or a native container detail?

Related Docs

• Native Overview
• RailsFast Base for Native
• RailsFast iOS
• Customization Workflow
• App Icons and Launch Screens
• Notifications