shakacode/react-webpack-rails-tutorial Setup and Architecture

What react-webpack-rails-tutorial demonstrates

This repository addresses the problem of adding React to a Ruby on Rails application without moving the entire application behind a separate single-page frontend. It is a tutorial and live demonstration rather than a narrowly focused component library. The live application is published at `www.reactrails.com`, and the repository presents an application structure in which Rails remains responsible for server behavior while React supplies richer browser interfaces.

The documented examples extend beyond mounting one React component. The application includes React, Redux, React Router, Rails Action Cable, internationalization through `react-intl`, CSS Modules, Tailwind CSS, Sass, hot reloading, linting, and integration with `npm` packages and Babel. This makes the repository more useful to engineers trying to understand how several parts of a full Rails and React application fit together.

Its intended audience is therefore broader than developers experimenting with JSX. It suits engineers who need a working reference for asset compilation, Rails integration, server rendering, or client-side state. However, the repository description labels it a legacy full-app tutorial and directs readers to `reactonrails.com/examples` for current maintained demonstrations. That qualification matters. The code can serve as a technical reference without being the recommended starting point for every new Rails application.

How Rails, Rspack, and the Node renderer connect

The repository uses the `react_on_rails` gem with React on Rails Pro, Shakapacker, and Rspack. According to the README, the Node Renderer performs server-side rendering and supports React Server Components. That arrangement introduces a second runtime alongside Rails: the Rails application handles requests and application behavior, while a Node service renders React through the renderer integration.

The `.env.example` file documents the contract between those processes. `REACT_ON_RAILS_PRO_LICENSE` contains a JWT token obtained from the React on Rails Pro service. `RENDERER_PASSWORD` is the shared secret between Rails and the Node renderer. The file states that development and test default to `local-dev-renderer-password` if the variable is absent, while production must configure it explicitly. `RENDERER_URL` identifies the renderer endpoint and defaults to `http://localhost:3800`. `RENDERER_PORT` selects the renderer port, and `RENDERER_WORKERS_COUNT` controls the worker process count. Setting it to `0` selects single-process mode for local debugging.

This design provides access to server rendering, streaming, and React Server Components, but it also creates more places where startup can fail. Operators must confirm that the Node process is listening, Rails can reach it over the configured URL, and both sides share the correct password. The README does not document a complete failure-recovery matrix for those cases, so this service boundary should be evaluated before selecting the architecture.

Prerequisites and a first ReScript use

The README does not document a complete installation sequence for this repository. It points readers to the project repository, its live demo, and the included development process files. The repository itself contains `Gemfile`, `Gemfile.lock`, `yarn.lock`, `Procfile.dev`, and several asset-related process files. The README also does not document one authoritative setup command that combines every Ruby and JavaScript prerequisite, so this tutorial does not invent a replacement sequence.

The `package.json` file provides concrete JavaScript constraints. It requires Node.js `>=22` and Yarn `1.22`. Its `postinstall` script runs `patch-package`, which means the JavaScript dependency lifecycle includes applying the patches stored by the project. The Ruby side is governed by Rails and gems listed in `Gemfile`, but the README does not state a single supported Ruby invocation for initial setup.

A documented first build action is the ReScript development watcher. This command removes generated ReScript output and starts a watch build:

yarn res:dev

The script corresponds to the package's ReScript clean and watch tasks. It should be used as a focused check of the ReScript toolchain, not as proof that the complete Rails application is ready. The README also documents independent JavaScript development through the Rspack dev server at `http://localhost:4000`. It does not give the exact combined startup command for Rails, the renderer, and the Rspack dev server, so the repository's process files remain the authoritative source for launching the complete application.

React Server Components and hydration boundaries

The repository's most distinctive example is the boundary between server-rendered and client-hydrated React components. The README describes this as the donut pattern and states that `'use client'` directives split the component tree. Components can therefore participate in server rendering while client boundaries identify the portions that require browser behavior and hydration.

The `/server-components` page demonstrates streaming, Suspense fallbacks, error boundaries, and client-driven re-fetching. These features are not simply a change in rendering speed. They require Rails, the Node renderer, generated bundles, and the browser runtime to agree about component boundaries and data flow. A component that reads browser-only data on the server, or a client boundary placed in the wrong position, can lead to hydration and runtime failures.

