RailsFast Native - iOS

RailsFast iOS is a thin UIKit + Hotwire Native shell around your RailsFast Base app.

Its job is not to rebuild the product in Swift. Its job is to:

• bootstrap Hotwire Native correctly
• present the right native shell
• keep iOS-specific behavior polished
• consume the Rails server contract cleanly
• stay template-generic so downstream apps can brand and extend it

The iOS starter follows the same Rails contract as RailsFast Android: Rails owns product semantics, and the native repo owns iOS container details.

Rails owns product semantics. The native repo owns iOS container details.

Run It On A Simulator

Get the shell running before you change anything. You only need a running RailsFast server and a couple of tools.

The Xcode project is generated by XcodeGen from project.yml. There is no committed .xcodeproj to fight with — you regenerate it from the YAML.

# from the railsfast-ios repo root
brew install xcodegen          # one-time
xcodegen generate              # writes RailsFast.xcodeproj from project.yml
open RailsFast.xcodeproj        # open in Xcode

Then:

1. Start your RailsFast Base server so the shell has something to render (bin/dev, serving http://localhost:3000).
2. In Xcode, pick an iOS Simulator and press Run.
3. The app launches into /native/entry and Rails decides what to show next.

The base URL defaults to http://localhost:3000. To point at a different server, edit RAILSFAST_BASE_URL in project.yml and run xcodegen generate again (or override it as an Xcode build setting).

Toolchain And Version Pins

A few pins are load-bearing. Know them before you upgrade anything.

• Hotwire Native iOS is pinned to exactly 1.3.0-beta via Swift Package Manager (project.yml). This is an exact tag, not a semver range.
• Deployment target: iOS 14.0. Swift 5.9. xcodeVersion: 16.0.
• Bundle id default com.railsfast.ios, device family 1,2 (iPhone + iPad).

Release Versioning

RailsFast iOS stores version/build settings in project.yml:

CURRENT_PROJECT_VERSION: 1
MARKETING_VERSION: "1.0.0"

Info.plist then derives:

• CFBundleShortVersionString = $(MARKETING_VERSION)
• CFBundleVersion = $(CURRENT_PROJECT_VERSION)

Apple treats CFBundleShortVersionString as the user-facing release version and CFBundleVersion as the uploaded build iteration. The template keeps those values in project.yml because XcodeGen regenerates RailsFast.xcodeproj from that YAML. Do not edit Version or Build only in Xcode on the signing Mac: those edits live in the generated project and are easy to lose.

Use the repo helper before archiving:

# Normal new public release: 1.0.0 -> 1.0.1, build 1 -> 2
ruby scripts/ios_release_version

# Another TestFlight build for the same public version: build only
ruby scripts/ios_release_version --bump none

# Exact sync after an emergency manual edit
ruby scripts/ios_release_version --version 1.0.1 --build 2

The helper updates project.yml, runs xcodegen generate, and leaves both project.yml and RailsFast.xcodeproj/project.pbxproj ready to commit and push. The signing Mac should then pull the committed version before archiving.

Why not Apple's agvtool directly? agvtool is built for projects where project.pbxproj is the source of truth. It searches the Xcode project for CURRENT_PROJECT_VERSION and writes version values from there, while RailsFast iOS intentionally treats project.yml as the source of truth.

If you later move signing and upload to CI, the network-aware versioning path is App Store Connect or fastlane. Apple exposes uploaded builds through the App Store Connect API, and fastlane's latest_testflight_build_number can derive the next build number from already-uploaded TestFlight builds. RailsFast does not add that dependency by default because deterministic source-controlled bumps are enough for local or remote-Mac signing.

The Main Files

App bootstrap

• RailsFast/App/AppDelegate.swift
• RailsFast/App/SceneDelegate.swift
• RailsFast/Core/AppConfiguration.swift
• RailsFast/Resources/Info.plist
• RailsFast/RailsFast.entitlements
• project.yml

AppDelegate.didFinishLaunching does two things, in order:

1. configureAppearance() — nav bar and tab bar appearance
2. configureHotwire() — path config, user agent, custom web view, bridge components, route handlers

Keep that order. Appearance is applied first so the chrome is correct before the first navigation. The window and root view controller are not created here — that happens in SceneDelegate.scene(_:willConnectTo:), which is where the actual root shell gets set.

configureHotwire() is the single registration point. It should stay boring and explicit. Important defaults:

• Hotwire.config.pathConfiguration.matchQueryStrings = false
• bundled path configuration first, then the remote Rails config
• tests use only the bundled path configuration (deterministic)
• Hotwire.config.applicationUserAgentPrefix = "RailsFast iOS; RailsFast Native iOS;"
• Hotwire.config.defaultViewController = { WebViewController(url: $0) }
• Hotwire.config.makeCustomWebView = { RailsFastWebView(...) }
• Hotwire.config.hidesTabBarWhenPushed = true

Register bridge components and route handlers before any navigation starts.

User Agent

AppConfiguration.userAgentPrefix builds:

{CFBundleDisplayName} iOS; RailsFast Native iOS;

Hotwire Native appends the rest:

Hotwire Native iOS; Turbo Native iOS; bridge-components: [...]

That keeps the downstream app name, the RailsFast template identity, the Hotwire framework identity, and the registered bridge capabilities in one user agent without duplicating framework strings. This mirrors the Android layering exactly, so Rails' hotwire_native_app? and railsfast_native_app? detection behaves identically on both platforms.

The iOS Architecture

The iOS starter is a thin UIKit shell over Hotwire Native with two roots that swap on window.rootViewController:

• a signed-out / onboarding Navigator (configuration name auth, starting at /native/entry)
• a signed-in RailsFastTabBarController (a HotwireTabBarController subclass)

SceneDelegate starts in the auth navigator. Rails then publishes shell state through the native-shell bridge component, using the same three-state vocabulary as Android and Rails:

• auth — signed out, no tabs
• onboarding — signed in but setup runs without tabs
• tabs — signed in, native tab shell

When Rails sends tabs, iOS swaps the window root to RailsFastTabBarController and loads the current tab catalog. The auth navigator is recreated fresh on each transition back to .auth / .onboarding for a clean slate — this mirrors Android's finish() + startActivity(AuthActivity) root swap.

This is the same two-shell model as Android. Auth, welcome, and onboarding do not live inside the signed-in tab bar — that is deliberate, and it avoids the hybrid-app smell where sign-in screens look trapped under app tabs.

Tab routing has one extra iOS-specific guard. The framework's HotwireTabBarController.route(_:) only ever routes through the currently selected navigator, so RailsFast iOS selects the owning tab first — and then must not race that tab's root load. The shell tracks, per tab root, whether the root's cold boot is still in flight, no matter who started it: the framework starting the selected tab at launch, a user tapping a cold tab, or shell routing itself. While a root is booting, any target other than the exact root URL already loading waits for requestDidFinish(at:) before routing — child routes and query-bearing roots such as /settings?return_to=/dashboard alike — and a newer route into the same booting tab replaces the waiting one rather than cancelling the root load. The finished signal fires for failed roots too, so a deep link is delivered (or shows the standard error screen) instead of being dropped. Tabs with a fully native root, like Account's /native/me, never issue a web request for their root, so nothing waits on them: routes go out immediately, which is equally race-free. Net effect: queries survive cold starts, and there are never two overlapping cold WKWebView.load() calls on one navigator.

Key files:

• RailsFast/App/SceneDelegate.swift
• RailsFast/Bridge/NativeShellComponent.swift
• RailsFast/Core/ShellState.swift
• RailsFast/Shell/RailsFastTabBarController.swift

Shell Handoff Rules

The native-shell bridge is page-scoped, but shell changes are scene/root-controller state. So the bridge component posts a NotificationCenter event instead of reaching directly into SceneDelegate. That keeps the component decoupled from UIKit scene plumbing.

Two details are load-bearing:

1. Shell transition notifications are dispatched on the next main-queue turn (DispatchQueue.main.async), not synchronously.
2. Modal bridge messages are ignored unless Rails marks the message as a handoff (handoff == true || !isModalPresentation).

The async boundary gives sibling bridge components in the same HTML document a chance to fire before the root controller swaps. This matters for login success: the handoff document carries both a toast message and a native-shell message, and you want the verified-login toast to fire before the root swap deactivates the destination. This mirrors Android's runOnUiThread async boundary.

The modal guard prevents a background modal page from reshaping the root shell just because its bridge connects while the presenting tab should stay in control.

The Four Bridge Components

iOS registers exactly four bridge components, in this order: NativeShellComponent, ToastComponent, MenuComponent, OverflowMenuComponent. Each one has a web BridgeComponent controller in RailsFast Base and an Android counterpart — the names, event names, and JSON payloads must match across all three.

• severity is one of success | error | warning | info.
• state is one of auth | onboarding | tabs.

Toasts

RailsFast uses bridge-driven native toasts for nonblocking Rails flash feedback. The toast component receives show with a {message, severity} data object — message and severity are fields of the message data, not siblings of an event key.

iOS has no first-party UIKit toast control, so RailsFast renders a custom UIKit material capsule with:

• an SF Symbol severity icon
• an adaptive blur material background
• haptic feedback (success / warning / error notification haptics; a light impact for info)
• a VoiceOver announcement
• two-line support for validation messages
• swipe-down dismissal, plus auto-dismiss

Presentation rules:

• normal visible pages render the toast in their source destination
• /native/handoff login-success toasts render on the active foreground window after a short delay, so the verified-login toast survives the auth → tabs root swap
• /native/entry logout transitions intentionally drop stale detached toasts

Menu and overflow menu (iOS 26 subtlety)

These two components are small, but the iOS 26 details are where the work is.

The overflow menu creates an image-only bar button (UIImage(systemName: "ellipsis.circle"), no title):

// RailsFast/Bridge/OverflowMenuComponent.swift
let button = UIBarButtonItem(image: UIImage(systemName: "ellipsis.circle"), primaryAction: action)
button.accessibilityLabel = data.label

if #available(iOS 16.0, *) {
    viewController.navigationItem.trailingItemGroups = [
        UIBarButtonItemGroup(barButtonItems: [button], representativeItem: nil)
    ]
} else {
    viewController.navigationItem.rightBarButtonItem = button
}

The menu component builds a UIAlertController(.actionSheet) and anchors its popover to the native bar button, not the web source rect:

The web stays the source of truth for what each menu item does — iOS replies with the server-provided selectedIndex.

Key files:

• RailsFast/Bridge/NativeShellComponent.swift
• RailsFast/Bridge/ToastComponent.swift
• RailsFast/Bridge/MenuComponent.swift
• RailsFast/Bridge/OverflowMenuComponent.swift

Route Decision Handlers

Route handlers are registered in this order — first match wins:

// RailsFast/App/AppDelegate.swift
Hotwire.registerRouteDecisionHandlers([
    TabRouteDecisionHandler(),                  // custom — cross-tab routing
    AppNavigationRouteDecisionHandler(),        // stock — in-tab pushes
    SafariViewControllerRouteDecisionHandler(), // stock — external links in Safari
    SystemNavigationRouteDecisionHandler()      // stock — mailto:, tel:, etc.
])

Native Tabs And Cross-Tab Routing

RailsFast iOS uses a custom RailsFastTabBarController on top of Hotwire's HotwireTabBarController.

Hotwire's stock tab controller routes through the currently selected tab's active navigator. RailsFast needs Android-equivalent ownership routing: before routing, the shell selects the tab that owns the URL.

TabCatalog is the native model for the Rails settings.shell.tabs contract. The default RailsFast tabs are:

• home starts at /dashboard
• account starts at /native/me
• settings starts at /settings

The Settings tab owns a broader route family, not just its start URL:

• ^/settings(?:/.*)?$
• ^/organizations(?:/.*)?$
• ^/memberships(?:/.*)?$
• ^/invitations(?:/.*)?$
• ^/billing(?:/.*)?$

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

TabCatalog accepts server-defined tabs only when they are safe for iOS: known RailsFast keys reuse native title/icon defaults, while unknown keys need an explicit title and a valid SF Symbol name (otherwise they are skipped with a warning). That keeps downstream apps flexible without letting arbitrary remote strings crash the native tab bar.

Cross-tab routing lives in TabRouteDecisionHandler + TabRoutingCoordinator. It matches only when the source navigator's tab differs from the tab that owns the target URL. Unclaimed routes are tab-agnostic: TabCatalog.tab(for:) returns nil, the custom handler does not match, and Hotwire's stock handler pushes the URL onto the current tab.

Key files:

• RailsFast/Shell/Tabs.swift
• RailsFast/Shell/RailsFastTabBarController.swift
• RailsFast/Shell/TabRoutingCoordinator.swift

Path Configuration

Rails is the source of truth for route policy. iOS loads path configuration from two sources, in order:

1. bundled fallback: RailsFast/Resources/path-configuration.json
2. Rails server: /native/configurations/ios/v1.json

