turbo-hmr 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6f12eb486a159355c025fa656c8c3e764379bb6e38c4af5cbc4e3cc3eeaa263
+  data.tar.gz: 6965f4bcb66437567a8a8cbd237de05db207f0f4f5e63fba2db330e28bb4a282
+SHA512:
+  metadata.gz: 80061ae7f2144ad3e1c54c016c7567d9c8b6b998ff319c0d8d14f4271690bf0bc03c697dcebb59636f6d50d89fc2bd11b8504d44e5fa87924b83076a078fdff3
+  data.tar.gz: 023375f245a878be95e8a633db97eb711392825ae9eea5554970e65ab9de5ba2d5a0222147b23bc34aa55929c3ba84732299dd62d45d87307885cee153a1268a

data/.ruby-gemset

@@ -0,0 +1 @@
+turbo-hmr

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.4.7

data/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+turbo-hmr is a Ruby gem that provides Hot Module Replacement (HMR) for Turbo with Importmap. It detects when pinned Stimulus controller modules change across Turbo-driven navigations and attempts to hot-swap them without triggering a full page reload.
+
+## Architecture
+
+The gem has two main components that work together:
+
+**Ruby/Rails side:**
+- `lib/turbo/hmr/engine.rb` - Rails Engine that sets up asset paths and registers helpers
+- `lib/turbo/hmr/importmap_helper.rb` - Overrides the default `javascript_inline_importmap_tag` to remove `data-turbo-track="reload"` attribute, which is essential for HMR to intercept importmap changes
+- `lib/generators/turbo/hmr/install_generator.rb` - Generator that configures the host application
+
+**JavaScript side:**
+- `app/javascript/turbo-hmr.js` - Core HMR logic that:
+  - Listens to `turbo:before-fetch-response` to extract the incoming page's importmap
+  - Compares importmaps in `turbo:before-render` to detect changes
+  - Hot-swaps changed Stimulus controllers by calling `application.unload()` and `application.register()` with re-imported modules
+  - Falls back to full reload via `Turbo.visit()` if non-controller imports change or hot-swap fails
+  - Only hot-swaps modules matching `controllers/*` pattern (configurable via `isControllerImport()`)
+
+**Key flow:**
+1. Importmap helper removes `data-turbo-track` attribute to prevent automatic reloads
+2. JavaScript intercepts Turbo navigation events to compare old vs new importmaps
+3. If only controllers changed: hot-swap them without page reload
+4. If anything else changed: trigger full reload
+
+## Development Commands
+
+**Run tests:**
+```bash
+bundle exec rspec
+```
+
+**Run specific test:**
+```bash
+bundle exec rspec spec/system/hotswap_system_spec.rb
+```
+
+**Run single focused test:**
+```bash
+bundle exec rspec spec/system/hotswap_system_spec.rb:<line_number>
+```
+
+## Testing
+
+The gem uses RSpec with system tests powered by Capybara and Cuprite (headless Chrome driver). The test suite includes a dummy Rails app in `spec/dummy/` that simulates a real Rails application with Turbo and Stimulus.
+
+System tests verify HMR behavior by:
+- Modifying controller files at runtime (`write_version_controller`)
+- Navigating between pages with Turbo
+- Verifying controllers hot-swap without full page reloads
+- Checking page load counts using custom `have_been_loaded` matcher
+
+The dummy app is essential for testing - it's not just scaffolding but a functioning Rails app that exercises the actual HMR flow.
+
+## Important Constraints
+
+- Hot-swapping only works for Stimulus controllers (modules under `controllers/` in importmap)
+- Controllers must be safe to re-import (no problematic side-effects during module evaluation)
+- Requires importmap entries to include cache-busting digests (Rails default in development/test)
+- The `data-turbo-track="reload"` attribute MUST be removed from importmap script tags

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Micah Geisel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,64 @@
+# turbo-hmr
+
+Hot Module Replacement for Turbo with Importmap.
+
+This gem detects when pinned Stimulus controller modules change across a Turbo-driven navigation (e.g., `Turbo.visit`). If the new page’s importmap updates any Stimulus controllers, the gem attempts to swap in the updated controllers without a full page reload by:
+
+- Disconnecting existing controller instances for the changed identifiers
+- Re-importing the updated modules
+- Re-registering/reconnecting controllers so instances start using the new code
+- Preventing the full page reload
+
+If any changed importmap item can’t be safely hot-swapped, we fall back upon the default Turbo.visit behavior to ensure correctness.
+
+## Why
+
+More seamless deployments for long-lived single-page sessions.
+
+Turbo’s morphing normally keeps you on the page without a full reload, but the browser doesn’t automatically re-import modules whose specifiers are unchanged while their URLs in the importmap have changed, and instead just does a full page load. This gem bridges that gap by watching for importmap diffs and applying a targeted hot swap.
+
+## How It Works
+
+This gem disables Turbo's built-in `data-turbo-track="reload"` behavior for importmaps and replaces it with smarter logic:
+
+1. During Turbo navigations, it intercepts `turbo:before-fetch-response` to extract the incoming page's importmap
+2. In `turbo:before-render`, it compares importmaps and detects what changed
+3. If only Stimulus controllers changed, it hot-swaps them without a full page reload
+4. Controllers are hot-swapped by calling `Stimulus.unload()` and `Stimulus.register()` with the new module
+5. If any non-controller imports changed, it triggers a full reload via `Turbo.visit()`
+
+**Caveat emptor: This process assumes that all stimulus controllers can be safely unloaded and reloaded without problematic side-effects. Users of this gem need to ensure that their controllers are safe to re-import!**
+
+## Installation
+
+1. Add to your Gemfile:
+
+   ```ruby
+   gem "turbo-hmr"
+   ```
+
+2. Run the installer:
+
+   ```bash
+   bin/rails generate turbo:hmr:install
+   ```
+
+   This will:
+   - Pin the `turbo-hmr` JavaScript module in `config/importmap.rb`
+   - Set it up in `app/javascript/application.js`
+
+## Limitations
+
+- Only swaps Stimulus controllers; other module changes will trigger a full page reload.
+- Assumes that controllers do not have problematic side-effects during module evaluation. The onus is upon the user of this gem to ensure their controllers are safe to re-import.
+- Assumes importmap entries include cache-busting digests when files change (Rails does this by default in development/test).
+- Requires disabling `data-turbo-track="reload"` on the importmap script tag (this gem monkeypatches importmaps-rails to do this).
+
+## Roadmap
+
+- Configurable module matching (allow/deny lists)
+- Opt-in HMR for non-controller modules
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/javascript/turbo-hmr.js

