rails-instructions rails-mobile.instructions.md

Hotwire Native Guidelines

Core Concepts

• Hotwire Native displays web content in a native shell with platform-specific navigation
• Web content renders in a WebView with native-feeling transitions and behaviors
• Link navigation is intercepted and handled by the native adapter
• Build once for the web, deploy simultaneously to web and native mobile apps
• Progressively enhance with native components where higher fidelity is needed

Navigation Best Practices

• Design web content to work across web, iOS, and Android
• Links between pages become native screen transitions automatically
• External links open in an in-app browser (SFSafariViewController on iOS, Custom Tabs on Android)
• Use data-turbo-action="replace" to replace the current screen instead of pushing a new one
• Ensure all screens are accessible via URLs for proper native navigation

Path Configuration

• Define platform-specific navigation rules in a JSON configuration file
• Host configuration files at versioned URLs (e.g., /configurations/ios_v1.json)
• Include both local (bundled) and remote (server-hosted) configurations
• Use regex patterns to match URLs and apply specific behaviors
• Configuration example:

{
  "settings": {
    "feature_flags": [
      {
        "name": "enable_new_feature",
        "enabled": true
      }
    ]
  },
  "rules": [
    {
      "patterns": ["/modal/.*"],
      "properties": {
        "context": "modal"
      }
    },
    {
      "patterns": ["/tabs/.*"],
      "properties": {
        "presentation": "refresh"
      }
    }
  ]
}

Bridge Components

• Use Bridge Components for web-to-native communication
• Components have both web (Stimulus) and native (Swift/Kotlin) counterparts
• Register component handlers in your native app and attach web controllers in HTML
• Use for native UI elements like top bar buttons, action sheets, and platform APIs
• Web component implementation example:

// app/javascript/controllers/native_button_controller.js
import { Controller } from "@hotwired/stimulus";
import { BridgeComponent } from "@hotwired/bridge";

export default class extends Controller {
  static values = { title: String, style: String };

  connect() {
    this.bridge = new BridgeComponent("button", this);
    this.bridge.send("connect", {
      title: this.titleValue,
      style: this.styleValue || "default",
    });
  }

  disconnect() {
    this.bridge.send("disconnect");
  }

  handleTap(message) {
    // Handle tap event from native
    const form = this.element.closest("form");
    if (form) form.requestSubmit();
  }
}