Add debounce to server side listener

README.md

@@ -20,7 +20,7 @@ Run installer:
 rails livereload:install
 ```
 
-Folders listened by default:
+Folders watched by default:
 - `app/views`
 - `app/helpers`
 - `app/javascript`
@@ -32,6 +32,12 @@ Folders listened by default:
 
 The gem detects if you use [`jsbundling-rails`](https://github.com/rails/jsbundling-rails) or [`cssbundling-rails`](https://github.com/rails/cssbundling-rails) and watches for changes in their output folder `app/assets/builds` automatically.
 
+In your layout, make sure you don't `turbo-track` your JS/CSS in development:
+```diff
++ <%= stylesheet_link_tag "application", "data-turbo-track": Rails.env.production? ? "reload" : "" %>
+- <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+```
+
 ## Configuration
 
 ### Listen paths
@@ -112,6 +118,21 @@ Rails.application.configure do
 end
 ```
 
+### Listen debounce delay
+
+If your app uses TailwindCSS or similar that compiles your CSS from looking at your templates, you can end up in a situation, where updating a template triggers twice for changes; once for the template and once for the rebuilt CSS. This can lead to unreliable reloads, ie. the reload happening before the CSS is built.
+
+To avoid this, you can add a debounce delay to the file watcher:
+
+```ruby
+# config/environments/development.rb
+
+Rails.application.configure do
+  # ...
+  config.hotwire_livereload.debounce_delay_ms = 300 # in milliseconds
+end
+```
+
 ## Disable livereload
 
 To temporarily disable livereload use:

lib/hotwire/livereload/engine.rb

@@ -16,6 +16,7 @@ class Engine < ::Rails::Engine
         #{root}/app/helpers
       ]
       config.hotwire_livereload.listen_options ||= {}
+      config.hotwire_livereload.debounce_delay_ms = 0
 
       initializer "hotwire_livereload.assets" do
         if Rails.application.config.respond_to?(:assets)
@@ -60,6 +61,14 @@ class Engine < ::Rails::Engine
 
       config.after_initialize do |app|
         if Rails.env.development? && Hotwire::Livereload.server_process?
+          @trigger_reload = (Hotwire::Livereload.debounce(config.hotwire_livereload.debounce_delay_ms) do |options|
+            if config.hotwire_livereload.reload_method == :turbo_stream
+              Hotwire::Livereload.turbo_stream(options)
+            else
+              Hotwire::Livereload.action_cable(options)
+            end
+          end)
+
           options = app.config.hotwire_livereload
           listen_paths = options.listen_paths.map(&:to_s).uniq
           force_reload_paths = options.force_reload_paths.map(&:to_s).uniq.join("|")
@@ -74,11 +83,7 @@ class Engine < ::Rails::Engine
               end
 
               options = {changed: changed, force_reload: force_reload}
-              if config.hotwire_livereload.reload_method == :turbo_stream
-                Hotwire::Livereload.turbo_stream(options)
-              else
-                Hotwire::Livereload.action_cable(options)
-              end
+              @trigger_reload.call(options)
             end
           end
           @listener.start
@@ -111,5 +116,27 @@ def self.server_process?
 
       puma_process || rails_server
     end
+
+    def self.debounce(wait_ms, &block)
+      if wait_ms.zero?
+        return ->(*args) { yield(*args) }
+      end
+
+      mutex = Mutex.new
+      timer_thread = nil
+      seconds = wait_ms.to_f / 1000.0
+
+      lambda do |*args|
+        mutex.synchronize do
+          # Cancel previous timer
+          timer_thread&.kill
+
+          timer_thread = Thread.new do
+            sleep(seconds)
+            yield(*args)
+          end
+        end
+      end
+    end
   end
 end