The bundled file is a safety net, not a second product contract. Keep it aligned with the Rails server config and with the Android catalog.

The iOS rules use platform-idiomatic presentation properties (view_controller, modal_style, presentation) that Android does not — Android uses uri deeplinks instead. The shared part is settings.shell (the tab catalog); the rules[] arrays differ by platform. Do not copy iOS modal_style into Android.

Auth sheet detents (iOS-only)

• /users/sign_up opens as a modal with modal_style: large (full-height detent). The signup form is taller — email, password, password confirmation, terms — and a medium detent forced users to swipe up before they could see and accept the terms.
• /users/sign_in opens as a modal with modal_style: medium (half-height). It is just email + password.

Native HTTP And The CSRF Posture

Fully native screens (like the Account tab) reuse the shared Rails session instead of inventing a second auth system. Here is how that works on iOS:

• Hotwire Native syncs WKWebView cookies into HTTPCookieStorage.shared after every page load (Navigator.sessionDidFinishRequest).
• NativeHttpClient configures its URLSession with httpCookieStorage = .shared, so its requests automatically carry the Rails session cookie.
• It sends Accept: application/json and decodes typed responses.

Key file: RailsFast/Core/NativeHttpClient.swift

Session Recovery: 401 → Auth Shell

When a Rails session expires, web and native should converge back on /native/entry rather than getting stuck.

• SceneDelegate.visitableDidFailRequest treats TurboError.http(401) as "the session is gone" and calls transitionToShell(.auth) instead of recovering in-stack.
• NativeMeViewModel separately maps a 401 JSON response to its .unauthorized state and invokes onUnauthorized, which SceneDelegate wires to transitionToShell(.auth).

Both paths rebuild the signed-out shell so the user lands cleanly on the welcome flow.

Key file: RailsFast/App/SceneDelegate.swift

Add A Native Screen

The reference recipe is the Account tab (Features/Me), selected by the Rails path-config view_controller: "me" rule. Copy this four-part split instead of putting networking or route parsing inside SwiftUI views:

• NativeMeViewController — a UIViewController conforming to PathConfigurationIdentifiable, hosting a UIHostingController<NativeMeView> pinned to all edges. This is the Hotwire destination.
• NativeMeViewModel — a @MainActor ObservableObject owning the loading / loaded / unauthorized / error state machine, dedup, retry, and the fetch through NativeHttpClient.
• NativeMeView — pure SwiftUI presentation, no networking.
• NativeMePayload — the Decodable shape (with a flexible decoder for credits, since Rails may serialize counters as numbers or strings).

Keep the canonical Rails URL as the screen identity.

To wire a new screen: add the view controller, give it a pathConfigurationIdentifier, map it in SceneDelegate.handle(proposal:), and add a view_controller rule in the Rails path configuration.

The Custom Web View

RailsFast installs RailsFastWebView through Hotwire.config.makeCustomWebView. Use that hook instead of forking Hotwire Native.

Its configure() currently owns:

• backgroundColor = .systemBackground and isOpaque = false — together these let the system background show through, which is what keeps the chrome consistent during loads and transitions
• disabling the horizontal scroll indicator and horizontal bounce
• isInspectable = true under DEBUG (iOS 16.4+) to preserve Safari Web Inspector after replacing Hotwire's default factory
• removing the iPhone HTML form accessory bar (the prev/next/done toolbar)

Outer-scroll lock for fullscreen surfaces

WebViewController.locksOuterScroll(for:) disables the outer WKScrollView bounce for /native/entry, /native/auth/welcome, and any /onboarding prefix. These are fixed-chrome screens that own their layout in CSS, so the whole surface should not rubber-band away from the device edges — only the inner page body scrolls. This is part of the same "CSS owns the safe area" story as the Liquid Glass work below.

iOS 26 Liquid Glass

This is the standout work in the iOS shell, so it is worth understanding the problem before the fixes.

