react_router_rails_spa 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 261fa2216af64ecdaff4a8d74850b7ccebd05f4c3d0fbd8af986fd0658faf873
-  data.tar.gz: 262c1899faf8d7b574d7c6523fb864139c640a1faf274c581f07139d68ae68bd
+  metadata.gz: 95855ba78c935cea1d1c666a75769bf23dca4b3593b6837f29ceb2d97c3259b2
+  data.tar.gz: b4f53bab792448b9a8a1f7df9d6b02a37680425ab51fcdde40cc90c3b3d7dc50
 SHA512:
-  metadata.gz: dec2a2a6262c9b3cbff0fa5f8f301d55cef2433b0f2b29350a610874240b735ca7d6b265f271df8dbd91e33cd922c7a41c038417ed22dd3f195a3dea77b671ac
-  data.tar.gz: 6419659c7dd675ea3e531efc15a6dfaef38597db12d420f84eb9ac61c0bb088121998c4e333bf2b2801d552a34010f0d802ca3aa494fe44cfc0534726e83791c
+  metadata.gz: 653a9a898765b134d1154e33169be82cd31d8143c775da3216e2106b7dad3b705a26d4fb94f07e30e200e478fd7d1398ae0308c883919e8a704d7a989ef53c6c
+  data.tar.gz: 813669a3b2801ddfad534b8ca1135f3f7dae018b8329f5bb112ced8fdf67d5367203c23f6f229b4b277ae645c6434e1e75c58f80cfbbb06c560fb4dea40133c9

data/.rubocop.yml

@@ -1,8 +1,221 @@
 AllCops:
   TargetRubyVersion: 3.0
+  NewCops: enable
 
+# Below taken from rubocop-rails-omakase
+
+# Align `when` with `end`.
+Layout/CaseIndentation:
+  Enabled: true
+  EnforcedStyle: end
+
+# Align comments with method definitions.
+Layout/CommentIndentation:
+  Enabled: true
+
+Layout/ElseAlignment:
+  Enabled: true
+
+Layout/EmptyLineAfterMagicComment:
+  Enabled: true
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: true
+
+# In a regular class definition, no empty lines around the body.
+Layout/EmptyLinesAroundClassBody:
+  Enabled: true
+
+# In a regular method definition, no empty lines around the body.
+Layout/EmptyLinesAroundMethodBody:
+  Enabled: true
+
+# In a regular module definition, no empty lines around the body.
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: true
+
+# Align `end` with the matching keyword or starting expression except for
+# assignments, where it should be aligned with the LHS.
+Layout/EndAlignment:
+  Enabled: true
+  EnforcedStyleAlignWith: variable
+
+# Method definitions after `private` or `protected` isolated calls need one
+# extra level of indentation.
+#
+# We break this rule in context, though, e.g. for private-only concerns,
+# so we leave it disabled.
+Layout/IndentationConsistency:
+  Enabled: false
+  EnforcedStyle: indented_internal_methods
+
+# Detect hard tabs, no hard tabs.
+Layout/IndentationStyle:
+  Enabled: true
+
+# Two spaces, no tabs (for indentation).
+#
+# Doesn't behave properly with private-only concerns, so it's disabled.
+Layout/IndentationWidth:
+  Enabled: false
+
+Layout/LeadingCommentSpace:
+  Enabled: true
+
+Layout/SpaceAfterColon:
+  Enabled: true
+
+Layout/SpaceAfterComma:
+  Enabled: true
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  Enabled: true
+
+Layout/SpaceAroundKeyword:
+  Enabled: true
+
+# Use `foo {}` not `foo{}`.
+Layout/SpaceBeforeBlockBraces:
+  Enabled: true
+
+Layout/SpaceBeforeComma:
+  Enabled: true
+
+Layout/SpaceBeforeFirstArg:
+  Enabled: true
+
+# Use `->(x, y) { x + y }` not `-> (x, y) { x + y }`
+Layout/SpaceInLambdaLiteral:
+  Enabled: true
+
+# Use `[ a, [ b, c ] ]` not `[a, [b, c]]`
+# Use `[]` not `[ ]`
+Layout/SpaceInsideArrayLiteralBrackets:
+  Enabled: true
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBrackets: no_space
+
+# Use `%w[ a b ]` not `%w[ a   b ]`.
+Layout/SpaceInsideArrayPercentLiteral:
+  Enabled: true
+
+# Use `foo { bar }` not `foo {bar}`.
+# Use `foo { }` not `foo {}`.
+Layout/SpaceInsideBlockBraces:
+  Enabled: true
+  EnforcedStyleForEmptyBraces: space
+
+# Use `{ a: 1 }` not `{a:1}`.
+# Use `{}` not `{  }`.
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: true
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+
+# Use `foo(bar)` not `foo( bar )`
+Layout/SpaceInsideParens:
+  Enabled: true
+
+# Requiring a space is not yet supported as of 0.59.2
+# Use `%w[ foo ]` not `%w[foo]`
+Layout/SpaceInsidePercentLiteralDelimiters:
+  Enabled: false
+  #EnforcedStyle: space
+
+# Use `hash[:key]` not `hash[ :key ]`
+Layout/SpaceInsideReferenceBrackets:
+  Enabled: true
+
+# Blank lines should not have any spaces.
+Layout/TrailingEmptyLines:
+  Enabled: true
+
+# No trailing whitespace.
+Layout/TrailingWhitespace:
+  Enabled: true
+
+Lint/RedundantStringCoercion:
+  Enabled: true
+
+# Use my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
+Lint/RequireParentheses:
+  Enabled: true
+
+Lint/UriEscapeUnescape:
+  Enabled: true
+
+# We generally prefer &&/|| but like low-precedence and/or in context
+Style/AndOr:
+  Enabled: false
+
+# Prefer Foo.method over Foo::method
+Style/ColonMethodCall:
+  Enabled: true
+
+Style/DefWithParentheses:
+  Enabled: true
+
+# Use Ruby >= 1.9 syntax for hashes. Prefer { a: :b } over { :a => :b }.
+Style/HashSyntax:
+  Enabled: true
+  EnforcedShorthandSyntax: either
+
+# Defining a method with parameters needs parentheses.
+Style/MethodDefParentheses:
+  Enabled: true
+
+Style/ParenthesesAroundCondition:
+  Enabled: true
+
+Style/PercentLiteralDelimiters:
+  Enabled: true
+  PreferredDelimiters:
+    default: "()"
+    "%i": "[]"
+    "%I": "[]"
+    "%r": "{}"
+    "%w": "[]"
+    "%W": "[]"
+
+# Use quotes for string literals when they are enough.
+Style/RedundantPercentQ:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: true
+  AllowMultipleReturnValues: true
+
+Style/Semicolon:
+  Enabled: true
+  AllowAsExpressionSeparator: true
+
+Style/StabbyLambdaParentheses:
+  Enabled: true
+
+# Use `"foo"` not `'foo'` unless escaping is required
 Style/StringLiterals:
