Building a framework-agnostic Ruby gem (and making sure it doesn't break)

On building a framework-agnostic Ruby gem (and making sure it doesn’t break)

What I learned supporting ERB, React, and Vue from a single Ruby gem. And how I keep it from breaking with automated iOS tests.

Ruby Native needs to work with ERB, React, and Vue. That’s three frameworks, three sets of conventions, and three ways developers expect an API to feel. And every new feature needs to ship across all of them without breaking the others.

This week I added a native navbar, and it was the first real test of whether this approach scales. Here’s what I’ve learned about keeping an API clean across frameworks, and how I’m catching regressions.

It’s HTML all the way down

When I started Ruby Native, it was ERB-only. The tab bar, push notifications, and forms all used the same pattern: render a hidden HTML element with data-native-* attributes. The native app detects these “signal elements” via a MutationObserver and translates them into real native UI.

For example, the native navbar is just this:

<div data-native-navbar="Account" hidden>
<div data-native-button data-native-icon="ellipsis.circle">
<div data-native-menu-item data-native-title="Edit profile"
data-native-href="/account/edit" data-native-icon="pencil">
</div>
<div data-native-menu-item data-native-title="Sign out"
data-native-click="#sign-out" data-native-icon="rectangle.portrait">
</div>
</div>
</div>

Hidden divs, that’s it! The native app doesn’t know what generated them. It just reads the DOM.

This turned out to be the most important decision in the entire project. Because when it came time to support React and Vue, I didn’t have to change anything on the native side. I just needed new ways to produce the same HTML.

Each framework’s API should feel good

ERB developers expect blocks and builders. React developers expect components and props. If you force one framework’s patterns onto another, the API feels wrong even if it works.

Here’s the same navbar in ERB:

<%= native_navbar_tag "Account" do |navbar| %>
<% navbar.button icon: "ellipsis.circle" do |menu| %>
<% menu.item "Edit profile", href: "/account/edit", icon: "pencil" %>
<% menu.item "Sign out", click: "#sign-out", icon: "rectangle.portrait" %>
<% end %>
<% end %>

And in React:

import { NativeNavbar, NativeButton, NativeMenuItem } from "ruby_native/react"
<NativeNavbar title="Account">
<NativeButton icon="ellipsis.circle">
<NativeMenuItem title="Edit profile" href="/account/edit" icon="pencil" />
<NativeMenuItem title="Sign out" click="#sign-out" icon="rectangle.portrait" />
</NativeButton>
</NativeNavbar>

Different syntax. Same output. The ERB version uses Ruby’s block pattern with a builder that yields menu items. The React version uses component composition with props. Both feel right in their own context.

The React components themselves are intentionally thin. Here’s NativeButton:

export function NativeButton({ position = "trailing", icon, title, href, click, selected, children }) {
const props = { "data-native-button": true }
if (icon) props["data-native-icon"] = icon
if (title) props["data-native-title"] = title
if (href) props["data-native-href"] = href
if (click) props["data-native-click"] = click
if (position) props["data-native-position"] = position
if (selected) props["data-native-selected"] = ""
return createElement("div", props, children)
}

No state or effects, just a function that turns props into data attributes. The less framework-specific logic lives in these components, the less can go wrong.

I don’t use Inertia day-to-day, and it shows!

I’m a Rails and ERB developer. I don’t reach for React or Vue on my own projects. When I built the Inertia support, I leaned heavily on early Ruby Native adopters who use Inertia every day. They told me when something felt off, when a prop name was confusing, or when a pattern didn’t match how they structure their apps.

This is something I think library authors underestimate. You can read the docs and follow the conventions, but there’s a feel to a framework that only comes from daily use. Having people who live in that framework test your API is the difference between “technically works” and “feels right.”

Three frameworks from one test bundle

Supporting multiple frameworks creates a real regression problem. A change to the JavaScript bridge could break React but not ERB. A new signal element might work in Hotwire but lead to a race condition in Inertia. And I don’t want to manually check every combination on every change.

So I set up XCUITest tests for each of the three demo apps: Beervana (Hotwire/ERB), Coffee (React/Inertia), and Habits (Vue/Inertia). Each test suite boots the real Rails server and exercises the actual native UI.

The tests don’t assert on HTML or JavaScript. They assert on what the user sees:

• Does the tab bar appear after sign-in?
• Does the navbar title update when I switch tabs?
• Does the menu button open with the right items?

Both tests are framework-agnostic. They have no idea what’s rendering the HTML. They just verify the native UI works. If I break something in the JavaScript bridge, these tests catch it regardless of which framework exposed the problem.

And then someone asked about Sinatra…

I haven’t tried it yet, but someone recently asked if Ruby Native works outside of Rails. With Sinatra, for example. And the honest answer is: it should. The signal elements are just HTML. The native app reads the DOM. There’s nothing Rails-specific about the data attributes themselves.

The Ruby gem’s helpers are Rails-specific, sure. But the React and Vue components aren’t. And you could render the raw HTML from any templating language.

That question made me realize the early decision to build on data attributes rather than framework hooks is paying off in ways I didn’t plan for. It’s one more framework to think about. But the fact that it’s even plausible tells me the abstraction is at the right layer.