Bridge Components for Hotwire Native apps

by Joe Masilotti, the Hotwire Native guy

Hotwire Native enables seamless communication between native Swift and Kotlin code and web views in hybrid mobile apps. Bridge components extend this functionality by providing reusable native components that interact your web views. They enable developers to break out of the web view container and drive native features.

This repository contains generalized, production-ready bridge components extracted from real-world client projects. Once installed, each component can be added to any page of your app and customized with a bit of HTML.

Components

See all the components

• Alert
• Barcode Scanner
• Biometrics Lock
• Button
• Document Scanner
• Form
• Haptic
• Location
• Menu
• NFC
• Notification Token
• Permissions
• Review Prompt
• Search
• Share
• Theme
• Toast

Requirements

• Hotwire Native Bridge
• Hotwire Native iOS v1.2 or later
• Android
  • Hotwire Native Android v1.2 or later
  • Kotlin v2.2.0

Check the examples/ directory for demo iOS, Android, and Rails apps.

Installation

Each component requires a Stimulus controller and a Swift/Kotlin component.

Web - Stimulus controllers

1. Install the bridge-components package

Add the bridge-components module via yarn:

yarn add @joemasilotti/bridge-components

or npm:

npm install @joemasilotti/bridge-components

or with Rails importmaps:

bin/importmap pin @joemasilotti/bridge-components

2. Register the Stimulus controllers

Register the Stimulus controllers after starting your Stimulus application:

import { Application } from "@hotwired/stimulus"
import { controllers } from "@joemasilotti/bridge-components"

const application = Application.start()
application.load(controllers)

iOS - Swift components

1. Add the Swift package dependency

In Xcode, select File → Add Packages Dependencies… and enter https://github.com/joemasilotti/bridge-components in the search field. Make sure your project is set under "Add to Project" and click Add Package. Then click Add Package again.

2. Register the native components

Import the framework and register all the available components in AppDelegate.swift:

import BridgeComponents // THIS LINE
import HotwireNative
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Hotwire.registerBridgeComponents(Bridgework.coreComponents) // THIS LINE
        return true
    }
}

Android - Kotlin components

1. Add the JitPack repository to your build file

In Android Studio, add the following line to settings.gradle.kts:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") } // THIS LINE
    }
}

2. Add the dependency

Add the following line to the bottom of build.gradle.kts (Module :app), replacing <latest-version> with the latest release:

dependencies {
    // ...

    implementation("dev.hotwire:core:<hotwire-native-version>")
    implementation("dev.hotwire:navigation-fragments:<hotwire-native-version>")

    implementation("com.github.joemasilotti:bridge-components:<latest-verison>") // THIS LINE
}

3. Register the native components

In your Application() subclass add the following:

package com.your.package.name

import android.app.Application
import com.masilotti.bridgecomponents.shared.Bridgework // THIS LINE
import dev.hotwire.core.bridge.KotlinXJsonConverter // THIS LINE
import dev.hotwire.core.config.Hotwire
import dev.hotwire.navigation.config.registerBridgeComponents // THIS LINE

class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Hotwire.config.jsonConverter = KotlinXJsonConverter() // THIS LINE
        Hotwire.registerBridgeComponents(*Bridgework.coreComponents) // THIS LINE
    }
}

Usage

Once installed, use a component by adding a data-controller attribute that matches the name of the Stimulus controller.

For example, to use the Button Component:

<a href="#" data-controller="bridge--button">Button</a>

Each component can then be configured further. Check the docs/components/ directory for more information.

JavaScript events

A few controllers fire custom JavaScript events prefixed with the bridge-- namespace. You can listen for these to perform custom handling when:

• A search query is executed
• A notification token is retrieved
• A location is retrieved
• A barcode is scanned

Need help?

If you need help installing, configuring, or using the components, feel free to open a new discussion or send me an email. I'd love to help!