iOS 26 changed navigation bars and tab bars to Liquid Glass — a translucent material that samples and blurs whatever is behind it. That is beautiful for native content, but a Hotwire app paints its content with a web view, and getting glass to look right over a web view took care. RailsFast iOS handles three page families differently, all driven by a small pure value type, NativeChromePolicy, which resolves chrome from two inputs: hidesNavigationBar and supportsLiquidGlass.

Three page families

1. Fullscreen web chrome (tab roots, onboarding, /native/entry, /native/auth/welcome):

• hide the UIKit nav bar
• extend the web view to all edges
• contentInsetAdjustmentBehavior = .never
• let web CSS own the safe area through env(safe-area-inset-*)

2. Visible native nav bar on iOS < 26:

• opaque native nav bar, web view does not extend under it
• contentInsetAdjustmentBehavior = .automatic

3. Visible native nav bar on iOS 26+:

• let UIKit use Liquid Glass; extend the web view under the bar
• contentInsetAdjustmentBehavior = .automatic
• nudge the scroll offset to -adjustedContentInset.top so content starts below the bar

Extending the web view under the glass gives it one continuous adaptive surface to sample, which avoids the two-tone artifact where the glass and the page resolve against different backing colors.

Why the shared WKWebView makes this hard

Hotwire reuses one WKWebView per Session across visits. So scroll-view state — contentInsetAdjustmentBehavior, contentOffset — leaks between tab roots, pushed pages, and modal pages.

Keep the WKWebView opaque

RailsFast paints the shared WKWebView with .systemBackground so cold loads, overscroll, dark mode, and Liquid Glass all see the same adaptive surface. Keep the WKWebView itself opaque while doing so.

This is a correctness contract, not just a drawing optimization. A standalone, dependency-free iOS 26.3.1 reduction naturally reproduced an intermittent native-content collapse only when a compact-sheet WKWebView combined these two public appearance settings:

webView.isOpaque = false
webView.backgroundColor = .systemBackground

The DOM, WKWebView.bounds, and every public zoom value remained at the correct device width / 1.0, while the visible document and scrollView.contentSize.width fell to approximately deviceWidth / 980 (402 -> 164.6667, or 390 -> 155). Either appearance property alone completed 100-cycle controls without a qualifying collapse. The reduced case needs no Hotwire, Rails, network request, navigation controller, detent change, form, or representative app CSS.

RailsFast therefore keeps .systemBackground and explicitly sets isOpaque = true. Removing only the initial background assignment is not a valid fix: configureNativeWebViewChrome reapplies the route's adaptive backing on every activation. Keeping the view opaque preserves all intended visuals and removes the known trigger.

The shell still retains its public-API recovery guard. Prevention cannot update already-installed binaries, and a future WebKit version may reach the same inconsistent postcondition through another path. For an attached, loaded, non-zoomable document whose native content width is below 80% of its viewport, RailsFastWebView uses a visually indistinguishable setZoomScale(1.000001) nudge under a temporary 1.01 maximum, restores the original zoom contract and logical scroll position, and never reloads or mutates the DOM. Checks cover render, bounds settling, window attachment, appearance, and app resume.

The natural stress loop intentionally lives outside product CI; RailsFast's unit suite injects the captured public/native postcondition deterministically to test recovery without making ordinary builds flaky.

Exact sample, screenshots, property controls, and raw public-API JSONL evidence:

• https://github.com/rameerez/WKWebViewSheetViewportRepro/tree/dc68650bacffc75c9d07f4ef3c18cc30c0333333
• https://github.com/rameerez/WKWebViewSheetViewportRepro/blob/dc68650bacffc75c9d07f4ef3c18cc30c0333333/evidence/README.md#property-level-controls

The exact upstream report is listed first, followed by neighboring legacy-viewport and resize states that do not describe this precise healthy-DOM/native-only divergence:

• Exact reduced report: https://bugs.webkit.org/show_bug.cgi?id=319180
• https://bugs.webkit.org/show_bug.cgi?id=262207
• https://bugs.webkit.org/show_bug.cgi?id=170595
• https://bugs.webkit.org/show_bug.cgi?id=267545
• https://bugs.webkit.org/show_bug.cgi?id=191872