+  Enabled: true
   EnforcedStyle: double_quotes
 
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
+Style/TrailingCommaInArrayLiteral:
+  Enabled: true
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: true
+
+# Other cops
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: true
+  Exclude:
+    - "**/*.gemspec"
+    - "**/*.rake"
+
+Gemspec/RequireMFA:
+  Enabled: true

data/README.md

@@ -1,38 +1,138 @@
-# 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.
 
-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.
+The React app is built as a static SPA.
+Static assets will be built in your Rails `public` folder,
+and will be deployed on your current production server with minimal, if any, configuration changes.
+
+With a single gem and a single command,
+this gem sets up all that you need in  ["Omakase"](https://dhh.dk/2012/rails-is-omakase.html)-style – An integrated client-side router,
+per-route code-splitting, the loader data-fetch pattern, Rails controllers and routes –
+All of this will be automatically set up for you.  
+
+[Read the introduction](https://github.com/naofumi/react_router_rails_spa/blob/main/documents/introduction.md) for more background: 
+
+## Who is it for?
+
+Consider trying out this gem if any of the below apply to you.
+
+- You want an out-of-the-box solution. 
+  - 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"](https://dhh.dk/2012/rails-is-omakase.html) on the front-end as well as your Rails back-end. 
+- You do not need SEO, at least not for the React pages.
+  - You can always use ERB views for the pages that need SEO.
+- You are tired of managing 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, for no concrete benefit.
+  - 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.
+We assume that you already 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
+```
+
+followed by:
+
+```shell
+bin/rails generate react_router_rails_spa:install
+```
+
+This will create a new directory called `frontend` inside the project root.
+This is where your React application is.
+
+It will also create a React bootstrap endpoint in your Rails routes for all paths starting with `/react`.
+The endpoint will be handled by `ReactController#show`.
+
+## Running the React Router development server
 
-Install the gem and add to the application's Gemfile by executing:
+React Router is built with Vite and uses the Vite development server to provide a Hot Module Replacement (HMR) capability.
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+Start the Vite development server with the following command
+(we assume that the Ruby on Rails server is already running (with either the `bin/rails s` or the `bin/dev` command).
+
+```shell
+bin/rails react_router:dev
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Note that the development server will not fully represent the application's behavior in production.
+In particular, the development server is only partially integrated with Rails.
+We therefore strongly recommend that you build the React Router assets into the `public` folder and preview it before deploying into production.
 
-```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.
+The React Router application will be available from the Rails development server
+(puma) at `http://localhost:3000/react`.
+This preview will be representative of the production app's behavior with Rails integration.
+
+## Deployment
+
+This gem integrates with the Ruby on Rails Asset pipeline, and the React application is automatically built whenever `bin/rails assets:precompile` is run.
+No changes are required on your deployment script, since your Ruby on Rails application should run this command.
+
+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`).
+
+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.
 
-TODO: Write usage instructions here
+## Notes when using Rails in API mode
 
-## Development
+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.
 
-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.
+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.
 
-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).
+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 +140,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,293 @@
+# Integrating Ruby on Rails with Modern SPAs
+
+## TL;DR;
+
+Integrating React onto a Ruby on Rails application is unnecessarily challenging.
+We have to install jsbundling-rails, install 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](https://github.com/naofumi/react_router_rails_spa),
+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](#using-the-gem).
+
+## 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"](https://dhh.dk/2012/rails-is-omakase.html). 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"](https://dhh.dk/2012/rails-is-omakase.html) 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](https://github.com/naofumi/react_router_rails_spa) 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](https://react.dev/learn/build-a-react-app-from-scratch).
+* 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 [how React was originally used](https://react.dev/learn/add-react-to-an-existing-project#using-react-for-a-part-of-your-existing-page).
+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.
+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 more robust if you are using Hotwire in your ERB views.
+
+## How does this compare to [...]?
+
+Compared to gems like [React on Rails](https://github.com/shakacode/react_on_rails) or [Intertia Rails](https://inertia-rails.dev/),
+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](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, 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](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.
+
+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.
+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 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](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 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 customize 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](https://reactrouter.com/how-to/spa).
+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](https://github.com/naofumi/react_router_rails_spa) 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 adds minor configurations for this.
+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](https://rrrails.castle104.com/react/). 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](https://github.com/naofumi/react-router-vite-rails).
+
+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.
+
+```shell
+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.
+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.)
+
+```shell
+rails new [project name] --javascript esbuild
+```
+
+### 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 frontend development server with HMR (Hot Module Replacement).
+
+```shell
+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.
+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.
+
+```shell
+bin/rails react_router:build
+```
+
+This command is also aliased as:
+
+```shell
+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.
+

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"
+  desc "Start React Router Development Server with Hot Module Reloading"
   task dev: [ :npm_install ] do
-    puts "Starting React Router v7 app dev server..."
+    puts "Starting React Router v7 app development server..."
     Dir.chdir("#{Dir.pwd}/frontend") do
       system("npm", "run", "dev")
     end
@@ -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"
+  desc "Build React Router App and move to the public folder"
   task build: [ :npm_install ] do
-    Dir.chdir("#{Dir.pwd}/frontend") do
-      puts "Building React Router v7 app..."
-      system("npm", "run", "build")
+    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

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/blob/main/documents/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://rubyonrails.org/",
+    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.2"
 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,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: react_router_rails_spa
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Naofumi Kagami
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-07 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.0.2
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.0.2
+date: 2025-04-22 00:00:00.000000000 Z
+dependencies: []
 description:
 email:
 - naofumi@mac.com
@@ -32,7 +18,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".idea/.gitignore"
-- ".idea/.name"
 - ".idea/inspectionProfiles/Project_Default.xml"
 - ".idea/misc.xml"
 - ".idea/modules.xml"
@@ -44,9 +29,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
@@ -65,6 +53,7 @@ metadata:
   homepage_uri: https://github.com/naofumi/react_router_rails_spa
   source_code_uri: https://github.com/naofumi/react_router_rails_spa
   changelog_uri: https://github.com/naofumi/react_router_rails_spa
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -83,5 +72,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