DEV Community: Naofumi Kagami

Integrating Ruby on Rails with Modern SPAs

Naofumi Kagami — Tue, 22 Apr 2025 12:52:53 +0000

TL;DR;

Integrating React onto a Ruby on Rails application is unnecessarily challenging. We have to install jsbundling-rails, multiple packages, configure propshaft, create an ERB endpoint, etc.

Why can't we just run rails new, install a single gem, and instantly have a state-of-the-art React setup with client-side routing, code-splitting, and effective data-loading patterns built-in?

This article introduces the react_router_rails_spa gem, which integrates a React Router SPA framework application into your existing Ruby on Rails project. With just a few commands, you will have a fully functioning scaffold on which to build your React app.

To jump to the installation steps, go to the "Using the gem" section.

Who is this for?

If any of the following describes yourself, then this gem might be for you.

You want to create an SPA with a React frontend and a Rails backend.

You want a simple setup that is "omakase". You don't want to install packages and configure them on the React side. On the Rails side, you don't want to manually add routes and controllers. Everything should be a single gem and a single command.
You want something that is easy to deploy, and cost-effective. You don't want to pay for an extra server that you don't strictly need.
You don't need SEO for the React pages.
If SEO is necessary, you can just serve ERB pages or static HTML files.

You tried Next.js, but you did not really need SSR nor RSCs. You were only interested in Next.js because you thought it was easy.

You're only using Next.js because you thought it was "omakase" and simple to set up.
After a while, you've found that integrating the Next.js server and the Rails server is harder than you bargained for. You've had headaches around authentication schemes, cross-domains, subdomains, CORS settings, samesite cookies, CSRF mitigation, and reverse proxies, etc. You've realized that running separate frontend and backend servers is hard.
You are not happy with the extra money you have to pay to Next.js.

The react_router_rails_spa gem gives you the simplicity of an opinionated SPA framework, without the complexity of a mulit-server setup.

You want to use cutting-edge React

You want to use cutting-edge React capabilities like code-splitting, loader-based data fetching and more, but you're not sure how to set this up from scratch.
You don't want to create a slow, bloated, legacy React app.

Who is this NOT for?

You want to embed some React components on top of your ERB-rendered pages

This is how React was originally used. React was built for this, and it's generally much simpler to set up than a multi-page SPA.

The current gem does not help you with this however since it is designed for SPA frameworks. If you wish to take this approach, you can build your own system or use Gems like react-rails and turbo-mount. Turbo Mount uses Stimulus to mount components, and is more robust if you are using Hotwire in your ERB views.

How does this compare to [...]?

Compared to gems like React on Rails or Intertia Rails, the current gem is just an installer and does virtually nothing to modify or add features to React Router. This is a great advantage and ensures that frontend developers will feel right at home.

It also means that you can easily understand how it works. You can customize accordingly.

Background

On February 14th, 2025, the React team published a blog post
titled Sunsetting Create React App. They strongly recommended that developers should now use an SPA framework instead.

Importantly, and often lost in the public discourse, they were NOT recommending an SSR framework. Instead, they were advocating for creating SPAs with SPA frameworks that could be deployed on a CDN, a static hosting service, or the public folder of a Ruby on Rails application.

In the following, we will call SPAs built with an SPA framework, "Modern React SPAs" to highlight that this is the current officially recommended approach. To contrast, we will call the ones that the React team is actively discouraging, "Legacy React SPAs".

"I have no interest nor use for SSR! I don't need SEO. An SPA is all that I need.

Instead of Create React App, I'll just use Vite!"

This was the most common response to the blog post. However IMO, it misses the point that the authors were repeatedly trying to make.

The React team is strongly recommending that even if you only need an SPA, you should be creating a Modern SPA. They carefully go through some of the features like code-splitting and loader-based routing that you will need to add if you are building a state-of-the-art React SPA from scratch.

These features are often challenging and require expertise to correctly implement, but are essential for modern React applications.

Without these features, your React SPA is a Legacy SPA. It will suffer from the same performance issues that plagued old SPAs a decade ago – namely huge initial bundle size, data-fetch waterfalls, flickering, and very slow load times.

In the above article, the React team went out of its way to tell us that we should not simply replace the deprecated Create React App with a newer but nonetheless still architecturally Legacy SPA. Instead, they strongly urge us to embrace Modern React SPAs and avoid these issues.

We should note that Vite is essentially a bundler and a development server, with a plugin system that allows us to easily install various packages. Although extremely useful, it is agnostic to the Legacy vs. Modern SPA debate. You can build a Legacy SPA using Vite, and you can also create a Modern SPA. Vite does not care either way, and the installer command npm create vite@latest gives you templates for both.

"I want to integrate my React app with a Ruby on Rails backend. I'll just add a javascript_include_tag to my bootstrap ERB template. That will load React just fine!"

This is also a common response from people who prefer a no-fuss solution for Rails. However, note that this is exactly the approach that the React team strongly discourages. The above solution is a Legacy SPA and will suffer from the same legacy issues.

Instead, the React team is recommending that you integrate a Modern SPA framework using ...

Well, actually, they don't have a concrete recommendation yet for Rails. As far as we know, nothing currently exists to easily integrate a Modern SPA with Rails.

We hope to address this with this react_router_rails_spa gem.

Why we need a different approach for Rails integration

Historically, the way to integrate React with Ruby on Rails was to create an ERB endpoint that served as the initial HTML
(the bootstrap HTML) for React. This ERB template would have either a javascript_include_tag (jsbundling-rails) or a javascript_pack_tag (webpacker) to load the React application build artifact. Newer gems like Vite Rails have also adopted the same approach.

However, this is exactly what the React team is discouraging, and it seems unwise to continue down this path.

The problem is that Modern SPAs build their own bootstrap HTML templates with SSG (the first HTML that the browser loads).
Modern SPA frameworks are not just JavaScript and instead, the bootstrap HTML and the JavaScript are tightly integrated.

Therefore, to take advantage of Modern SPA features, Rails has to give up on generating its own bootstrap HTML from an ERB template with an embedded javascript_include_tag. A better approach is to take the bootstrap HTML generated by the SPA framework, and wrap Rails integration around this.

This is how the react_router_rails_spa gem works.

Outline of how the gem works

It is important to note that the react_router_rails_spa gem is nothing more than a stock React Router installation with some custom configuration, paired with the generation of a single Rails controller.

There is very little custom code, and this is actually a huge advantage. This is a very thin wrapper around the official React Router installer and resilient against future changes. If you wish, you can easily update and customise your NPM packages independently of this gem. The generated code is also heavily commented
to help you understand the internals for yourself.

React Router SPA framework mode

We install and use React Router in SPA framework mode, configured to generate an SPA build.
It is a true SPA and will build static files that can be served from any static hosting provider. These are transferred to the public folder in Rails for deployment.

The command for building the react application is integrated into the rake assets:precompile command. Therefore, you do not need any additional configuration in your CI/CD scripts.

Integration with Ruby on Rails through cookies

Previously, you would integrate Ruby on Rails using a bootstrap HTML template generated by Rails using ERB templates. This allowed you, for example, to embed CSRF-mitigation token tags. As mentioned above, this is incompatible with Modern SPA frameworks.

Otherwise, you could build your SPA independently of Rails and send extra requests from the browser to retrieve the CSRF token and other integration information. This requires otherwise unnecessary network requests.

Neither approach is ideal.

Instead, the react_router_rails_spa gem sends Rails-generated cookies and/or headers alongside the SPA framework-generated bootstrap HTML file. It give you the best of both worlds.

For example, the ReactRouterRailsSpa::CsrfCookieEnabled module
sends session-specific CSRF tokens via cookies to integrate Rails'
CSRF protection with React. The SPA framework-generated HTML is untouched.

Rake files for automation

We provide rake tasks for starting up the development server and building the React Router application.

Note that the build task is attached to the assets:precompile task.
This means that you do not need to add extra configuration to your CI/CD scripts to build the React Router app since it should normally call this task already.

If your CI/CD already installs Node (which is required for building), then you probably won't have to touch your CI/CD scripts at all.

Additional React Router and Vite Configuration

