How do I keep a web app and its native shells consistent?
Keep the shells thin and let the server decide. Screens, navigation rules and feature gates all come from Rails, so they stay consistent by construction. The only things that should live in mobile/ios and mobile/android are the icon, the purchase sheet and anything the web genuinely cannot do.
The line to hold
| Belongs on the server | Belongs in the shell |
|---|---|
| Every screen and form | App icon and launch screen |
| Navigation rules, served per platform | Native purchase sheet |
| Feature gating and authorization | System browser handoff for OAuth |
| Copy, pricing, everything visible | Device capabilities |
Anything in the left column changes with a deploy. Anything in the right column changes with a build, a submission and a wait, on two platforms separately.
Branch sparingly
hotwire_native_app?
Two or three uses is healthy: the purchase trigger, the subscription management link, maybe a hidden footer. A dozen means you are maintaining two products that happen to share a database, and they will drift.
Design for phone width first
The app is a phone-sized web view, so a screen that only works on a laptop is already broken in the
app. The grid in app/assets/stylesheets/03-layout.css collapses to a flex stack under 900px, and
testing at that width catches most of it before it ever reaches a device.
Two specs worth having
bin/check
spec/design/view_classes_spec.rb fails when a template names a class no stylesheet defines, which
is the silent way a mobile-only layout bug gets introduced. And a request spec asserting the native
branch renders the native purchase trigger is worth writing, because getting that wrong is an App
Store rejection rather than a cosmetic bug.
Re-test the shells after a redesign
The shells do not change, but what they display does. A layout change that looks fine in a browser can break the navigation feel in the app, particularly around modals. Open both shells after any significant visual change, which is a ten minute check, not a test plan.
When drift is worth it
Sometimes a native screen genuinely is better, such as a camera flow. Accept the release cost deliberately for those, and write down why, so the next person does not assume it was an accident and add three more.