The repository structure supports that complexity. Its top-level directories include `app/`, `client/`, `renderer/`, `config/`, and `spec/`, while `package.json` contains scripts for generated packs and separate test and development builds. The linting scripts explicitly ignore generated client paths and `client/app/packs/server-bundle.js`. Those exclusions show that bundle generation is part of the application structure rather than an incidental command added after the fact.

React Server Components are not required for every React on Rails project. If an application needs only a small interactive widget, adopting this complete server-component boundary would add configuration and deployment complexity that the feature itself does not justify. The tutorial is most relevant when streaming or server-only component composition addresses a known requirement.

Where this legacy tutorial can mislead

The repository's range makes it useful as a worked example. It places Rails, React, Redux, React Router, Action Cable, Rspack, Shakapacker, CSS Modules, Tailwind CSS, Sass, hot reloading, Babel, and deployment examples in one project. Engineers can trace those connections rather than assembling an integration from disconnected snippets.

The limitation is equally clear. The repository description calls it legacy, and the README points to `reactonrails.com/examples` for current maintained demos. Its package description says `Code from the React Rspack tutorial`, while the README now covers React on Rails 16.4, Shakapacker 9.7, React Server Components, ES2024, and React on Rails Pro. That combination makes it valuable for architecture study but requires version comparison before copying dependencies and conventions into a new application.

The MIT license covers this repository, but it does not settle the licensing of the external services used by the demo. `.env.example` states that `REACT_ON_RAILS_PRO_LICENSE` is required in production. An engineer adopting the renderer or React on Rails Pro must review that service's own terms separately from this repository's MIT license. The distinction matters because repository source permission and hosted-feature permission are separate questions.

Maintenance, release activity, and upgrade cost

The repository is not archived. Its last push was on 2026-10-15. The release list includes production releases dated 2026-10-11, 2026-09-17, and 2026-06-04. These dates show recent repository and deployment activity, but the release names do not establish a separate compatibility policy for every dependency. The legacy label remains important because recent deployment activity is not the same thing as being the current recommended starter for a new project.

Upgrades can involve several dependency groups. On the JavaScript side, `package.json` constrains Node.js and Yarn while its scripts coordinate ReScript, Rspack-related assets, linting, Jest, and generated packs. On the Ruby side, the application depends on Rails and the `react_on_rails` gem. Production operation also depends on the Node renderer, its worker settings, and a valid React on Rails Pro token.

The release cadence suggests deployment activity, but upgrading remains a cross-runtime task rather than a single package update. The most project-specific first check is to compare the versions in `package.json`, `Gemfile.lock`, and `yarn.lock` with the React on Rails Pro documentation, then confirm that the generated-pack and renderer commands still match those versions.

Server rendering versus a smaller Rails integration

A conventional Rails application with a small React client integration is a genuine alternative. It would still need a JavaScript build and a mount point, but it would not require the full Node renderer arrangement solely to provide server-rendered React or React Server Components. This approach suits forms, validation feedback, dashboards, and isolated interactive controls where SSR or streaming is not a requirement.

A separately deployed SPA backed by a Rails API is another alternative. It gives the frontend an independent deployment boundary and can use React Router as the primary application shell, but it moves browser routing, authentication state, and API communication outside the Rails-rendered application. It does not demonstrate the server-component or hydration boundary taught by this repository.

The practical distinction is feature driven. Use this tutorial when the Rails and Node rendering relationship is the thing you need to understand. Choose a smaller client integration when the browser component only needs a Rails-provided page, and choose an SPA when separating the frontend application is the stated architectural goal.

Editorial conclusion

Engineers evaluating React on Rails integration should use this repository to study Rspack, Shakapacker, Redux, Action Cable, and the Node rendering boundary. People seeking a current minimal starter should first compare the README's legacy designation with the maintained examples at reactonrails.com/examples. Before copying it into production, verify that the required React on Rails Pro license, Node.js `>=22` environment, Yarn `1.22`, renderer secret, and renderer endpoint fit the target application.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. shakacode/react-webpack-rails-tutorial on GitHub