We currently serve the React application from the /react/* paths. All other paths are handled by Rails. The current gem configures this for you. If you want a different setup, you can change the configurations.

Demo and Source code

We have a demo application running on Kamal on a VPS server. It has simple, session-based authentication and basic CRUD. Mutations are secured by integration with Rails CSRF protection.
In the demo application, we have intentionally added a 0.5 to 1.5-second random delay on all server requests. Even the most bloated and inefficient web technologies will look great on a high-performance device with a fast network. Unless your demo intentionally simulates non-ideal situations, it is meaningless.
The source-code for this demo application is available on GitHub.

The source code is heavily commented. We recommend that you read through it to understand the setup in more detail.

Using the gem

Install Ruby on Rails

This gem works with a pre-existing installation of Rails. Create a new Rails application if you haven't already.

rails new [project name]

Note that this gem works even with a no-build Rails setup (which is the Rails default). However, you will need Node.js in your CI/CD for deployment. If you are unsure how to do this, we recommend that you generate a new Rails application with jsbundling-rails pre-installed by using the following installation command.
This will create a ready-made Dockerfile that installs Node.js.
(This gem won't use esbuild. We're only doing this for Node.js.)

rails new [project name] --javascript esbuild

Install the `react_router_rails_spa` gem

Add the following line to your Gemfile.

gem "react_router_rails_spa"

Install the gem

bundle install

We recommend committing your changes at this point before the following generator adds and modifies your files.

Run the generator

bin/rails generate react_router_rails_spa:install

This will install the latest version of React Router and generate the routes and all the necessary files and configurations.

Run the development server

Run the following command to start the frontend development server with HMR (Hot Module Replacement).

bin/rails react_router:dev

Point your browser to http://localhost:5173/react/ to see the welcome page.

Note that the frontend development server will not truly represent
how the React application and Rails server interact in production. In particular, features that require integration like linking between the React and Rails app may not work. It is important to test with the following preview command before deploying.

Preview and build the React Router application

Run the following command to build the React Router application
and store the static files into the Rails public directory.

bin/rails react_router:build

This command is also aliased as:

bin/rails react_router:preview

Start your Rails application if it is not already running and point your browser to http://localhost:3000/react/ to see the welcome page.

Read the code

We have added numerous comments to the code generated by this gem. Please read it to understand how the integration works.

Rails View Helpers for Components

Naofumi Kagami — Mon, 23 Dec 2024 01:00:32 +0000

This post is intended to gather feedback on a proposal for a new feature for Rails, while I put together a pull request. I welcome any comments, either here or on X or BlueSky

TL:DR

I want to propose an extension to Ruby on Rails TagHelpers which will enable us to create HTML structures that were cumbersome before.

In short, the view helper code to write this,

<figure>
  <img src="/path/to/image.jpg" alt="Alternate Text" />
  <figcaption>Figure Caption</figcaption>
</figure>

could look like this (with my extension proposal),

def figure(src, alt:, figcaption: nil)
  tag.figure do |b|
    b << tag.img(src:, alt:)
    b << tag.figcaption(figcaption) if figcaption.present?
  end
end

instead of this (how we would currently write this with view helpers),

def figure(src, alt:, figcaption: nil)
  figure_content = tag.img(src:, alt:)
  figure_content += tag.figcaption(figcaption) if figcaption.present?
  tag.figure do
    figure_content
  end
end

The proposed approach allows us to write more complex HTML with tag helpers alone (without ERb), using code that closely mirrors the HTML structure. This will simplify the creation of UI components.

Note: The HTML and view helper code snippets above come from Garrett Dimon's blog post.

Credit to Garrett Dimon and Adam McCrea

Garrett Dimon wrote an excellent post "Structure Your ERb and Partials for more Maintainable Front-end Code in Rails" where he discusses alternative approaches to using view helpers and partials, together with points to consider when choosing between the two.

Adam McCrea wrote a post in response, "Say No To Partials And Helpers For A Maintainable Rails Front-End", proposing "throwing out ERB partials and helpers altogether, and using Phlex instead".

Although I fully agree that Phlex is fantastic and a breath of fresh air, I hope my proposal addresses at least one of Adam's major complaints and will allow us to positively re-evaluate traditional Rails ERb and view helpers.

In short, I don't want to throw the baby out with the bathwater.😀

Let's first look at ViewComponents and Phlex

Before diving into the details of what I am proposing, let's first look at how you would write the HTML above using ViewComponents and Phlex.

I hope this illustrates my point, which can be summarised as "Why do we need to write a new class for just 4 lines of HTML?".

I think there is a better way.

ViewComponents

figure_component.rb

class FigureComponent < ViewComponent::Base
  def initialize(src, alt:, figcaption: nil)
    @src = src
    @alt = alt
    @figcaption = figcaption
  end
end

figure_component.html.erb

<figure>
  <img src="<%= @src %>" alt="<%= @alt %>" />
  <% if @figcaption.present? %>
    <figcaption><%= @figcaption %></figcaption>
  <% end %>
</figure>

Phlex

class Components::Figure < Components::Base
  def initialize(src, alt:, figcaption: nil)
    @src = src
    @alt = alt
    @figcaption = figcaption
  end

  def view_template
    figure do
      img(src: @src, alt: @alt)
      figcaption { @figcaption } if @figcaption
    end
  end
end

This proposal

def figure(src, alt:, figcaption: nil)
  tag.figure do |b|
    b << tag.img(src:, alt:)
    b << tag.figcaption(figcaption) if figcaption.present?
  end
end

The need for a simpler approach

Both ViewComponent and Phlex are class based and are great for components that need to encapsulate logic.

However, with the rise of Tailwind CSS, we are encouraged to write a lot of smaller components whose only purpose is to DRY our code and save us from writing a ton of CSS classes – they have very little internal logic. In these cases, ViewComponents and Phlex can be an overkill.

In many cases, traditional view helpers included in Rails are sufficient for this. For the following HTML for example, you can write a very easy-to-understand helper that mirrors the HTML structure like this.

HTML

<figure>
  <img src="/path/to/image.jpg" alt="Alternate Text" />
</figure>

view helper

def figure(src, alt:)
  tag.figure do
    tag.img(src:, alt:)
  end
end

However, this breaks down when the <figure> element has more than one child.

For the following HTML where <figure> has two children, you could either write a hard-to-read view helper, or more often, you would use ERb.

Although I fully appreciate that ERb is better than view helpers for rendering highly complex HTML, I find it hard to accept the idea that simply increasing the number of children from one to two makes the HTML substantially more complex. I am uncomfortable with the thought that this alone should compel us to use ERb instead of view helpers.

HTML

<figure>
  <img src="/path/to/image.jpg" alt="Alternate Text" />
  <figcaption>Figure Caption</figcaption>
</figure>

view helper (hard-to-read)

def figure(src, alt:, figcaption: nil)
  figure_content = tag.img(src:, alt:)
  figure_content += tag.figcaption(figcaption) if figcaption.present?
  tag.figure do
    figure_content
  end
end

ERb (you would often use this instead of the above view helper)

<figure>
  <img src="<%= src %>" alt="<%= alt %>" />
  <% if figcaption.present? %>
    <figcaption><%= figcaption %></figcaption>
  <% end %>
</figure>

Given this situation, I propose an idea to make it easier to write HTML elements with more than one child in view helpers, by adding a feature to tag helpers.

Why don't tag helpers work when there is more than one child?

If we write the following code in a view helper, we lose the <img> tag and only get the <figcaption>.

This is because the return value of the do block is used as the content for the <figure> tag. Since tag.figcaption is the last expression in the block, this value becomes the content. The tag.img is lost because its value is not captured anywhere.

view helper

def figure(src, alt:, figcaption: nil)
  tag.figure do
    tag.img(src:, alt:)
    tag.figcaption(figcaption) if figcaption.present?
  end
end

HTML

<figure>
  <figcaption>Figure Caption</figcaption>
</figure>

Proposed solution

I propose the following syntax. We extend tag helpers to optionally provide a variable (in this case b for "buffer") to the block. We push the tag.img and tag.figcaption to this buffer (b), which is implemented as an Array. After the tag helper yields the block, it performs a safe_join on the buffer resulting in HTML that includes both child elements, and will be used as content for the <figure> tag.

def figure(src, alt:, figcaption: nil)
  tag.figure do |b|
    b << tag.img(src:, alt:)
    b << tag.figcaption(figcaption) if figcaption.present?
  end
end

The code that this enables closely aligns with the structure of the HTML and is easy to compare. Even people with minimal understanding of Ruby should be able to understand what is happening.

Benefits

Through this proposed feature, developers who are hesitant to use ViewComponents or Phlex can better benefit from components while sticking to traditional ERb and view helpers.

It also promotes writing components using functions (view helpers), in a way that is easy for non-Ruby developers (i.e. designers) to understand. Note that modern React components are also functions, not classes.

This feature enables us to implement slightly more complex components in view helpers without resorting to ERb templates. Compared to ERb, the benefits are the ability to fit multiple components in a single file, an explicit interface, a simpler API for calling (you don't need to write render "[path to partial]", [hash of locals] which can become verbose), and performance.

What about unit testing?

One of the commonly mentioned benefits of using ViewComponents or Phlex instead of ERb and view helpers, is the ability to unit test components.

I do not know where this idea originated from, but I do know that the Rails Guides has sections for unit testing ERb partials and for unit testing view helpers.

I have been unit testing ERb partials and HTML-generating view helpers for several years.

Implementation

Although I have been using a variation of this technique for many years, I am proposing to add this to Rails to make it more convenient and to increase awareness of the safe_join technique.

I am currently preparing an implementation and a pull request. In the meantime, if you have any comments or opinions, I would love to hear them!

DEV Community: Naofumi Kagami

Integrating Ruby on Rails with Modern SPAs

TL;DR;

Who is this for?

You want to create an SPA with a React frontend and a Rails backend.

You tried Next.js, but you did not really need SSR nor RSCs. You were only interested in Next.js because you thought it was easy.

You want to use cutting-edge React

Who is this NOT for?

You want to embed some React components on top of your ERB-rendered pages

How does this compare to [...]?

Background

Why we need a different approach for Rails integration

Outline of how the gem works

React Router SPA framework mode

Integration with Ruby on Rails through cookies

Rake files for automation

Additional React Router and Vite Configuration

Demo and Source code

Using the gem

Install Ruby on Rails

Install the react_router_rails_spa gem

Run the development server

Preview and build the React Router application

Read the code

Rails View Helpers for Components

TL:DR

Credit to Garrett Dimon and Adam McCrea

Let's first look at ViewComponents and Phlex

ViewComponents

Phlex

This proposal

The need for a simpler approach

Why don't tag helpers work when there is more than one child?

Proposed solution

Benefits

What about unit testing?

Implementation

Install the `react_router_rails_spa` gem