@@ -0,0 +1,149 @@
+class TurboHmr {
+  constructor() {
+    this.currentImportmap = null
+    this.application = null
+    this.pendingImportmap = null
+    this.changes = { controllers: [], others: [] }
+  }
+
+  start(application) {
+    this.application = application
+    this.currentImportmap = this.extractImportmap(document)
+
+    document.addEventListener("turbo:before-fetch-response", this.handleBeforeFetchResponse.bind(this))
+    document.addEventListener("turbo:before-render", this.handleBeforeRender.bind(this))
+  }
+
+  async handleBeforeFetchResponse(event) {
+    const response = event.detail.fetchResponse
+    const html = await response.responseHTML
+    const parser = new DOMParser()
+    const doc = parser.parseFromString(html, "text/html")
+    this.pendingImportmap = this.extractImportmap(doc)
+  }
+
+  handleBeforeRender(event) {
+    if (!this.pendingImportmap || !this.currentImportmap) return
+
+    this.detectChanges(this.currentImportmap, this.pendingImportmap)
+
+    // console.log("turbo-hmr: changes:", this.changes)
+
+    if (this.changes.others.length > 0) {
+      // console.log("turbo-hmr: Non-controller imports changed, triggering reload")
+      event.preventDefault()
+      location.reload()
+
+    } else if (this.changes.controllers.length > 0) {
+      // console.log("turbo-hmr: Hot-swapping controllers:", this.changes.controllers)
+
+      // Unload removed controllers before render
+      const removedControllers = this.changes.controllers.filter(c => c.newUrl === null)
+      for (const change of removedControllers) {
+        this.unloadController(change.identifier)
+      }
+
+      // Reload added/changed controllers after render
+      requestAnimationFrame(() => {
+        const addedOrChangedControllers = this.changes.controllers.filter(c => c.newUrl !== null)
+        Promise.all(addedOrChangedControllers.map(change =>
+          this.reloadController(change.identifier, change.newUrl)
+        ))
+          .then(() => {
+            // console.log("turbo-hmr: successfully hot-swapped controllers")
+            this.currentImportmap = this.pendingImportmap
+          })
+          .catch(error => {
+            console.error("turbo-hmr: Failed to hot-swap controllers", error)
+            location.reload()
+          })
+      })
+    } else {
+      this.currentImportmap = this.pendingImportmap
+    }
+  }
+
+  extractImportmap(doc) {
+    const importmapScript = doc.querySelector('script[type="importmap"]')
+    if (!importmapScript) return null
+
+    try {
+      return JSON.parse(importmapScript.textContent)
+    } catch (e) {
+      console.error("turbo-hmr: Failed to parse importmap", e)
+      return null
+    }
+  }
+
+  detectChanges(oldMap, newMap) {
+    this.changes = { controllers: [], others: [] }
+
+    for (const [identifier, url] of Object.entries(newMap.imports)) {
+      const oldUrl = oldMap.imports[identifier]
+      const isController = this.isControllerImport(identifier)
+
+      if (!oldUrl) {
+        // Added
+        const change = { identifier, oldUrl: null, newUrl: url }
+        isController ? this.changes.controllers.push(change) : this.changes.others.push(change)
+      } else if (oldUrl !== url) {
+        // Changed
+        const change = { identifier, oldUrl, newUrl: url }
+        isController ? this.changes.controllers.push(change) : this.changes.others.push(change)
+      }
+    }
+
+    // Removed
+    for (const [identifier, url] of Object.entries(oldMap.imports)) {
+      if (!newMap.imports[identifier]) {
+        const isController = this.isControllerImport(identifier)
+        const change = { identifier, oldUrl: url, newUrl: null }
+        isController ? this.changes.controllers.push(change) : this.changes.others.push(change)
+      }
+    }
+  }
+
+  isControllerImport(identifier) {
+    return identifier.startsWith("controllers/")
+  }
+
+  async hotSwapControllers() {
+    for (const change of this.changes.controllers) {
+      if (change.newUrl) {
+        await this.reloadController(change.identifier, change.newUrl)
+      } else {
+        await this.unloadController(change.identifier)
+      }
+    }
+  }
+
+  async reloadController(identifier, url) {
+    const controllerName = this.identifierToControllerName(identifier)
+    const module = await import(url)
+    this.application.unload(controllerName)
+    this.application.register(controllerName, module.default)
+    // console.log(`turbo-hmr: Reloaded controller "${controllerName}" from ${url}`)
+  }
+
+  async unloadController(identifier) {
+    const controllerName = this.identifierToControllerName(identifier)
+    this.application.unload(controllerName)
+    // console.log(`turbo-hmr: Unloaded controller "${controllerName}"`)
+  }
+
+  identifierToControllerName(identifier) {
+    // "controllers/version_controller" => "version"
+    // "controllers/admin/users_controller" => "admin--users"
+    return identifier
+      .replace("controllers/", "")
+      .replace("_controller", "")
+      .replace(/\//g, "--")
+      .replace(/_/g, "-")
+  }
+}
+
+const hotswap = new TurboHmr()
+export function start(application) {
+  hotswap.start(application)
+}
+export default { start }

data/lib/generators/turbo/hmr/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Installs turbo-hmr into your Rails application.
+
+    This generator will:
+    - Create an initializer to disable data-turbo-track on the importmap
+    - Pin the turbo_hmr module in config/importmap.rb
+    - Add the import to app/javascript/application.js
+
+Example:
+    bin/rails generate turbo:hmr:install

data/lib/generators/turbo/hmr/install_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Turbo
+  module Hmr
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Installs turbo-hmr"
+
+        def update_importmap
+          append_to_file "config/importmap.rb", %(pin "turbo-hmr", to: "turbo-hmr.js"\n)
+        end
+
+        def update_application_js
+          application_js_path = "app/javascript/application.js"
+
+          # Read the existing content to determine where to add the code
+          if File.exist?(application_js_path)
+            content = File.read(application_js_path)
+
+            # Add the import at the top if not already present
+            unless content.include?('from "turbo-hmr"')
+              prepend_to_file application_js_path, "import { start as startTurboHmr } from \"turbo-hmr\"\n"
+            end
+
+            # Add the start call after Stimulus is initialized
+            unless content.include?("startTurboHmr")
+              # Try to add after Application.start() or window.Stimulus assignment
+              if content.match(/(?:const|let|var)\s+(\w+)\s*=.*Application\.start\(\)/)
+                app_var = Regexp.last_match(1)
+                inject_into_file application_js_path, "\nstartTurboHmr(#{app_var})\n",
+                  after: /#{app_var}\s*=.*Application\.start\(\)/
+              elsif content.match(/window\.Stimulus\s*=.*Application\.start\(\)/)
+                inject_into_file application_js_path, "\nstartTurboHmr(window.Stimulus)\n",
+                  after: /window\.Stimulus\s*=.*Application\.start\(\)/
+              else
+                append_to_file application_js_path, "\n// Start turbo-hmr (adjust the application variable name as needed)\n// startTurboHmr(application)\n"
+              end
+            end
+          else
+            create_file application_js_path, <<~JS
+              import { start as startTurboHmr } from "turbo-hmr"
+              import { Application } from "@hotwired/stimulus"
+
+              const application = Application.start()
+              startTurboHmr(application)
+            JS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/turbo/hmr/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Turbo
+  module Hmr
+    class Engine < ::Rails::Engine
+      isolate_namespace Turbo::Hmr
+
+      initializer "turbo_hmr.assets" do |app|
+        app.config.assets.paths << root.join("app/javascript")
+        app.config.assets.precompile += %w[turbo-hmr.js]
+      end
+
+      initializer "turbo_hmr.importmap_helper" do
+        ActiveSupport.on_load(:action_controller) do
+          helper Turbo::Hmr::ImportmapHelper
+        end
+      end
+    end
+  end
+end

data/lib/turbo/hmr/importmap_helper.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Turbo
+  module Hmr
+    module ImportmapHelper
+      # Override importmap helper to not add data-turbo-track to the importmap script
+      # This allows turbo-hmr to handle importmap changes without full page reloads
+      def javascript_inline_importmap_tag(importmap_json = Rails.application.importmap.to_json(resolver: self))
+        tag.script importmap_json.html_safe,
+          type: "importmap", nonce: request&.content_security_policy_nonce
+      end
+    end
+  end
+end

data/lib/turbo/hmr/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Turbo
+  module Hmr
+    VERSION = "0.0.1"
+  end
+end

data/lib/turbo/hmr.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "hmr/version"
+require_relative "hmr/engine"
+require_relative "hmr/importmap_helper"
+
+module Turbo
+  module Hmr
+    class Error < StandardError; end
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: turbo-hmr
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Micah Geisel
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Enables HMR (Hot Module Replacement) for ES modules during Turbo navigations,
+  with special support for Stimulus controllers.
+email:
+- micah@botandrose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-gemset"
+- ".ruby-version"
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/javascript/turbo-hmr.js
+- lib/generators/turbo/hmr/USAGE
+- lib/generators/turbo/hmr/install_generator.rb
+- lib/turbo/hmr.rb
+- lib/turbo/hmr/engine.rb
+- lib/turbo/hmr/importmap_helper.rb
+- lib/turbo/hmr/version.rb
+homepage: https://github.com/botandrose/turbo-hmr
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/botandrose/turbo-hmr
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Hot Module Replacement for Turbo
+test_files: []