WebKit's animated-resize implementation is a plausible source-level mechanism, not a proven root cause—the reduced case needs no detent transition after presentation: https://github.com/WebKit/WebKit/blob/3489b26dd844b8115f10e23f7d194fcd9055d6e2/Source/WebKit/UIProcess/API/ios/WKWebViewIOS.mm#L3417-L3435

The cold-modal first-paint bug

This one was subtle enough to keep documented.

• Symptom: the first open of /users/sign_up or /users/sign_in painted web content behind the native nav bar. Second and later opens were fine. Pushed screens like /settings were always fine.
• Root cause: a modal Navigator has its own modal Session. On first open that session cold-boots a new WKWebView (a ColdBootVisit). The pre-render nudge correctly set the offset, then the cold-page render reset contentOffset.y back to 0. On second open the modal web view already holds the page, so activation has real size and the early nudge sticks — which is why the bug was first-open-only.
• The fix that worked: keep the normal lifecycle nudge for pushed/cached screens, then add a second render-phase nudge in visitableDidRender(). That is the first native hook after the cold-modal render reset, so it repairs without observers, timers, forced layout, or page JS. It only moves the scroll view when it is still effectively at the native top (contentOffset.y <= 1 — an inclusive 1pt tolerance for fractional offsets during the sheet animation); real Turbo scroll restoration (offset > 1) is left alone.

The iOS < 26 dock gap

Fullscreen surfaces own their bottom safe area in CSS (env(safe-area-inset-bottom), position: fixed; bottom: 0). On iOS < 26 the default .automatic adds a bottom safe-area inset, so the CSS viewport ends up inset and bottom: 0 lands at the safe-area edge, not the device edge — and env() returns 0 on the very first paint before viewport-fit=cover settles, so the page's compensation produces a visible gap above the home indicator.

Key file: RailsFast/Shell/WebViewController.swift

Deep Links

RailsFast iOS supports two deep-link classes:

