ruby-native

ruby_native

Ruby Native turns a Rails app into iOS and Android apps. This gem is the Rails-side integration: view helpers, a YAML config file, endpoints auto-mounted at /native, and a CLI for previewing and deploying builds. Full docs, including the complete helper reference and config schema, live at rubynative.com/docs.

Installation

gem "ruby_native"

The engine auto-mounts at /native. No route configuration needed.

Getting started

Run the install generator:

rails generate ruby_native:install

This creates config/ruby_native.yml with tabs taken from your routes. If you use a coding agent, hand it the rest here:

bundle exec ruby_native mcp install

Then say: set up Ruby Native in this app. It wires the layout, checks its own work, and later drafts the listing, captures screenshots, and submits for review, stopping only for the few clicks Apple keeps for a person. By hand, the same steps are:

1. Edit the config with your colors and tabs (see below).

2. Add the stylesheet and viewport-fit=cover to your layout <head>:

   <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
   <%= stylesheet_link_tag :ruby_native %>
   

   viewport-fit=cover is required for CSS env(safe-area-inset-*) variables to resolve to real values instead of 0.

3. Add the tab bar to your layout <body>:

   <%= native_tabs_tag %>
   

4. Preview it on your phone (see below).

The full walkthrough, including safe area layout and hiding web-only navigation with native_app?, is at rubynative.com/docs/setup.

Configuration

config/ruby_native.yml controls the native shell:

appearance:
  tint_color: "#007AFF"
  background_color: "#FFFFFF"

tabs:
  - title: Home
    path: /
    icon: house
  - title: Profile
    path: /profile
    icon: person

Changes are picked up without restarting the server in development. See rubynative.com/docs for the full schema: appearance and dark mode, navbar branding, Advanced Mode, OAuth, and linked domains.

Preview

Preview your app on a real device without deploying:

bundle exec ruby_native preview

This starts a Cloudflare tunnel and shows a QR code for the Ruby Native app to scan. Your Rails server needs to be running separately. Requires cloudflared:

brew install cloudflare/cloudflare/cloudflared

The tunnel points at port 3000, or at PORT when it is set, the same way rails server picks its port. Pass --port 4000 to override, or --url for an upstream that isn't on localhost.

See rubynative.com/docs/cli for deploy, login, and auto-deploying from CI.

React and Vue

Building with Inertia instead of ERB? @ruby-native/react and @ruby-native/vue provide the same helpers as npm packages, versioned alongside this gem. See rubynative.com/docs/inertia for setup.

AI agents

Every docs page serves markdown: append .md to the URL or request Accept: text/markdown. For an index of everything, fetch rubynative.com/llms.txt, or llms-full.txt for the complete docs as a single file.

MCP server

Docs tell an agent what to write. They don't tell it whether what it wrote works, and Ruby Native's signals fail silently on purpose: an app that doesn't recognize a data-native-* attribute ignores it. A typo renders nothing, raises nothing, and logs nothing, so it survives right up until someone opens the build and notices the missing button.

ruby_native mcp closes that loop. It speaks MCP over stdin and stdout. Three tools answer from your working copy, with no account involved:

Tool	Answers
check_views	Which signals in your templates are misspelled, duplicated, or newer than the installed gem
lookup_signals	Every data-native-* attribute, the gem version it needs, and the helper that emits it
validate_config	What in config/ruby_native.yml the apps reject outright, and what they quietly ignore

Four more read your account, using the token ruby_native login already stored:

Tool	Answers
status	Where the app is on the way to the App Store, and what is in the way, with who clears each thing
config_errors	What real devices reported failing over the last 48 hours, with the decode error behind each one
deployed_builds	The build your users can actually install, and which signals it's too old to understand
build_status	Whether one build succeeded, and the error if it didn't

The pairs are the point. validate_config says what will fail to decode; config_errors says what did, on which devices. check_views compares your templates against the gem in your Gemfile; deployed_builds compares them against the binary in the store, which is usually the answer to "the attribute is right but nothing happens on my phone".

Full reference at rubynative.com/docs/cli. Register it in the project's .mcp.json, which Claude Code reads:

bundle exec ruby_native mcp install

Then say: set up Ruby Native in this app.

Installed as the Claude Code plugin (claude plugin marketplace add ruby-native/gem, then claude plugin install ruby-native@ruby-native), the server is the same command. The plugin asks for an optional Ruby Native token; leave it blank and the account tools use the login ruby_native login stored on this machine.

Or, in a client that takes JSON:

{
  "mcpServers": {
    "ruby-native": {
      "command": "bundle",
      "args": ["exec", "ruby_native", "mcp"]
    }
  }
}

The rest stage things with Ruby Native and reach Apple only on a build or a click on the dashboard: permissions_set, testers_add, icon_set, screenshots_setup, screenshots_capture, listing_push, listing_pull, and demo_account_set, each the same as its CLI command. submit is the one tool that reaches Apple on its own: it takes two calls with a token in between, so the agent has to show you what is going before it can send it, and withdraw takes it back out of the queue until Apple approves. The first three tools never leave your machine; the rest send your CLI token to rubynative.com. check_views needs the herb gem, same as ruby_native check.

License

MIT.