react_router_rails_spa 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8b4be06b2470f7ece193c99c21dca1af7ae3856591399c8e16b6170bcc54c9e
-  data.tar.gz: b845de80454767f463266504cff5028f098d9de7bb4837ff3de0d310c08ef5a5
+  metadata.gz: 95855ba78c935cea1d1c666a75769bf23dca4b3593b6837f29ceb2d97c3259b2
+  data.tar.gz: b4f53bab792448b9a8a1f7df9d6b02a37680425ab51fcdde40cc90c3b3d7dc50
 SHA512:
-  metadata.gz: 17b47b7846d437d18bc48ff589f183b5a7b1a8d7e9406cd34ff9a3e19eab5d388facdbcb1685bf3df56a52a81e3300eb50fe6fbcbd627e73233f7eb1028d7633
-  data.tar.gz: e781941c2404d2e5f7e41be2249cb3ed17fc56d3975d1a6d23324b02d1cf2b7fc05f9f3ed0784de29319dbcc18c9f7c2e9fa5e46445b40bb555d2a99c1e2937f
+  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,40 +1,34 @@
 ## React Router SPA Framework mode integration for Ruby on Rails
 
 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.
 
-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.
+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.
 
-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.
+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.  
 
- 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.
+[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 you fit any of the following descriptions.
+Consider trying out this gem if any of the below apply to you.
 
-- 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 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
 
-The React Router application will be installed inside the `frontend` directory. We assume that you have an existing Ruby on Rails application.
+We assume that you already have an existing Ruby on Rails application.
 
 Add this line to your application's Gemfile:
 
@@ -46,48 +40,52 @@ 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.
-It will also create a React bootstrap endpoint for all paths starting with `/react`.
-The endpoint will be handled by `ReactController#show`.
+This is where your React application is.
 
-You will also have rake tasks for starting the dev server and building/previewing the React app.
-
-As part of the integration, we provide utilities for using the robust CSRF protection built into Ruby on Rails from your React application.
+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
 
-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. 
+React Router is built with Vite and uses the Vite development server to provide a Hot Module Replacement (HMR) capability.
 
-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`).
+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
 ```
 
-Access the development server from the URL outputted from this command (Typically `http://localhost:5173/react`)
+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.
 
 To preview the production build, run the following command.
 ```shell
 bin/rails react_router:preview
 ```
 
-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.
+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.
-
-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.
+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.
+then install it in your CI/CD environment since building the React Router application will require it. 
 
 ## Background
 
@@ -128,6 +126,7 @@ Importantly, API mode implies a stateless API server that does not support cooki
 It removes the middleware for cookie handling and also for CSRF protection.
 
 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.
 

data/documents/introduction.md

@@ -2,42 +2,63 @@
 
 ## 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.
+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.
 
-To jump to the installation steps, go to the "Steps to Integrate React Router into your Rails Application" section.
+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?
 
-The react_router_rails_spa gem was designed for the following situations.
+If any of the following describes yourself, then this gem might be for you.
 
-### You want to create a web application with a React frontend and a Rails backend.
+### 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. 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 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 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 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). 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.
+* 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 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.
+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 React because you believe you can create better UIs
+### You want to use cutting-edge React
 
-* 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.
+* 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 [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).
+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 therefore more robust if you are using Hotwire in your ERB views.
+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
 
@@ -50,9 +71,9 @@ Importantly, and often lost in the public discourse, they were **NOT** recommend
 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"**
+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, I will call the ones that the React team is actively discouraging, **"Legacy React SPAs"**.
+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.
@@ -79,7 +100,7 @@ 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.
+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.
@@ -93,9 +114,9 @@ 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.
+As far as we 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).
+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
 
@@ -126,51 +147,41 @@ This is how the react_router_rails_spa 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
+**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.
 
-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.
+### React Router SPA framework mode
 
-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.
+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.
 
-### Rails routes.rb and the ReactController
+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.
 
-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.
+### Integration with Ruby on Rails through cookies
 
-`ReactController` will also add session cookies so that you can take advantage of session information from the bootstrap HTML file onwards.
+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.
 
-Finally, the `ReactController` allows you to set cache headers separately from assets served directly from the `assets` folder.
+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.
 
-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. 
+Neither approach is ideal.
 
-Another way to look at this integration is like this;
+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.
 
-* 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.
+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
 
@@ -191,31 +202,13 @@ 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.
+* 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. I recommend that you read through it to understand the setup in more detail.
+The source code is heavily commented. We recommend that you read through it to understand the setup in more detail.
 
 ## Using the gem
 
@@ -227,8 +220,16 @@ This gem works with a pre-existing installation of Rails. Create a new Rails app
 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.
+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
 
@@ -257,7 +258,7 @@ 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).
+Run the following command to start the frontend development server with HMR (Hot Module Replacement).
 
 ```shell
 bin/rails react_router:dev
@@ -265,7 +266,11 @@ bin/rails react_router:dev
 
 Point your browser to http://localhost:5173/react/ to see the welcome page.
 
-### Build the React Router application
+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.
@@ -274,17 +279,15 @@ and store the static files into the Rails `public` directory.
 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`.
+This command is also aliased as:
 
 ```shell
 bin/rails react_router:preview
 ```
 
-### Read the added code
+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
 
-I have added numerous comments to the code generated by this gem. Please read it to understand how the integration works.
+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/generators/templates/react.rake

@@ -18,7 +18,7 @@ namespace :react_router do
   #
   # bin/rails react_router:dev
   desc "Start React Router Development Server with Hot Module Reloading"
-  task dev: [:npm_install] do
+  task dev: [ :npm_install ] do
     puts "Starting React Router v7 app development server..."
     Dir.chdir("#{Dir.pwd}/frontend") do
       system("npm", "run", "dev")
@@ -27,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")
@@ -42,7 +42,7 @@ namespace :react_router do
   #
   # bin/rails react_router:build
   desc "Build React Router App and move to the public folder"
-  task build: [:npm_install] do
+  task build: [ :npm_install ] do
     puts "Building React Router v7 app..."
     `cd frontend && npm run build`
 
@@ -59,7 +59,7 @@ namespace :react_router do
   # 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]
+  task preview: [ :build ]
 
   # Run bin/rails react_router:clobber to remove the build files.
   # Running bin/rails assets:clobber will also run this task.
@@ -75,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/welcome/welcome.tsx

@@ -61,7 +61,7 @@ const resources = [
     text: "Read the README for the react_router_rails_spa gem",
   },
   {
-    href: "https://github.com/naofumi/react_router_rails_spa/documentation/introduction.md",
+    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",
   },
   {
@@ -69,7 +69,7 @@ const resources = [
     text: "Read the React Router Docs",
   },
   {
-    href: "https://reactrouter.com/docs",
+    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.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: react_router_rails_spa
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Naofumi Kagami
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-20 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
@@ -67,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: