react_router_rails_spa 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 261fa2216af64ecdaff4a8d74850b7ccebd05f4c3d0fbd8af986fd0658faf873
-  data.tar.gz: 262c1899faf8d7b574d7c6523fb864139c640a1faf274c581f07139d68ae68bd
+  metadata.gz: a8b4be06b2470f7ece193c99c21dca1af7ae3856591399c8e16b6170bcc54c9e
+  data.tar.gz: b845de80454767f463266504cff5028f098d9de7bb4837ff3de0d310c08ef5a5
 SHA512:
-  metadata.gz: dec2a2a6262c9b3cbff0fa5f8f301d55cef2433b0f2b29350a610874240b735ca7d6b265f271df8dbd91e33cd922c7a41c038417ed22dd3f195a3dea77b671ac
-  data.tar.gz: 6419659c7dd675ea3e531efc15a6dfaef38597db12d420f84eb9ac61c0bb088121998c4e333bf2b2801d552a34010f0d802ca3aa494fe44cfc0534726e83791c
+  metadata.gz: 17b47b7846d437d18bc48ff589f183b5a7b1a8d7e9406cd34ff9a3e19eab5d388facdbcb1685bf3df56a52a81e3300eb50fe6fbcbd627e73233f7eb1028d7633
+  data.tar.gz: e781941c2404d2e5f7e41be2249cb3ed17fc56d3975d1a6d23324b02d1cf2b7fc05f9f3ed0784de29319dbcc18c9f7c2e9fa5e46445b40bb555d2a99c1e2937f

data/README.md

@@ -1,38 +1,139 @@
-# ReactRouterRails
+## React Router SPA Framework mode integration for Ruby on Rails
 
-TODO: Delete this and the text below, and describe your gem
+The react_router_rails_spa gem integrates [React Router in SPA Framework mode](https://reactrouter.com/how-to/spa) with your Ruby on Rails application.
+The React app is built as static assets in your Rails `public` folder, and so it can be deployed on your current production server with minimal, if any, configuration changes.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/react_router_rails_spa`. To experiment with that code, run `bin/console` for an interactive prompt.
+Benefit from state-of-the-art React SPA technlologies –
+the integrated client-side router, loader data-fetching pattern,
+automatic code-splitting, and development server with HMR,
+without the costs and complexities of running a separate front-end server.
+
+If you are using Next.js, not for SEO
+but only for convenience,
+if you are not using SSR but fetching data on the client-side,
+then this gem will provide you with a similarly convenient but simpler, cheaper and more performant solution.
+
+ You may be considering the traditional approaches to React and Rails integration such as [Webpacker](https://github.com/rails/webpacker),
+[jsbundling-rails](https://github.com/rails/jsbundling-rails), [Vite Ruby](https://github.com/ElMassimo/vite_ruby)
+but concerned about installing and configuring additional packages, and avoiding SPA pitfalls.
+With a single gem and a single command, this gem sets up all that you need in  "Omakase"-style – Rails route and controller setup, an integrated client-side router, automatic per-route code-splitting, and the loader data-fetch pattern to eliminate data-fetch waterfalls.
+
+## Who is it for?
+
+Consider trying out this gem if you fit any of the following descriptions.
+
+- You want to integrate React into a Ruby on Rails application.
+  - You want an out-of-the-box solution for a state-of-the-art multipage React application. You do not enjoy installing React, React Router, Tailwind, configuring code-splitting, and deciding the data-loading scheme that you will use throughout your application. You want "Omakase" on the front-end as well as your Rails back-end. 
+  - Your Ruby on Rails application already has ERB (Hotwire)  pages.
+- You do not need SEO for the React generated pages (you don't need SSR/SSG).
+  - You can always use ERB views for the pages that neww SEO.
+- You do not want to host multiple servers for your frontend and your backend.
+  - You do not want to incur the additional costs, complexity, and authentication concerns that are inherent when dealing with multiple servers.
+  - You want to simply deploy your React frontend as static assets on a single server, inside your Ruby on Rails `public` folder.
+- You have many pages, and you want to reduce the initial JavaScript payload size by using automatic code-splitting and lazy-loading, but without sacrificing performance due to request waterfalls.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+The React Router application will be installed inside the `frontend` directory. We assume that you have an existing Ruby on Rails application.
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'react_router_rails_spa'
+```
+
+Then, run:
+
+```shell
+bundle install
+bin/rails generate react_router_rails_spa:install
+```
+
+This will create a new directory called `frontend` inside the project root.
+It will also create a React bootstrap endpoint for all paths starting with `/react`.
+The endpoint will be handled by `ReactController#show`.
 
-Install the gem and add to the application's Gemfile by executing:
+You will also have rake tasks for starting the dev server and building/previewing the React app.
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+As part of the integration, we provide utilities for using the robust CSRF protection built into Ruby on Rails from your React application.
+
+## Running the React Router development server
+
+React Router is built with Vite and uses the Vite development server to provide a Hot Module Replacement (HMR) capability, that is very helpful for routing editing of pages.
+However, the development server is not used in production and will not widely represent the application's behavior in production.
+We therefore strongly recommend that you build the React Router assets into the `public` folder and preview it before deploying into production. 
+
+Start the Vite development server with HMR with the following command (we assume that the Ruby on Rails server is already running (with either `bin/rails s` or `bin/dev`).
+
+```shell
+bin/rails react_router:dev
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Access the development server from the URL outputted from this command (Typically `http://localhost:5173/react`)
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+To preview the production build, run the following command.
+```shell
+bin/rails react_router:preview
 ```
 
-## Usage
+This will build the React Router application into the Rails `public` folder, and the React Router application will be available from the Rails development server (puma) at `http://localhost:3000/react`.
+The preview will be representative of the production app's behavior.
+
+## Deployment
+
+This gem integrates with the Ruby on Rails Asset pipeline.
+
+The React Router application is automatically built whenever `bin/rails assets:precompile` is run
+and therefore no changes should be required since your Ruby on Rails application should already do this.
+
+If your deployment pipeline does not already install Node (for example, you have a "no-build" deployment for Rails),
+then install it in your CI/CD environment since building the React Router application will require it.
+
+## Background
+
+Ruby on Rails has officially supported bundling of complex JavaScript frontend libraries,
+first with [Webpacker](https://github.com/rails/webpacker),
+and currently with [jsbundling-rails](https://github.com/rails/jsbundling-rails).
+We also have [Vite Ruby](https://github.com/ElMassimo/vite_ruby) with an integrated dev server, HMR and other goodies.
+
+However, on February 14th, 2025,
+the React team announced the [official deprecation of Create React App (CRA)](https://react.dev/blog/2025/02/14/sunsetting-create-react-app).
+Instead, they suggested developers should use a framework that builds single-page apps
+(SPA) deployable to a CDN or a static hosting service –
+In other words, SPA frameworks such as Next.js or React Router.
+Importantly,
+they advised
+against [building a React app from scratch](https://react.dev/learn/build-a-react-app-from-scratch)
+unless your app has constraints not well-served by existing SPA frameworks.
+
+This approach poses challenges to the traditional Rails integration solutions.
+They all compile the React applications to a single JavaScript file
+that is then loaded from an ERB file (the React bootstrap HTML) containing helper functions such as
+`javascript_include_tag` (jsbundling-rails), `javascript_pack_tag` (webpacker), or `vite_javascript_tag` (vite-rails).
+However, SPA frameworks do not just compile to a single JavaScript file.
+Instead,
+they additionally generate their own React bootstrap HTML file which includes many framework-specific optimizations
+(React Router v7 generates this using SSG from `app/root.tsx`).
 
-TODO: Write usage instructions here
+This gem uses the bootstrap HTML file
+generated by the SPA framework instead of an ERB file.
+This is served through an ActionController endpoint,
+enabling you to use cookies to send session-specific information on the first HTML load
+and is used in this gem to send CSRF tokens.
 
-## Development
+## Notes when using Rails in API mode
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Ruby on Rails provides an API mode that removes many frontend features.
+Importantly, API mode implies a stateless API server that does not support cookies.
+It removes the middleware for cookie handling and also for CSRF protection.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To fully benefit from hosting your React app inside Rails' `public` folder, we recommend that you avoid API-mode and instead use cookies for authentication.
+If you want to convert your API-mode application to use cookies, make sure to also restore CSRF features.
+Otherwise, your app will be vulnerable to CSRF attacks.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/react_router_rails_spa. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/re_rou_ra/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/naofumi/react_router_rails_spa. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/naofumi/react_router_rails_spa/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -40,4 +141,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the ReactRouterRails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/react_router_rails_spa/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the ReactRouterRailSpa project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/naofumi/react_router_rails_spa/blob/main/CODE_OF_CONDUCT.md).

data/documents/introduction.md

@@ -0,0 +1,290 @@
+# Integrating Ruby on Rails with Modern SPAs
+
+## TL;DR;
+
+This article describes the [react_router_rails_spa gem](https://github.com/naofumi/react_router_rails_spa), which allows you to integrate a React Router SPA framework application into you existing Ruby on Rails project.
+
+To jump to the installation steps, go to the "Steps to Integrate React Router into your Rails Application" section.
+
+## Who is this for?
+
+The react_router_rails_spa gem was designed for the following situations.
+
+### You want to create a web application with a React frontend and a Rails backend.
+
+* You want a simple setup that is ["omakase"](https://dhh.dk/2012/rails-is-omakase.html). You don't want to install packages and configure them on the React side. You don't want to manually add routes and controllers on the Rails side. 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 worry about server charges.
+* You don't need SEO for the React pages. 
+* If SEO is necessary, you can just serve ERB pages or static HTML files. 
+
+### You are considering Next.js, but you do not need SSR nor RSCs. You are only considering Next.js because it is easy to set up.
+
+* You're only using Next.js because you thought it was ["omakase"](https://dhh.dk/2012/rails-is-omakase.html). You actually found Rails integration harder than you bargained for.
+* You are worried about deployment. Specifically, you are not happy with Vercel pricing or the extra cost of an additional AWS ECS instance to host Next.js.
+
+The react_router_rails_spa gem satisfies the above requirements and more.
+It will give you an ["omakase"](https://dhh.dk/2012/rails-is-omakase.html) Modern React SPA with a single command.
+
+### You want to use React because you believe you can create better UIs
+
+* You're using React because you think you can create a better UI/UX compared to Hotwire (I actually think that this is untrue and Hotwire can create great UI/UXs, but that's a different discussion)
+* You want to use cutting-edge React capabilities like code-splitting, loader-based data fetching and more. You don't want to create a slow, bloated, legacy React app.
+
+## Who is this NOT for?
+
+### You want to embedd some React components on top of your ERB-rendered pages
+
+This is [the original way that React was used](https://react.dev/learn/add-react-to-an-existing-project#using-react-for-a-part-of-your-existing-page).
+If you wish to take this approach,
+you can build your own system or use Gems like [react-rails](https://github.com/reactjs/react-rails) and  [turbo-mount](https://github.com/skryukov/turbo-mount).
+Turbo Mount uses Stimulus to mount components, and is therefore more robust if you are using Hotwire in your ERB views.
+
+## Background
+
+On February 14th, 2025,
+the React team published a blog post
+titled [Sunsetting Create React App](https://react.dev/blog/2025/02/14/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](https://react.dev/blog/2025/02/14/sunsetting-create-react-app#how-to-migrate-to-a-framework)
+that could be deployed on a CDN, a static hosting service, or the `public` folder of a Ruby on Rails application.
+
+In the following, I will call SPAs built with an SPA framework, **"Modern React SPAs"**
+to highlight that this is the current officially recommended approach.
+To contrast, I 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](https://react.dev/learn/build-a-react-app-from-scratch) 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.
+
+I should note that Vite is essentially a bundler and a development server, with a plugin system that allows us to easily install various packages.
+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 both templates.
+
+> **"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 I know, nothing currently exists to easily integrate a Modern SPA with Rails.
+
+I hope to address this with this [react_router_rails_spa gem](https://github.com/naofumi/react_router_rails_spa).
+
+## 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](https://vite-ruby.netlify.app/guide/rails.html#tag-helpers-🏷) 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.
+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`.
+Instead, we have to take the bootstrap HTML generated by the SPA framework, and wrap Rails 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](https://github.com/naofumi/react_router_rails_spa) does 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 you can easily update your NPM packages independently of this gem. The generated code is also heavily commented to help you understand the internals for yourself.
+
+### React Router
+
+We install and use React Router in framework mode, [configured to generate an SPA build](https://reactrouter.com/how-to/spa).
+This will build static files that can be served from any static hosting provider, including the `public` folder in Rails.
+
+One of these static files is the bootstrap HTML template (the root `index.html` file).
+We change the name of this file so that it will not be directly served from the `public` folder.
+Instead,
+we use a dedicated Rails controller to add Rails-generated HTTP headers and cookies
+and serve the file as the response body.
+
+After building, these static files will be transferred to the Rails `public` folder from which they can be deployed like any other static asset.
+
+### Rails routes.rb and the ReactController
+
+We generate a `ReactController` that serves the bootstrap HTML template.
+The body of the response is the exact contents of the React Router-generated `index.html` file, but
+by passing it through the `ReactController`,
+we can customize the headers and add session-specific information as cookies.
+
+For example, `ReactController`
+includes  the `ReactRouterRailsSpa::CsrfCookieEnabled` module
+which sends session-specific CSRF tokens via cookies to integrate Rails'
+CSRF protection with React.
+
+`ReactController` will also add session cookies so that you can take advantage of session information from the bootstrap HTML file onwards.
+
+Finally, the `ReactController` allows you to set cache headers separately from assets served directly from the `assets` folder.
+
+Rails uses the [ActionDispatch::Static middleware](https://api.rubyonrails.org/classes/ActionDispatch/Static.html)
+to serve assets from the `public` folder,
+and this sets the HTTP caching headers aggressively to allow extensive caching for long periods of time.
+While this is great for JavaScript, CSS and image assets,
+this is usually undesirable for HTML files since we cannot attach cache-busting digests to them.
+Serving the bootstrap HTML template through `ReactController` allows us
+to easily change the cache headers to values that are suitable for HTML responses.
+Currently, the [react_router_rails_spa gem](https://github.com/naofumi/react_router_rails_spa) uses the same cache headers as other ERB files,
+but this can be customized in the controller. 
+
+Another way to look at this integration is like this;
+
+* The traditional approach taken by webpack, esbuild and vite-rails, is to communicate between the React application and Rails via a Rails generated ERB bootstrap HTML. For example, Rails-generated CSRF tokens were provided as `meta` tags embedded in HTML.
+* The current approach is to use the React Router generated bootstrap HTML and to add Rails integration through HTTP headers (including cookies) only. That's why this gem sends Rails-generated CSRF tokens to the React application using cookies.
+
+### 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 adds minor configurations for this.
+If you want a different setup, you can change the configurations.
+
+Note that configurations for the Vite development server are tricky.
+We have provided settings
+to compensate for the fact that the development server runs on port 5173 while the Rails application runs on port 3000.
+However, this will not allow you to test integration between Rails and React.
+
+* The React app runs on port 5173 while the ERB files are on port 3000. Links between the two will not work on the development server, even if they are fine in production.
+* The React app running on the development server will not bootstrap from the Ruby on Rails endpoint on the `ReactController#show` action. Instead, the development server will directly serve the React Router generated bootstrap HTML. This means that the bootstrap file will not contain Rails integrations. This is only an issue on the development server and not in production.
+
+As a solution, you can use the development server with HMR for small fixes, but for larger changes,
+you will need to use a "preview" build.
+You should also always check with a "preview" build before deploying to production.
+
+We provide a rake task for building a "preview".
+
+```shell
+bin/rails react_router:preview
+```
+
+## Demo and Source code
+
+* I have a [demo application based on the current proposal running on Kamal on a VPS server](https://rrrails.castle104.com/react-router/). It has simple, session-based authentication and basic CRUD. Mutations are secured by integration with Rails CSRF protection.
+* In the demo application, I have intentionally added a 0.5 to 1.5-second 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](https://github.com/naofumi/react-router-vite-rails).
+
+The source code is heavily commented. I 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.
+
+```shell
+rails new [project name]
+```
+
+Note that this gem works even with a no-build Rails setup (which is the Rails default),
+but you will need Node on your machine to install React Router.
+
+### Install the `react_router_rails_spa` gem
+
+Add the following line to your `Gemfile`.
+
+```ruby
+gem "react_router_rails_spa"
+```
+
+Install the gem
+
+```shell
+bundle install
+```
+
+We recommend committing your changes at this point before the following generator adds and modifies your files.
+
+Run the generator
+
+```shell
+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 development server. This comes with HMR (Hot Module Replacement).
+
+```shell
+bin/rails react_router:dev
+```
+
+Point your browser to http://localhost:5173/react/ to see the welcome page.
+
+### 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.
+
+```shell
+bin/rails react_router:build
+```
+
+Start your Rails application if it is not already running.
+
+Point your browser to http://localhost:3000/react/ to see the welcome page.
+
+This command is also aliased as `preview`.
+
+```shell
+bin/rails react_router:preview
+```
+
+### Read the added code
+
+I have added numerous comments to the code generated by this gem. Please read it to understand how the integration works.
+

data/lib/react_router_rails_spa/csrf/csrf_cookie_enabled.rb

@@ -0,0 +1,20 @@
+# This concern sets the CSRF token inside the "X-CSRF-Token" cookie,
+# allowing you to easily use the robust CSRF protection that Ruby on Rails provides
+# inside your React Router app.
+#
+# Refer to `frontend/app/utilities/csrf.ts` to see
+# how the client side is implemented.
+module ReactRouterRailsSpa
+  module CsrfCookieEnabled
+    extend ActiveSupport::Concern
+    included do
+      before_action :set_csrf_cookie
+    end
+
+    private
+
+    def set_csrf_cookie
+      cookies["X-CSRF-Token"] = form_authenticity_token
+    end
+  end
+end

data/lib/react_router_rails_spa/generators/install_generator.rb

@@ -6,19 +6,54 @@ module ReactRouterRailsSpa
       source_root File.expand_path("templates", __dir__)
 
       def create_react_router_app
-        say "Setting up React Router v7 SBA mode in Rails..."
+        say "Downloading React Router v7 ..."
         inside Rails.root do
           run "npx create-react-router@latest frontend --yes --no-git-init"
         end
       end
 
       def setup_rails_routes
-        route 'get "react/*path", to: "react#show"'
+        say "Setting up Rails routes ..."
+        route <<~RUBY
+          # When we use React Router inside a subdirectory, it works better if we
+          # use a trailing slash for the root path.
+          # This redirects from "/react-router" to "/react-router/".
+          get "react", to: redirect("/react/"), constraints: ->(req) {
+              req.original_url.last != "/"
+            }
+
+          # All requests to `/react/*` are handled by ReactController#show.
+          match "react", to: "react#show", via: :all
+          get "react/*path", to: "react#show"
+        RUBY
       end
 
       def create_react_controller
-        create_file "app/controllers/react_controller.rb", <<-RUBY
+        say "Creating the React bootstrap endpoint controller ..."
+        create_file "app/controllers/react_controller.rb", <<~RUBY
+          # This controller provides the catch-all action for React Router.
+          # This will render the bootstrap HTML file
+          # for all React Router requests.
+          #
+          # Unlike typical webpack or esbuild setups, we do not generate the bootstrap HTML file from ERB templates which include
+          # `javascript_include_tag` (propshaft, sprockets) or `javascript_pack_tag` (webpack).
+          # Instead, we take the index.html file that was generated by the React Router build
+          # and rename it to "react-router-rails-spa-index.html".
+          # We then serve this from the controller action in response to the bootstrap HTML file request.
+          #
+          # Benefits:
+          #
+          # * We can use the index.html file that React Router generates using SSG,
+          #   from the `frontend/app/root.tsx` file.
+          #   This file contains optimizations that would be challenging to recreate inside Rails using ERB templates.
+          # * By going through the Rails controller, we can adjust the cache and cookie headers to
+          #   improve performance, reliability, and integration with Rails.
+          #
+          # The included ReactRouterRailsSpa::CsrfCookieEnabled module will 
+          # send the CSRF token inside the "X-CSRF-Token" cookie for use inside your React app.
           class ReactController < ApplicationController
+            include ReactRouterRailsSpa::CsrfCookieEnabled
+
             def show
               render file: Rails.public_path.join("react/react-router-rails-spa-index.html"), layout: false
             end
@@ -26,20 +61,19 @@ module ReactRouterRailsSpa
         RUBY
       end
 
-      def create_public_folders
-        empty_directory Rails.root.join("public/react")
-      end
-
       def copy_rake_task
+        say "Copying Rake tasks ..."
         template "react.rake", "lib/tasks/react.rake"
       end
 
       def copy_react_router_configs
+        say "Copying React Router configurations ..."
         template "react-router.config.ts", "frontend/react-router.config.ts"
         template "vite.config.ts", "frontend/vite.config.ts"
       end
 
       def copy_react_app_files
+        say "Copying React Router application pages and utilities ..."
         template "home.tsx", "frontend/app/routes/home.tsx"
         directory "welcome", "frontend/app/welcome"
         template "csrf.ts", "frontend/app/utilities/csrf.ts"

data/lib/react_router_rails_spa/generators/templates/csrf.ts

@@ -14,13 +14,13 @@
 *
 * How it works.
 *
-* 1. The Ruby on Rails server sends the session-specific
+* 1. The Ruby on Rails server creates and sends the session-specific
 *    CSRF token in a Cookie named "X-CSRF-Token"
 *    app/controllers/concerns/csrf_cookie_enabled.rb
 * 2. Retrieve this token with the `getCSRFToken()` function
 *    and use its value to send in your fetch request headers.
 * 3. On receiving the request, Rails will validate that the
-*    'X-CSRF-Token' header value matches what was sent via the cookie.
+*    'X-CSRF-Token' header value is identical to the session-specific token.
 * 4. Note that you only need to do this for non-GET requests assuming that
 *    you are following best practices and not mutating data in GET requests.
 *
@@ -36,6 +36,10 @@
 *      }
 *    )
 *
+* Note that Axios has a feature that automatically does this for you.
+* Read the XSRF configuration comments on the linked page.
+* https://axios-http.com/docs/req_config
+*
 * */
 
 export function getCSRFToken() {

data/lib/react_router_rails_spa/generators/templates/csrf_cookie_enabled.rb

@@ -0,0 +1,18 @@
+# This concern sets the CSRF token inside the "X-CSRF-Token" cookie,
+# allowing you to easily use the robust CSRF protection that Ruby on Rails provides
+# inside your React Router app.
+#
+# Refer to `frontend/app/utilities/csrf.ts` to see
+# how the client side is implemented.
+module CsrfCookieEnabled
+  extend ActiveSupport::Concern
+  included do
+    before_action :set_csrf_cookie
+  end
+
+  private
+
+  def set_csrf_cookie
+    cookies["X-CSRF-Token"] = form_authenticity_token
+  end
+end

data/lib/react_router_rails_spa/generators/templates/proxy.ts

@@ -1,17 +1,24 @@
 /*
-* In this example application, the Ruby on Rails APIs endpoints are like
-* `GET /posts` or `GET /users` and do not have any prefixes like `/api*`.
+* The `baseApiPath()` is useful when you are using the React Router development server
+* and the JSON API endpoints on your Rails server do not have specific prefixes.
+* It is not used in production or preview builds.
 *
-* However, during development, the port for the Vite development server (typically 5173) is different from
+*
+* In the example application, the Ruby on Rails API endpoints are like
+* `GET /posts` or `GET /users` and do not have any specific prefixes like `/api*`.
+*
+* However, during development, the port for the React Router development server (typically 5173) is different from
 * the Rails development server (typically 3000).
-* This means that the Vite server needs to distinguish
+* This means that the React Router server needs to distinguish
 * between the requests it should send to the Rails server on port 3000 (JSON API requests) and the
-* ones that it should handle itself on port 5173 (e.g., the Vite assets).
+* ones that it should handle itself on port 5173 (e.g., the React Router assets).
 *
-* Therefore, when running on the Vite development server, we prefix
-* requests intended for the Rails API server with "/api" to tell Vite to send them
+* Therefore, when running on the React Router development server, we prefix
+* requests intended for the Rails API server with "/api" to tell the development server to send them
 * to port 3000.
-* See the `proxy:` section in `frontend-react-router/vite.config.ts` for
+* The all other requests will be sent to port 5173.
+*
+* See the `proxy:` section in `frontend/vite.config.ts` for
 * the Vite side of this configuration.
 *
 * Using this function, you would write a request to the Rails API as follows.
@@ -20,8 +27,8 @@
 *       headers: { "Accept": "application/json" }
 *     }).then(...)....
 *
-* Note that if your API server's endpoints are like `/api/posts`,
-* then you can write like the following, without the `baseApiPath()` function.
+* Note that if your JSON API server's endpoints are like `/api/posts`,
+* then you don't need the `baseApiPath()` function.
 *
 *   fetch(`/api/posts`, {
 *       headers: { "Accept": "application/json" }

data/lib/react_router_rails_spa/generators/templates/react-router.config.ts

@@ -2,11 +2,10 @@ import type { Config } from "@react-router/dev/config";
 
 export default {
   // Config options...
-  // For our React Router app, we will turn off Server-side render
-  // use SPA mode!!
+  // For our React Router app, we will turn off Server-side render and use SPA mode.
   ssr: false,
-  // In the above, we have decided to serve the React Router app from "/react-router/".
-  // The basename options tell React Router to manage this when generating
+  // We serve the React Router app from the "/react/" path.
+  // The basename option tells React Router to manage this when generating
   // Link tags, for example.
-  basename: "/react-router/"
+  basename: "/react/"
 } satisfies Config;

data/lib/react_router_rails_spa/generators/templates/react.rake

@@ -1,17 +1,4 @@
-namespace :react do
-  desc "Build the React application"
-  task :build do
-    puts "Building React Router v7 app..."
-    system("cd frontend && npm install && npm run build")
-
-    puts "Moving build files to public/react-router..."
-    system("rm -rf public/react-router/*")
-    system("mv frontend/dist/* public/react-router/")
-    system("mv public/react-router/index.html public/react-router/react-router-index.html")
-
-    puts "✅ React app successfully built and deployed!"
-  end
-end
+# frozen_string_literal: true
 
 namespace :react_router do
   # For convenience, npm packages do not have to be explicitly installed.
@@ -30,9 +17,9 @@ namespace :react_router do
   # this task in the Procfile.
   #
   # bin/rails react_router:dev
-  desc "Start React Router Dev Server"
-  task dev: [ :npm_install ] do
-    puts "Starting React Router v7 app dev server..."
+  desc "Start React Router Development Server with Hot Module Reloading"
+  task dev: [:npm_install] do
+    puts "Starting React Router v7 app development server..."
     Dir.chdir("#{Dir.pwd}/frontend") do
       system("npm", "run", "dev")
     end
@@ -40,7 +27,7 @@ namespace :react_router do
 
   # bin/rails react_router:typecheck
   desc "Check Typescript for the React Router App"
-  task typecheck: [ :npm_install ] do
+  task typecheck: [:npm_install] do
     puts "Check Typescript for React Router v7 app..."
     Dir.chdir("#{Dir.pwd}/frontend") do
       system("npm", "run", "typecheck")
@@ -54,21 +41,26 @@ namespace :react_router do
   # Running bin/rails assets:precompile will also run this task.
   #
   # bin/rails react_router:build
-  desc "Build React Router App"
-  task build: [ :npm_install ] do
-    Dir.chdir("#{Dir.pwd}/frontend") do
-      puts "Building React Router v7 app..."
-      system("npm", "run", "build")
+  desc "Build React Router App and move to the public folder"
+  task build: [:npm_install] do
+    puts "Building React Router v7 app..."
+    `cd frontend && npm run build`
 
-      puts "Moving build files to public/react..."
-      system("rm -rf public/react/*")
-      system("mv frontend/build/client public/react")
-      system("mv public/react/index.html public/react/react-router-rails-spa-index.html")
+    puts "Moving build files to public/react..."
+    `rm -rf public/react`
+    `mv frontend/build/client public/react`
+    `mv public/react/index.html public/react/react-router-rails-spa-index.html`
 
-      puts "✅ React app successfully built and deployed!"
-    end
+    puts "✅ React app successfully built and deployed!"
   end
 
+  # Run bin/rails react_router:preview to create a preview build.
+  #
+  # This is identical to running bin/rails react_router: build
+  # and is provided solely to align better with intent.
+  desc "Preview your React Router App from the Rails development server (typically port 3000)"
+  task preview: [:build]
+
   # Run bin/rails react_router:clobber to remove the build files.
   # Running bin/rails assets:clobber will also run this task.
   task :clobber do
@@ -83,5 +75,5 @@ end
 # This means that any normal Rails deployment script which
 # contains rake assets:precompile will also build the
 # React Router app automatically.
-Rake::Task["assets:precompile"].enhance([ "react_router:build" ])
-Rake::Task["assets:clobber"].enhance([ "react_router:clobber" ])
+Rake::Task["assets:precompile"].enhance(["react_router:build"])
+Rake::Task["assets:clobber"].enhance(["react_router:clobber"])

data/lib/react_router_rails_spa/generators/templates/vite.config.ts

@@ -3,32 +3,32 @@ import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 import tsconfigPaths from "vite-tsconfig-paths";
 
+const railsEnv = process.env.RAILS_ENV || 'development'
+
 export default defineConfig({
   plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
   build: {
     assetsDir: "assets",
-    // Set to true if you want sourcemaps
-    sourcemap: true,
+    // Set to true if you want sourcemaps in your build.
+    sourcemap: (["test", "development"].indexOf(railsEnv) !== -1) ? true : false,
   },
-  // Like in react-router.config.ts, this tells Vite that
-  // the app is served from the "/react-router/" sub-path.
-  // Change this if you want to use a different sub-path name.
-  base: "/react-router/",
+  // As also defined in react-router.config.ts, this tells Vite that
+  // the app is served from the "/react/" sub-path.
+  base: "/react/",
 
   // These are settings for the dev server.
   server: {
-    // In production, the API server (Rails) and the assets
-    // will be served from the same port number (typically 80).
+    // In production and preview mode, the API server (Rails) and the assets
+    // will be served from the same port number (typically 80 for production and 3000 for preview).
     //
-    // However, in development, assets will be served from the
-    // Vite dev server on port 5173, and the API server will be on
-    // port 3000 (Rails default).
-    // The use of different ports can complicate CORS setting and cookie handling.
+    // However, when using the vite development server, assets will be served from port 5173,
+    // and the API server will be on port 3000 (Rails default).
+    // The use of different ports complicates CORS settings and cookie handling.
     //
-    // To prevent this problem, Vite provides a proxy mode that can receive API requests
-    // on port (5173) and forward this to the Rails server (port 3000).
-    // The browser will think that all communication happens on port 5173 so CORS
-    // is no longer necessary.
+    // To work around this, Vite provides a proxy mode that can receive API requests
+    // on port (5173) and forward them to the Rails server (port 3000).
+    // From the browser's viewpoint, all communications including API requests to the Rails server
+    // will now happen on port 5173, so CORS will no longer be necessary.
     proxy: {
       // Any requests starting with "/api" will be forwarded according to
       // the following rules.
@@ -44,6 +44,8 @@ export default defineConfig({
         // Note that if the Rails server has a dedicated namespace for APIs,
         // then you can just use that instead of "/api", and the following
         // rewrite rule will not be necessary.
+        //
+        // Also see `frontend/app/utilities/proxy.ts` for how we handle this inside React.
         rewrite: (path) => path.replace(/^\/api/, ""),
       },
     },

data/lib/react_router_rails_spa/generators/templates/welcome/welcome.tsx

@@ -5,7 +5,7 @@ import railsLogo from "./rails-logo.svg";
 export function Welcome() {
   return (
     <main className="flex items-center justify-center pt-16 pb-4">
-      <div className="flex-1 flex flex-col items-center gap-16 min-h-0">
+      <div className="flex-1 flex flex-col items-center min-h-0">
         <header className="flex flex-row items-baseline gap-9 max-w-[100vw]">
           <div className="w-[300px]">
             <img
@@ -28,16 +28,18 @@ export function Welcome() {
             />
           </div>
         </header>
-        <div className="max-w-[300px] w-full space-y-6 px-4">
+        <div className="mt-12 text-2xl text-gray-600">with the</div>
+        <h1 className="mt-6 text-3xl font-bold">react_router_rails_spa gem</h1>
+        <div className="mt-12 max-w-[300px] w-full space-y-6 px-4">
           <nav className="space-y-4">
-            <p className="leading-6 text-gray-700 dark:text-gray-200 text-center">
+            <p className="text-2xl leading-6 text-gray-700 dark:text-gray-200 text-center">
               What&apos;s next?
             </p>
             <div className="text-center">
               {resources.map(({ href, text }) => (
                 <a
                   key={href}
-                  className="block mb-2 leading-normal text-blue-700 hover:underline dark:text-blue-500"
+                  className="block mb-4 leading-tight text-blue-700 hover:underline dark:text-blue-500"
                   href={href}
                   target="_blank"
                   rel="noreferrer"
@@ -54,12 +56,20 @@ export function Welcome() {
 }
 
 const resources = [
+  {
+    href: "https://github.com/naofumi/react_router_rails_spa",
+    text: "Read the README for the react_router_rails_spa gem",
+  },
+  {
+    href: "https://github.com/naofumi/react_router_rails_spa/documentation/introduction.md",
+    text: "Read the Introduction for the react_router_rails_spa gem",
+  },
   {
     href: "https://reactrouter.com/docs",
-    text: "React Router Docs",
+    text: "Read the React Router Docs",
   },
   {
-    href: "https://rmx.as/discord",
-    text: "Join Discord",
+    href: "https://reactrouter.com/docs",
+    text: "Read the Ruby on Rails Docs",
   },
 ];

data/lib/react_router_rails_spa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReactRouterRailsSpa
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/react_router_rails_spa.rb

@@ -2,6 +2,7 @@
 
 require_relative "react_router_rails_spa/version"
 require_relative "react_router_rails_spa/generators/install_generator"
+require_relative "react_router_rails_spa/csrf/csrf_cookie_enabled"
 
 module ReactRouterRailsSpa
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: react_router_rails_spa
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Naofumi Kagami
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-07 00:00:00.000000000 Z
+date: 2025-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -32,7 +32,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".idea/.gitignore"
-- ".idea/.name"
 - ".idea/inspectionProfiles/Project_Default.xml"
 - ".idea/misc.xml"
 - ".idea/modules.xml"
@@ -44,9 +43,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- documents/introduction.md
 - lib/react_router_rails_spa.rb
+- lib/react_router_rails_spa/csrf/csrf_cookie_enabled.rb
 - lib/react_router_rails_spa/generators/install_generator.rb
 - lib/react_router_rails_spa/generators/templates/csrf.ts
+- lib/react_router_rails_spa/generators/templates/csrf_cookie_enabled.rb
 - lib/react_router_rails_spa/generators/templates/home.tsx
 - lib/react_router_rails_spa/generators/templates/proxy.ts
 - lib/react_router_rails_spa/generators/templates/react-router.config.ts
@@ -83,5 +85,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: Use React Router v7 framework on your Rails-powered SPA.
+summary: Integrate React Router v7 SPA framework with your Ruby on Rails backend.
 test_files: []

data/.idea/.name

@@ -1 +0,0 @@
-re_rou_ra