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

Summary

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.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: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.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:And in React: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: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’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 ...