Server-Side Rendering with Rails and React

Note for readers

This post got some flack over on r/rails over the use of React with Rails. This is not about whether you should use React with Rails. There’s a time and place for everything, and I think Rails views are great for many use cases. This post is about how to get better integration between Rails and React if you are using them together. Now without further ado…

inertia-rails has been getting a lot of buzz lately. One of its best features is SSR, out of the box. But I don’t want to rewrite my existing app in Inertia.

What if you just want better integration in your existing Rails/React app? I really like React Router (and apparently so do Next.js users…) because it’s fast and just works. Or what about the sane data-fetching patterns of React Query? I don’t want to mix data-loading via props on the server with client-side API requests. I want to keep everything in the same place.

A lot of these pain points can be addressed with SSR. You get initial data on page load, better integration for things like title and meta, and more. Many React libraries support SSR today.

So, how do you add SSR to an existing Rails app?

This is a minimally viable example. It’s only meant to illustrate the concepts.

Architecture

Before diving in, let’s understand what we’re building. For SSR to work, we need two different entrypoints:

• A server entrypoint for initial rendering on the server
• A client entrypoint for hydrating the app on the client

Client Entrypoint

First, we’ll need to handle providers like QueryClientProvider or BrowserRouter differently on the server than on the client.

You’ll need to lift these providers up into a client-specific entrypoint, out of the component with all your routes.

1
export default const App = () => (
2
  // No QueryClientProvider or BrowserRouter here
3
  <Routes>
4
    <Route path="/dashboard" element={<Dashboard />} />
5
  </Routes>
6
);

Then, the client entrypoint:

1
import { hydrateRoot } from "react-dom/client";
2
import { Hydrate, QueryClient, QueryClientProvider } from "react-query";
3
import { BrowserRouter } from "react-router";
4

5
import App from "@/App";
6

7
const queryClient = new QueryClient();
8
const state = window.__INITIAL_STATE__ ?? {};
9

10
hydrateRoot(
11
  document.getElementById("root")!,
12
  <QueryClientProvider client={queryClient}>
13
    <Hydrate state={state}>
14
      <BrowserRouter>
15
        <App />
16
      </BrowserRouter>
17
    </Hydrate>
18
  </QueryClientProvider>
19
);

We hydrate the existing root instead of creating a new one. This helps us avoid an unnecessary re-render. We’ll receive the initial state for React Query via window.__INITIAL_STATE__.

Server Entrypoint

The server entrypoint will be a function because our initial render depends on the URL, plus any initial props. Both path and props will be passed to our SSR server by Rails.

Let’s take a look at our render function:

1
import { renderToString } from "react-dom/server";
2
import { dehydrate, QueryClient, QueryClientProvider } from "react-query";
3
import { StaticRouter } from "react-router";
4
import { ServerStyleSheet } from "styled-components";
5

6
import App from "@/App";
7

8
function render(path = "/", props = {}) {
9
  const sheet = new ServerStyleSheet();
10
  const queryClient = new QueryClient();
11

12
  const { query_data } = props;
13
  query_data.forEach(({ key, data }) => {
14
    queryClient.setQueryData(key, data);
15
  });
16

17
  const app = renderToString(
18
    sheet.collectStyles(
19
      <QueryClientProvider client={queryClient}>
20
        <StaticRouter location={path}>
21
          <App />
22
        </StaticRouter>
23
      </QueryClientProvider>
24
    )
25
  );
26

27
  const styles = sheet.getStyleTags();
28
  const content = [styles, app].join("\n");
29
  const state = dehydrate(queryClient);
30

31
  return { content, state };
32
}
33

34
export { render };

We create a query client so we can set the query data ahead of time. We’ll have some initial data provided by Rails. I’ve structured the query_data as an array of objects with keys and data.

Then we use ServerStyleSheet from styled-components to collect the styles as we generate the HTML string.

window.location won’t be available during SSR, so we use StaticRouter to tell React Router the URL.

ReactDOM.renderToString transforms the JSX to a string.

Putting the Server in Server-Side Rendering

We need a simple HTTP server.

1
import express from "express";
2

3
const app = express();
4

5
app.use(express.json({ limit: "5mb" }));
6

7
app.post("/", async (req, res) => {
8
  const { render } = await import("@/entrypoints/server.tsx");
9

10
  const { path, props } = req.body;
11
  const { content, state } = render(path, props);
12

13
  res.json({ content, state });
14
});
15

16
app.use((e, req, res, next) => {
17
  res.status(500).send([e.message, e.stack].join("\n"));
18
});
19