• Custom scheme (railsfast://) for development and automation — no AASA needed, registered in Info.plist.
• Universal Links (production HTTPS) — declared via the Associated Domains entitlement.

SceneDelegate canonicalizes both forms into internal app URLs (relative paths become absolute, localhost aliases are normalized in dev, external hosts are rejected, query strings are preserved) and then routes through RailsFastTabBarController.routeDeepLink — or stashes the link as a pending deep link and replays it once the shell reaches .tabs.

Test the custom scheme on a booted simulator:

xcrun simctl openurl booted "railsfast:///dashboard?deeplink_smoke=1"
xcrun simctl openurl booted "railsfast:///settings?return_to=/dashboard"
xcrun simctl openurl booted "railsfast:///native/me?source=settings"

For tab-root links, expect: the correct tab selected, the tab bar visible, the query string preserved, and no duplicate pushed root page.

Universal Links require a real HTTPS domain and a valid AASA file. Localhost can validate the custom scheme and the server payload, but not Apple's full domain trust flow.

Universal Links And AASA

Universal Links are a two-sided trust relationship:

1. The iOS app declares an Associated Domains entitlement, e.g. applinks:yourdomain.com.
2. Rails serves an Apple App Site Association file listing the app ID and the claimed paths.

On the iOS side, the entitlement uses the $(RAILSFAST_ASSOCIATED_DOMAIN) build variable, which defaults to the placeholder example.com. Replace it with your real production host before shipping.

The Rails side serves /.well-known/apple-app-site-association (and a byte-identical alias at /apple-app-site-association). The path list is server-owned — it lives in config/railsfast/railsfast.yml under native.ios.app_link_paths. With no Team ID / bundle / paths configured, the endpoint fails closed and returns a valid non-claiming payload, so the template never publishes a fake Apple app claim.

Testing The iOS Template

RailsFastTests/AppConfigurationTests.swift is the single test file, and it encodes the whole contract. If you add a behavior worth protecting, add an assertion here. It covers:

• base URL stays template-generic; user-agent identity; custom scheme registered
• entitlement keeps applinks:$(RAILSFAST_ASSOCIATED_DOMAIN) and the example.com default
• URL canonicalization (localhost aliases, IPv6 ::1, rejecting wrong port / scheme / external / protocol-relative)
• jsonURL behavior; default + remote tab catalog parsing; matchQueryStrings = false
• the bundled path-config contract (account tab, me view controller, onboarding replace + hide nav bar)
• NativeMePayload flexible credits decoder
• every toast PresentationStrategy branch and its delays
• the full NativeChromePolicy matrix and the glass nudge decision tables (including the inclusive 1pt top tolerance)
• the opaque adaptive WKWebView prevention contract plus deterministic collapsed-content detection/recovery, including detached-session rejection

Run it:

cd ~/GitHub/railsfast-ios
xcodebuild test -project RailsFast.xcodeproj -scheme RailsFast -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

What To Customize In iOS

Change app identity

Edit project.yml, then xcodegen generate. Use it for: app display name, bundle ID, base URL, custom URL scheme, associated domain, navigation title font hook.

Change the app icon and launch screen

Use App Icons and Launch Screens for the complete asset-generation and cold-launch verification workflow. iOS derives installed icon sizes from one opaque 1024x1024 source, while the static UILaunchScreen and runtime StartupLoadingView must share the same LaunchBackground and optional LaunchLogo assets to avoid a white WebView interval.

Change native navigation title fonts

Native nav titles are UIKit text, not Rails HTML — CSS or Google Fonts loaded by the Rails app do not touch UINavigationBar, native tab labels, or SwiftUI-native screens. RailsFast iOS has one narrow hook in AppDelegate (BrandAppearance.navigationTitleFontName) that reads NAVIGATION_TITLE_FONT_NAME from Info.plist (a PostScript name), falling back to the system font if blank or unresolved.

To add a title font: add the .ttf/.otf files to a resource folder, register them under UIAppFonts in Info.plist, then set NAVIGATION_TITLE_FONT_NAME to the font's PostScript name.

# project.yml
settings:
  base:
    RAILSFAST_NAVIGATION_TITLE_FONT_NAME: Inter-SemiBold
info:
  properties:
    NAVIGATION_TITLE_FONT_NAME: "$(RAILSFAST_NAVIGATION_TITLE_FONT_NAME)"
    UIAppFonts:
      - Fonts/Inter-SemiBold.ttf

Change supported native tabs

Edit RailsFast/Shell/Tabs.swift, the bundled RailsFast/Resources/path-configuration.json, and the Rails path configuration in RailsFast Base. The server can hide, show, and route supported tabs, but the iOS binary still needs a safe native representation (title + SF Symbol) for every supported tab.

Change shell behavior

Edit SceneDelegate.swift / NativeShellComponent.swift — only when the actual shell architecture changes.

Change page chrome or visual polish

Edit WebViewController.swift / AppDelegate.swift for nav bar behavior, Liquid Glass handling, safe-area behavior, and modal/pushed page chrome.

When To Put Something In iOS Instead Of Rails

Ask the same question as the rest of the native docs:

Is this a product rule or a native container detail?

Put it in iOS when it is a true container concern: scene/window setup, view controllers, the tab bar, iOS-only transitions, glass/safe-area chrome, native UI affordances.

Keep it in RailsFast Base when it is really a route-ownership rule, a tab-policy rule, an onboarding rule, or a billing/pricing policy. Those belong on the server so they can change without an App Store review.

Production Readiness Checklist

Before shipping a downstream iOS app:

• Set a real bundle ID, Apple Team ID, and associated domain.
• Bump version/build with ruby scripts/ios_release_version, commit the regenerated Xcode project, and pull that commit on the signing Mac before archiving.
• Keep RAILSFAST_ASSOCIATED_DOMAIN aligned with the production host.
• Configure Rails AASA app IDs and paths in config/railsfast/railsfast.yml.
• Verify /.well-known/apple-app-site-association over HTTPS with no redirects or HTML.
• Verify the custom scheme still works in development.
• Verify Universal Links on a simulator or real device.
• Test login, logout, onboarding, tabs, pushed pages, modal sheets, and app relaunch.
• Test iOS 18 and iOS 26 if the deployment target spans both visual systems.

Related Docs

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

References

• Apple Info.plist version keys: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
• Apple agvtool versioning reference: https://developer.apple.com/library/archive/qa/qa1827/_index.html
• App Store Connect API builds: https://developer.apple.com/documentation/appstoreconnectapi/builds
• fastlane latest TestFlight build number: https://docs.fastlane.tools/actions/latest_testflight_build_number/
• XcodeGen project spec: https://yonaskolb.github.io/XcodeGen/Docs/ProjectSpec.html