feat: Add helpers to enable HMR when using @vitejs/plugin-react-refresh

When using HTML entrypoints this will be injected by the plugin, but for
server-rendered templates it must be injected manually using the helper.

Author: ElMassimo

docs/guide/hanami.md

@@ -14,11 +14,7 @@
 [sourceCodeDir]: /config/#sourcecodedir
 [autoBuild]: /config/#autobuild
 [entrypoints]: /guide/development.html#entrypoints-⤵%EF%B8%8F
-[vite_client]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_hanami/lib/vite_hanami/tag_helpers.rb
-[vite_javascript]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_hanami/lib/vite_hanami/tag_helpers.rb
-[vite_typescript]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_hanami/lib/vite_hanami/tag_helpers.rb
-[vite_stylesheet]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_hanami/lib/vite_hanami/tag_helpers.rb
-[vite_asset_path]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_hanami/lib/vite_hanami/tag_helpers.rb
+[helpers]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_hanami/lib/vite_hanami/tag_helpers.rb
 [development]: /guide/development
 [vite_hanami]: https://github.com/ElMassimo/vite_ruby/tree/main/vite_hanami
 [hanami]: https://hanamirb.org/
@@ -36,10 +32,9 @@ As we saw in the [development] section, [entrypoints] will be [automatically det
 In order to link the JavaScript and CSS managed by Vite in your Hanami views or
 templates, you can use the following helpers:
 
-- <kbd>[vite_client]</kbd>: Renders the Vite client to enable Hot Module Reload.
-- <kbd>[vite_javascript]</kbd>: Render a `<script>` tag referencing a JavaScript file.
-- <kbd>[vite_typescript]</kbd>: Render a `<script>` tag referencing a TypeScript file.
-- <kbd>[vite_stylesheet]</kbd>: Render a `<link>` tag referencing a CSS file.
+- <kbd>[vite_javascript][helpers]</kbd>: Renders a `<script>` tag referencing a JavaScript file
+- <kbd>[vite_typescript][helpers]</kbd>: Renders a `<script>` tag referencing a TypeScript file
+- <kbd>[vite_stylesheet][helpers]</kbd>: Renders a `<link>` tag referencing a CSS file
 
 You can pass any options supported by <kbd>javascript</kbd> and <kbd>stylesheet</kbd>.
 
@@ -54,16 +49,25 @@ You can pass any options supported by <kbd>javascript</kbd> and <kbd>stylesheet<
 </head>
 ```
 
-For other types of assets, you can use <kbd>[vite_asset_path]</kbd> and pass the resulting URI to the appropriate tag helper.
+For other types of assets, you can use <kbd>[vite_asset_path][helpers]</kbd> and pass the resulting URI to the appropriate tag helper.
 
 ```erb
 <img src="<%= vite_asset_path 'images/logo.svg' %>" />
 <link rel="prefetch" href="<%= vite_asset_path 'typography.css' %>" />
 ```
 
+### Enabling Hot Module Reload 🔥
+
+Use the following helpers to enable HMR in development:
+
+- <kbd>[vite_client][helpers]</kbd>: Renders the Vite client to enable Hot Module Reload
+- <kbd>[vite_react_refresh][helpers]</kbd>: Only when using `@vitejs/plugin-react-refresh`
+
+They will only render if the dev server is running.
+
 ### Smart Output ✨
 
-For convenience, <kbd>[vite_javascript]</kbd> will automatically inject tags for styles or entries imported within a script.
+For convenience, <kbd>[vite_javascript][helpers]</kbd> will automatically inject tags for styles or entries imported within a script.
 
 ```erb
 <%= vite_javascript 'application' %>

docs/guide/padrino.md

@@ -14,11 +14,7 @@
 [sourceCodeDir]: /config/#sourcecodedir
 [autoBuild]: /config/#autobuild
 [entrypoints]: /guide/development.html#entrypoints-⤵%EF%B8%8F
-[vite_client_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_padrino/lib/vite_padrino/tag_helpers.rb
-[vite_javascript_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_padrino/lib/vite_padrino/tag_helpers.rb
-[vite_typescript_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_padrino/lib/vite_padrino/tag_helpers.rb
-[vite_stylesheet_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_padrino/lib/vite_padrino/tag_helpers.rb
-[vite_asset_path]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_padrino/lib/vite_padrino/tag_helpers.rb
+[helpers]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_padrino/lib/vite_padrino/tag_helpers.rb
 [development]: /guide/development
 [vite_padrino]: https://github.com/ElMassimo/vite_ruby/tree/main/vite_padrino
 [padrino]: https://padrinorb.com/
@@ -36,10 +32,9 @@ As we saw in the [development] section, [entrypoints] will be [automatically det
 In order to link the JavaScript and CSS managed by Vite in your Padrino views or
 templates, you can use the following helpers:
 
-- <kbd>[vite_client_tag]</kbd>: Renders the Vite client to enable Hot Module Reload.
-- <kbd>[vite_javascript_tag]</kbd>: Render a `<script>` tag referencing a JavaScript file.
-- <kbd>[vite_typescript_tag]</kbd>: Render a `<script>` tag referencing a TypeScript file.
-- <kbd>[vite_stylesheet_tag]</kbd>: Render a `<link>` tag referencing a CSS file.
+- <kbd>[vite_javascript_tag][helpers]</kbd>: Renders a `<script>` tag referencing a JavaScript file
+- <kbd>[vite_typescript_tag][helpers]</kbd>: Renders a `<script>` tag referencing a TypeScript file
+- <kbd>[vite_stylesheet_tag][helpers]</kbd>: Renders a `<link>` tag referencing a CSS file
 
 You can pass any options supported by <kbd>javascript</kbd> and <kbd>stylesheet</kbd>.
 
@@ -52,16 +47,25 @@ You can pass any options supported by <kbd>javascript</kbd> and <kbd>stylesheet<
   = vite_typescript_tag 'application'
 ```
 
-For other types of assets, you can use <kbd>[vite_asset_path]</kbd> and pass the resulting URI to the appropriate tag helper.
+For other types of assets, you can use <kbd>[vite_asset_path][helpers]</kbd> and pass the resulting URI to the appropriate tag helper.
 
 ```haml
 %img{ src: vite_asset_path('images/logo.svg') }
 %link{ rel: 'prefetch', href: vite_asset_path('typography.css') }
 ```
 
+### Enabling Hot Module Reload 🔥
+
+Use the following helpers to enable HMR in development:
+
+- <kbd>[vite_client_tag][helpers]</kbd>: Renders the Vite client to enable Hot Module Reload
+- <kbd>[vite_react_refresh_tag][helpers]</kbd>: Only when using `@vitejs/plugin-react-refresh`
+
+They will only render if the dev server is running.
+
 ### Smart Output ✨
 
-For convenience, <kbd>[vite_javascript_tag]</kbd> will automatically inject tags for styles or entries imported within a script.
+For convenience, <kbd>[vite_javascript_tag][helpers]</kbd> will automatically inject tags for styles or entries imported within a script.
 
 ```haml
 = vite_javascript_tag 'application'

docs/guide/rails.md

@@ -14,11 +14,7 @@
 [sourceCodeDir]: /config/#sourcecodedir
 [autoBuild]: /config/#autobuild
 [entrypoints]: /guide/development.html#entrypoints-⤵%EF%B8%8F
-[vite_client_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_rails/lib/vite_rails/tag_helpers.rb
-[vite_javascript_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_rails/lib/vite_rails/tag_helpers.rb
-[vite_typescript_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_rails/lib/vite_rails/tag_helpers.rb
-[vite_stylesheet_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_rails/lib/vite_rails/tag_helpers.rb
-[vite_asset_path]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_rails/lib/vite_rails/tag_helpers.rb
+[helpers]: https://github.com/ElMassimo/vite_ruby/blob/main/vite_rails/lib/vite_rails/tag_helpers.rb
 [development]: /guide/development
 [vite_rails]: https://github.com/ElMassimo/vite_ruby/tree/main/vite_rails
 [installed example]: https://github.com/ElMassimo/vite_ruby/tree/main/examples/rails
@@ -40,10 +36,9 @@ As we saw in the [development] section, [entrypoints] will be [automatically det
 In order to link the JavaScript and CSS managed by Vite in your Rails layouts or
 templates, you can using the following helpers:
 
-- <kbd>[vite_client_tag]</kbd>: Renders the Vite client to enable Hot Module Reload.
-- <kbd>[vite_javascript_tag]</kbd>: Render a `<script>` tag referencing a JavaScript file.
-- <kbd>[vite_typescript_tag]</kbd>: Render a `<script>` tag referencing a TypeScript file.
-- <kbd>[vite_stylesheet_tag]</kbd>: Render a `<link>` tag referencing a CSS file.
+- <kbd>[vite_javascript_tag][helpers]</kbd>: Renders a `<script>` tag referencing a JavaScript file
+- <kbd>[vite_typescript_tag][helpers]</kbd>: Renders a `<script>` tag referencing a TypeScript file
+- <kbd>[vite_stylesheet_tag][helpers]</kbd>: Renders a `<link>` tag referencing a CSS file
 
 You can pass any options supported by <kbd>javascript_include_tag</kbd> and <kbd>stylesheet_link_tag</kbd>.
 
@@ -59,7 +54,7 @@ You can pass any options supported by <kbd>javascript_include_tag</kbd> and <kbd
 </head>
 ```
 
-For other types of assets, you can use <kbd>[vite_asset_path]</kbd> and pass the resulting URI to the appropriate tag helper.
+For other types of assets, you can use <kbd>[vite_asset_path][helpers]</kbd> and pass the resulting URI to the appropriate tag helper.
 
 ```erb
 <img src="<%= vite_asset_path 'images/logo.svg' %>" />
@@ -72,9 +67,26 @@ If using `.jsx`, `.tsx`, or any other extension, make sure to be explicit:
 <%= vite_javascript_tag 'application.tsx' %>
 ```
 
+### Enabling Hot Module Reload 🔥
+
+Use the following helpers to enable HMR in development:
+
+- <kbd>[vite_client_tag][helpers]</kbd>: Renders the Vite client to enable Hot Module Reload
+- <kbd>[vite_react_refresh_tag][helpers]</kbd>: Only when using `@vitejs/plugin-react-refresh`
+
+They will only render if the dev server is running.
+
+#### Hot Reload for Stimulus Controllers
+
+If you are using [Stimulus], check out <kbd>[vite-plugin-stimulus-hmr]</kbd>.
+
+You will no longer need to refresh the page when tweaking your controllers 😃
+
+Comes installed by default in [this template][jumpstart].
+
 ### Smart Output ✨
 
-For convenience, <kbd>[vite_javascript_tag]</kbd> will automatically inject tags for styles or entries imported within a script.
+For convenience, <kbd>[vite_javascript_tag][helpers]</kbd> will automatically inject tags for styles or entries imported within a script.
 
 ```erb
 <%= vite_javascript_tag 'application' %>
@@ -93,11 +105,3 @@ When running the development server, these tags are omitted, as Vite will load t
 ```erb
 <script src="/vite/assets/application.js" type="module" crossorigin="anonymous"/>
 ```
-
-### Stimulus HMR 🔥
-
-If you are using [Stimulus], check out <kbd>[vite-plugin-stimulus-hmr]</kbd>, which provides HMR for Stimulus controllers.
-
-You will no longer need to refresh the page when tweaking your controllers 😃
-
-Comes installed by default in [this template][jumpstart].

docs/guide/troubleshooting.md

@@ -13,6 +13,8 @@
 [Using Heroku]: /guide/deployment#using-heroku
 [example app]: https://github.com/ElMassimo/vite_ruby/tree/main/examples/rails/vite.config.ts
 [windi]: /guide/plugins.html#windi-css
+[@vitejs/plugin-react-refresh]: https://www.npmjs.com/package/@vitejs/plugin-react-refresh
+[tag helpers]: /guide/development.html#tag-helpers-🏷
 
 # Troubleshooting
 
@@ -26,6 +28,19 @@ Verify that both <kbd>[vite]</kbd> and <kbd>[vite-plugin-ruby]</kbd> are in `dev
 
 If you are using a non-standard setup, try configuring <kbd>[viteBinPath]</kbd>.
 
+### Hot Module Refresh does not work for React
+
+When using <kbd>[@vitejs/plugin-react-refresh]</kbd> in non-HTML entrypoints,
+you must explicitly [register the HMR plugin](https://github.com/vitejs/vite/issues/1984#issuecomment-778289660).
+
+A [<kbd>vite_react_refresh_tag</kbd> helper][tag helpers] is provided for your convenience:
+
+```erb
+  <%= vite_client_tag %>
+  <%= vite_react_refresh_tag %>
+  <%= vite_javascript_tag 'application' %>
+```
+
 ### Making HMR work in Docker Compose
 
 Using Vite.js with Docker Compose requires configuring [`VITE_RUBY_HOST`][host] in the services.

test/helper_test.rb

@@ -27,6 +27,21 @@ def test_vite_client_tag
     }
   end
 
+  def test_vite_react_refresh_tag
+    assert_nil vite_react_refresh_tag
+    with_dev_server_running {
+      assert_equal <<~HTML, vite_react_refresh_tag
+        <script type="module">
+          import RefreshRuntime from '/vite-production/@react-refresh'
+          RefreshRuntime.injectIntoGlobalHook(window)
+          window.$RefreshReg$ = () => {}
+          window.$RefreshSig$ = () => (type) => type
+          window.__vite_plugin_react_preamble_installed__ = true
+        </script>
+      HTML
+    }
+  end
+
   def test_vite_asset_path
     assert_equal '/vite-production/assets/application.d9514acc.js', vite_asset_path('application.ts')
     assert_equal '/vite-production/assets/styles.0e53e684.css', vite_asset_path('styles.css')

vite_hanami/lib/vite_hanami/installation.rb

@@ -16,7 +16,7 @@ def setup_app_files
       # Allow @vite/client to hot reload changes in development
       security.content_security_policy(
         security.content_security_policy
-          .sub('script-src', "script-src 'unsafe-eval'")
+          .sub('script-src', "script-src 'unsafe-eval' 'unsafe-inline'")
           .sub('connect-src', "connect-src ws://\#{ ViteRuby.config.host_with_port }")
       )
     CSP

vite_hanami/lib/vite_hanami/tag_helpers.rb

@@ -9,6 +9,12 @@ def vite_client
     html.script(src: src, type: 'module')
   end
 
+  # Public: Renders a script tag to enable HMR with React Refresh.
+  def vite_react_refresh
+    tag = vite_manifest.react_refresh_preamble
+    raw(tag) if tag
+  end
+
   # Public: Resolves the path for the specified Vite asset.
   #
   # Example:

vite_padrino/lib/vite_padrino/tag_helpers.rb

@@ -9,6 +9,11 @@ def vite_client_tag
     content_tag(:script, nil, src: src, type: 'module')
   end
 
+  # Public: Renders a script tag to enable HMR with React Refresh.
+  def vite_react_refresh_tag
+    vite_manifest.react_refresh_preamble&.html_safe
+  end
+
   # Public: Resolves the path for the specified Vite asset.
   #
   # Example:

vite_rails/lib/vite_rails/tag_helpers.rb

@@ -9,6 +9,11 @@ def vite_client_tag
     tag.script(src: src, type: 'module')
   end
 
+  # Public: Renders a script tag to enable HMR with React Refresh.
+  def vite_react_refresh_tag
+    vite_manifest.react_refresh_preamble&.html_safe
+  end
+
   # Public: Resolves the path for the specified Vite asset.
   #
   # Example:

vite_rails_legacy/lib/vite_rails_legacy/tag_helpers.rb

@@ -9,6 +9,11 @@ def vite_client_tag
     "<script#{ tag_options({ src: src, type: 'module' }, escape: true) }></script>".html_safe
   end
 
+  # Public: Renders a script tag to enable HMR with React Refresh.
+  def vite_react_refresh_tag
+    vite_manifest.react_refresh_preamble&.html_safe
+  end
+
   # Public: Resolves the path for the specified Vite asset.
   #
   # Example: