Converting Existing Ruby on Rails Sites

Here we describe the steps required to install Next.js into an existing Ruby on Rails site. We assume that the Ruby on Rails site is running Rails 7, but the knowledge should be easily transferable to other versions. We also assume that the Rails project is running inside Docker.

Copy then nextjs folder to your new project

The Next.js installation for this demo project is derived from the With Docker example and tweaked to run in development mode. The easiest way to install this into your project is to simply copy the entire folder into your project root directory.

Modifying your Rails installation

.gitignore settings

Update your .gitignore file in your project root directory so that unnecessary files inside the nextjs directory will not be checked-in to your Git repository. See the .gitignore file in the demo project to understand what entries should be added.

Add a CSRF Token endpoint

Add a CSRF token endpoint to a controller that does not require authentication. Rails will require CSRF tokens even before login so make sure that authentication is not necessary to get the tokens.

An example is shown below. The form_authenticity_token is all that you need to get the token.

  def csrf
    render json: { authenticity_token: form_authenticity_token }
  end

Edit the CsrfToken component nextjs/components/csrf_token.js to send requests to the above endpoint.

Switch off Hotwire/Turbo if necessary

Go to app/javascript/application.js and turn off Turbo if necessary. You may need to export the Turbo object as below.

import { Turbo } from '@hotwired/turbo-rails';
Turbo.session.drive = false;

Add an indicator to show how the current page is rendered

Although this is not a requirement, we have found it useful to display whether the current page is rendered by React or by ERB. We typically add a badge to the app/views/layouts/application.html.erb layout and to the React layout as well. Only show this indicator in development mode.

docker-compose.yml

Since the original Rails development environment should already be configured with docker-compose.yml, all we need to do is to add the Next.js container and adjust the network ports.

The simplest way to to copy the next container section in the demo docker-compose.yml file.

Note that the external port for web container (running Rails) is moved to 3001. We use this only when we have already created React pages (available through port 3000), but we want to directly access the ERB pages in development, bypassing the Next.js server. Port 3001 is not used anywhere else. In production, we should remove this external port since we would never want to show both the React and ERB pages (it would most likely be detrimental for SEO).

Also, if you wish to run Next.js in production mode, simply use command: yarn start instead of command: yarn dev and set environment variables accordingly.

Allow non-localhost clients to access the Rails app in development

In development, Rails is configured to restrict access from external clients. Pending further information on how to set this up better, we have simply turned this off in development.

config/environments/development.rb

  config.hosts = []