20
app.listen(3001);

We set up an Express app and configure it with high limits for JSON payloads to accommodate larger initial query data. The root endpoint returns whatever our render function produces.

Putting it on Rails

Now let’s connect everything to Rails via the Ssr service:

1
class Ssr
2
  class << self
3

4
    SSR_TIMEOUT = 3
5
    SSR_SERVER_URL = "http://localhost:3001/"
6

7
    def call(path, props)
8
      uri = URI.parse(SSR_SERVER_URL)
9

10
      http = Net::HTTP.new(uri.host, uri.port)
11
      http.open_timeout = SSR_TIMEOUT
12
      http.read_timeout = SSR_TIMEOUT
13

14
      request = Net::HTTP::Post.new(uri.path, "Content-Type" => "application/json")
15
      request.body = { path:, props: }.to_json
16

17
      response = http.request(request)
18
      JSON.parse(response.body).with_indifferent_access
19
    rescue => e
20
      { content: "", state: "" }
21
    end
22
  end
23
end

This service makes a POST request to our Express server with the path and props, then returns the response as a hash.

Controllers

Our SsrController handles common logic for initializing @props and triggering SSR.

1
class SsrController < ApplicationController
2
  before_action :initialize_query_data
3

4
  private
5

6
  def initialize_query_data
7
    @props = { query_data: [] }
8
  end
9

10
  def default_render
11
    @ssr = Ssr.call(request.path, @props)
12
    render "ssr/index"
13
  end
14
end

For each set of routes that need to provide additional data to React, we can create a controller that inherits from SsrController.

Actions append the data they need to @props[:query_data]:

1
class DashboardController < SsrController
2
  def index
3
    @props[:query_data] << {
4
      key: %w[posts recent],
5
      data: PostSerializer.many(current_user.posts),
6
    }
7
  end
8
end

Here, the index action in DashboardController adds the current user’s posts to @props[:query_data], which will be available to React Query in our render function.

Views

We have a basic layout that includes meta tags and stylesheets, and a React-specific template that handles the SSR content.

The application layout should look familiar. We still use Vite’s helpers.

1
<!DOCTYPE html>
2
<html lang="en">
3
  <head>
4
    <title>App</title>
5

6
    <%= favicon_link_tag vite_asset_path 'images/favicon.ico' %>
7
    <%= vite_stylesheet_tag 'application' %>
8

9
    <%= csrf_meta_tags %>
10
    <%= csp_meta_tag %>
11

12
    <%= yield :head %>
13

14
    <%= vite_typescript_tag 'client.tsx', defer: true %>
15
  </head>
16

17
  <body>
18
    <%= yield %>
19
  </body>
20
</html>

The ssr/index template is where the magic happens.

1
<div id="root">
2
  <%= sanitize @ssr[:content], scrubber: SsrScrubber.new %>
3
</div>
4

5
<script>
6
  window.__INITIAL_STATE__ = <%= raw j(@ssr[:state].to_json) %>;
7
</script>

We sanitize with a custom scrubber and use raw(j(...)) to avoid XSS attacks.

Building and Running

You’ll need to build the server before running it.

1
bin/vite build --ssr    # Build the server
2
bin/vite ssr            # Run it!

To build the SSR server automatically during rails assets:precompile, you can enable the ssrBuildEnabled option in your Vite Ruby configuration. Add the following to your config/vite.json:

1
{
2
  "all": {
3
    "sourceCodeDir": "app/frontend",
4
    "watchAdditionalPaths": [],
5
    "ssrBuildEnabled": true, // <--- Add this
6
  },
7
}

If you’re using a Procfile, you’ll need to add the following:

1
web: bundle exec puma -C config/puma.rb
2
ssr: bin/vite ssr
3
worker: bundle exec sidekiq

There You Have It

Server-side rendering might seem complicated, but I think it’s worth doing for better integration with React. We can enjoy the productivity of Rails while still delivering the performance benefits of modern frontends.

universal_renderer gem

After building this into our own Rails app, I realized it was a lot of boilerplate. I decided to move the code into a gem called universal_renderer.

It integrates server-side rendering into Rails and works seamlessly with the universal-renderer NPM package.

It has controller helpers for passing props, view helpers for integrating into your templates, automatic fallback to client-side rendering if SSR fails, and streaming responses for fast TTFB (especially with Bun).

It’s a work in progress, and I’d love to hear from you if you have ideas for contributions.

Reach me at me@thaske.com or @thaske_ on X.

Thanks for reading!