rspack_rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d38b564f0260e86ab95775b11d6435853d520922028c59c3acce6c7ad1af639b
-  data.tar.gz: 062aff2e71411f542808ec77ed5054935040ec6018a1a3839ba374b2cfd10dc2
+  metadata.gz: d5c0f485458181960a59600c16b354bbb260d5856d37200ffaf416e4d6c88222
+  data.tar.gz: a06bf0ec56b0850342ea39c4d461f4d165e8b3c1f046c7c41d6149b5412c5fbe
 SHA512:
-  metadata.gz: 0d1ab868d62a2ce92bb0cf1f330f4113e311658fea8e0174f50ef73c001fa7f67ccb580094bdb7f805606026536b7a3580ece740dd4f88d3b946baa32e84883a
-  data.tar.gz: c919c924784fb9885e4b8c9b8ae5db4255475adb9fd915a71e1a7a882a20bd02d6cf6c0eb2120928d7c89a0b214676ec3ddf92b1e785f48a89059e5e9ed02bd5
+  metadata.gz: 70886ccbe82932f10548639cb3190b4a06ad032fa854c5677c87553c93d4a32feb4a9968a5b72881fa5cfb94833ca02994168a541771c95a33222d51422677f4
+  data.tar.gz: 989663562bc6cd2e8a72ef05872319117c5f21e9b43697fc57874ea6c725370a86118ec3e01bd950f854dddbc57d48a8e9f10b675f2ef0686c1126df93573203

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-11-13
+
+- `rspack:migrate`: moves an importmap-rails or jsbundling-rails (esbuild/webpack/rollup) app to rspack. Requires a clean git tree (or `FORCE=1`)
+- `rspack.config.mjs` resolves bare imports from `app/javascript` (`resolve.modules`), so importmap-style `import "controllers/application"` keeps working
+- `rspack:install:stimulus` also rewrites a bare `import "controllers"`
+- Installers stop when a package install fails instead of carrying on
+
 ## [0.3.0] - 2026-11-13
 
 - Multiple entry points: every `app/javascript/entrypoints/*.{js,ts}` becomes a bundle named after the file; `application.ts` works as the main entry

data/README.md

@@ -1,8 +1,24 @@
 # rspack_rails
 
-Bundle your Rails app's JavaScript with [Rspack](https://rspack.rs), the Rust-powered, webpack-compatible bundler.
+[![Gem Version](https://img.shields.io/gem/v/rspack_rails)](https://rubygems.org/gems/rspack_rails)
+[![CI](https://github.com/tungnt1203/rspack_rails/actions/workflows/main.yml/badge.svg)](https://github.com/tungnt1203/rspack_rails/actions/workflows/main.yml)
 
-rspack_rails follows the `jsbundling-rails` model: rspack writes bundles to `app/assets/builds`, and Propshaft (or Sprockets) serves and fingerprints them.
+Bundle your Rails app's JavaScript and CSS with [Rspack](https://rspack.rs), the Rust-powered, webpack-compatible bundler, and get **hot module replacement** in development.
+
+![Editing CSS and a Stimulus controller while the page keeps its state](docs/hmr.gif)
+
+*Above: CSS and a Stimulus controller are edited while the page is open. Both update in place, and the counter keeps its value because the page never reloads.*
+
+- **One command setup**: `bin/rails rspack:install`, then `bin/dev`
+- **HMR for JavaScript, CSS and Stimulus controllers**, with an automatic fallback to the asset pipeline when the dev server is not running
+- **Stimulus autoloading**: drop a `*_controller.js` (or `.ts`) in `app/javascript/controllers`, no manifest to maintain
+- **TypeScript and CSS modules** out of the box, through Rspack's built-in SWC and native CSS
+- **Multiple entry points** from `app/javascript/entrypoints/`
+- **`rspack:migrate`** moves an importmap or jsbundling app over in one command
+- **`rspack:doctor`** checks Node.js, packages, config and layout, and says what to fix
+- Works with **Propshaft and Sprockets**; CI runs a real app on Rails 7.2 and 8.1
+
+rspack_rails follows the `jsbundling-rails` model: rspack writes bundles to `app/assets/builds`, and Propshaft (or Sprockets) serves and fingerprints them in production.
 
 ## Installation
 
@@ -19,6 +35,28 @@ The installer:
 - adds a `js:` process running the dev server to `Procfile.dev` and sets up `bin/dev`
 - installs `@rspack/cli`, `@rspack/core` and `@rspack/dev-server` with your package manager (bun, yarn, pnpm or npm, detected from the lockfile)
 
+## Migrating from importmap or jsbundling
+
+```bash
+git commit -am "Before rspack"     # rspack:migrate refuses to run on a dirty tree (FORCE=1 to override)
+bin/rails rspack:migrate
+git diff                           # review
+bin/dev
+```
+
+**From importmap-rails**
+- Every `pin` in `config/importmap.rb` becomes an npm dependency. Versions recorded by importmap (`# @1.2.3` or jspm URLs) are kept. Gem-served pins such as Turbo install the latest npm release.
+- `javascript_importmap_tags` is replaced with `rspack_javascript_tag`, and `import "controllers"` with the Stimulus autoloader.
+- `config/importmap.rb`, `bin/importmap`, vendored packages, the `importmap-rails` gem, `stale_when_importmap_changes` and the `bin/importmap audit` CI step are removed.
+- Bare imports of app code (`import "controllers/application"`) keep working through `resolve.modules`.
+
+**From jsbundling-rails** (esbuild, webpack, rollup)
+- The `jsbundling-rails` gem, the old bundler package and its config file are removed. `Procfile.dev` runs the rspack dev server.
+- `javascript_include_tag "application"` becomes `rspack_javascript_tag`, and the generated `controllers/index.js` gives way to the autoloader.
+- Extra entry files in the root of `app/javascript/` are listed so you can move them to `app/javascript/entrypoints/`.
+
+The task finishes by listing any remaining lines that mention importmap or jsbundling. Shakapacker/Webpacker apps are not supported yet.
+
 ## Usage
 
 Run `bin/dev` to start Rails and the rspack dev server (with hot module replacement) together.
@@ -112,6 +150,7 @@ npm run typecheck
 |---|---|
 | `bin/rails rspack:install:stimulus` | Sets up Stimulus with controller autoloading |
 | `bin/rails rspack:install:typescript` | Adds tsconfig.json, typescript and a `typecheck` script |
+| `bin/rails rspack:migrate` | Moves an importmap or jsbundling app to rspack |
 | `bin/rails rspack:doctor` | Checks Node.js, packages, config, layout, Procfile and dev server |
 | `bin/rails rspack:build` | Installs JS dependencies, then runs `build` |
 | `bin/rails rspack:clobber` | Removes rspack output from `app/assets/builds` |
@@ -143,6 +182,7 @@ bin/setup
 bundle exec rake   # specs + rubocop
 bin/integration    # new Rails app + every installer, build, doctor and precompile
 bin/integration "~> 7.2.0"   # against a specific Rails version
+bin/integration-migrate importmap    # rails new + rspack:migrate (or: jsbundling)
 ```
 
 ## License

data/lib/install/install.rb

@@ -68,6 +68,6 @@ unless File.exist?("bin/dev") && File.read("bin/dev").include?("Procfile.dev")
 end
 
 say "Installing @rspack/cli, @rspack/core and @rspack/dev-server"
-run pm.add_dev_command("@rspack/cli", "@rspack/core", "@rspack/dev-server")
+run pm.add_dev_command("@rspack/cli", "@rspack/core", "@rspack/dev-server"), abort_on_failure: true
 
 say "rspack_rails installed. Run bin/dev to start developing.", :green

data/lib/install/migrate.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# Rails application template run by `bin/rails rspack:migrate`.
+# Moves an app from importmap-rails or jsbundling-rails to rspack_rails.
+require "json"
+
+migration = RspackRails::Migration.new(Rails.root)
+pm = RspackRails::PackageManager.detect(Rails.root)
+layout = "app/views/layouts/application.html.erb"
+stimulus = File.exist?("app/javascript/controllers/application.js")
+
+def remove_gem(name)
+  gem_line = /^[ \t]*gem[ \t]+["']#{Regexp.escape(name)}["'].*\n/
+  gsub_file "Gemfile", /^[ \t]*#.*\n(?=#{gem_line.source})/, "" # the comment describing it
+  gsub_file "Gemfile", gem_line, ""
+end
+
+case migration.source
+when :rspack
+  say "This app already uses rspack_rails. Run `bin/rails rspack:doctor` to check it.", :green
+  exit
+when :shakapacker
+  say "Shakapacker/Webpacker apps are not supported by rspack:migrate yet.", :red
+  exit 1
+when :none
+  say "No importmap-rails or jsbundling-rails setup found. Running rspack:install instead."
+when :importmap
+  say "Migrating from importmap-rails"
+  packages = migration.npm_install_args
+  vendored = migration.vendored_files
+
+  gsub_file layout, /^\s*<%= javascript_importmap_tags.*%>\n/, "" if File.exist?(layout)
+  if File.exist?("app/assets/config/manifest.js")
+    gsub_file "app/assets/config/manifest.js", %r{^//= link_tree \.\./\.\./javascript .js\n}, ""
+    gsub_file "app/assets/config/manifest.js", %r{^//= link_tree \.\./\.\./\.\./vendor/javascript .js\n}, ""
+  end
+  if File.exist?("app/javascript/application.js")
+    gsub_file "app/javascript/application.js", %r{^// Configure your import map in config/importmap.rb.*\n}, ""
+  end
+  Dir.glob("app/controllers/**/*.rb").each do |controller|
+    next unless File.read(controller).include?("stale_when_importmap_changes")
+
+    gsub_file controller, /^[ \t]*# Changes to the importmap will invalidate the etag.*\n/, ""
+    gsub_file controller, /^[ \t]*stale_when_importmap_changes.*\n/, ""
+  end
+  gsub_file "config/ci.rb", %r{^[ \t]*step .*bin/importmap audit.*\n}, "" if File.exist?("config/ci.rb")
+  remove_file "config/importmap.rb"
+  remove_file "bin/importmap"
+  vendored.each { |path| remove_file path }
+  remove_gem "importmap-rails"
+when :jsbundling
+  say "Migrating from jsbundling-rails"
+  bundlers = migration.bundler_packages
+  migration.bundler_configs.each { |path| remove_file path }
+  gsub_file "Procfile.dev", /^js: .*\n/, "js: #{pm.run_command("dev")}\n" if File.exist?("Procfile.dev")
+  remove_gem "jsbundling-rails"
+end
+
+apply "#{__dir__}/install.rb"
+
+if migration.source == :importmap && packages.any?
+  say "Installing packages that were pinned in config/importmap.rb: #{packages.join(", ")}"
+  run pm.add_command(*packages), abort_on_failure: true
+end
+
+if migration.source == :jsbundling && bundlers.any?
+  say "Removing the previous bundler: #{bundlers.join(", ")}"
+  package = JSON.parse(File.read("package.json"))
+  bundlers.each do |name|
+    package["dependencies"]&.delete(name)
+    package["devDependencies"]&.delete(name)
+  end
+  File.write("package.json", "#{JSON.pretty_generate(package)}\n")
+end
+
+apply "#{__dir__}/stimulus.rb" if stimulus
+
+controllers_index = "app/javascript/controllers/index.js"
+if migration.source == :importmap && File.exist?(controllers_index) &&
+   File.read(controllers_index).include?("@hotwired/stimulus-loading")
+  remove_file controllers_index # replaced by controllers/autoload.js
+end
+
+if migration.source == :jsbundling
+  migration.extra_root_entries.each do |path|
+    say "#{path} was an entry point under jsbundling. Move it to app/javascript/entrypoints/ " \
+        "so rspack builds it.", :yellow
+  end
+end
+
+leftovers = Dir.glob("{app,config,lib}/**/*.{rb,erb,js,ts,yml}").flat_map do |path|
+  File.readlines(path).each_with_index.filter_map do |line, index|
+    next if line.strip.start_with?("#", "//", "<%#")
+
+    "#{path}:#{index + 1}: #{line.strip}" if line.match?(/importmap|jsbundling/i)
+  end
+end
+if leftovers.any?
+  say "These lines still mention importmap/jsbundling and may need a manual change:", :yellow
+  leftovers.each { |line| say "  #{line}", :yellow }
+end
+
+say "Migration finished. Review the changes with `git diff`, then run `bin/rails rspack:doctor`.", :green

data/lib/install/rspack.config.mjs

@@ -47,6 +47,9 @@ export default defineConfig({
   },
   resolve: {
     extensions: ["...", ".ts"],
+    // Bare imports of app code work as they did with importmap
+    // (import "controllers/application", import "lib/utils").
+    modules: ["node_modules", path.resolve(root, "app/javascript")],
   },
   module: {
     rules: [

data/lib/install/stimulus.rb

@@ -16,9 +16,9 @@ end
 
 if !File.exist?(entry)
   create_file entry, %(import "./controllers/autoload"\n)
-elsif File.read(entry).match?(%r{^import ["']\./controllers(/index(\.js)?)?["'];?$})
-  say "Replacing the controllers/index.js import with controllers/autoload"
-  gsub_file entry, %r{^import ["']\./controllers(/index(\.js)?)?["'];?$}, %(import "./controllers/autoload")
+elsif File.read(entry).match?(%r{^import ["'](?:\./)?controllers(/index(\.js)?)?["'];?$})
+  say "Replacing the controllers import with controllers/autoload"
+  gsub_file entry, %r{^import ["'](?:\./)?controllers(/index(\.js)?)?["'];?$}, %(import "./controllers/autoload")
 elsif !File.read(entry).include?("./controllers/autoload")
   append_to_file entry, %(import "./controllers/autoload"\n)
 end
@@ -28,6 +28,6 @@ if File.exist?("app/javascript/controllers/index.js")
 end
 
 say "Installing @hotwired/stimulus"
-run pm.add_command("@hotwired/stimulus")
+run pm.add_command("@hotwired/stimulus"), abort_on_failure: true
 
 say "Stimulus installed. Controllers in app/javascript/controllers are registered automatically.", :green

data/lib/install/typescript.rb

@@ -14,6 +14,6 @@ package = JSON.parse(File.read("package.json"))
 File.write("package.json", "#{JSON.pretty_generate(package)}\n")
 
 say "Installing typescript"
-run pm.add_dev_command("typescript")
+run pm.add_dev_command("typescript"), abort_on_failure: true
 
 say "TypeScript ready. Rspack compiles .ts files; run `#{pm.run_command("typecheck")}` to type-check.", :green

data/lib/rspack_rails/migration.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module RspackRails
+  # Detects how an app bundles JavaScript today and works out what
+  # `rspack:migrate` has to change. Pure inspection: nothing here writes files.
+  class Migration
+    Pin = Struct.new(:name, :to, :version, keyword_init: true)
+
+    # importmap-only helpers with no npm equivalent.
+    IMPORTMAP_ONLY = %w[@hotwired/stimulus-loading].freeze
+
+    BUNDLER_PACKAGES = %w[esbuild webpack webpack-cli rollup @rollup/plugin-node-resolve
+                          @rollup/plugin-commonjs @rollup/plugin-terser].freeze
+    BUNDLER_CONFIGS = %w[webpack.config.js rollup.config.js rollup.config.mjs].freeze
+
+    attr_reader :root
+
+    def initialize(root)
+      @root = Pathname(root)
+    end
+
+    # :rspack, :shakapacker, :importmap, :jsbundling or :none
+    def source
+      @source ||= if file?("rspack.config.mjs") then :rspack
+                  elsif file?("config/shakapacker.yml") || file?("config/webpacker.yml") then :shakapacker
+                  elsif file?("config/importmap.rb") then :importmap
+                  elsif jsbundling? then :jsbundling
+                  else
+                    :none
+                  end
+    end
+
+    def pins
+      @pins ||= parse_pins(read("config/importmap.rb").to_s)
+    end
+
+    # { "package" => "version or nil" } for every pin that comes from npm. The version is
+    # known only when importmap recorded it (vendored "# @1.2.3" pins or jspm URLs); gem-served
+    # pins such as turbo-rails install the latest npm release.
+    def npm_packages
+      pins.reject { |pin| local_pin?(pin) || IMPORTMAP_ONLY.include?(pin.name) }
+          .to_h { |pin| [package_name(pin.name), pin.version] }
+    end
+
+    # The argument list for `npm install` / `yarn add`, versions pinned when known.
+    def npm_install_args
+      npm_packages.map { |name, version| version ? "#{name}@#{version}" : name }
+    end
+
+    # Vendored copies of packages that now come from npm.
+    def vendored_files
+      pins.reject { |pin| local_pin?(pin) }.filter_map do |pin|
+        path = "vendor/javascript/#{pin.to || "#{pin.name}.js"}"
+        path if file?(path)
+      end
+    end
+
+    def bundler_packages
+      dev = package_json.fetch("devDependencies", {}).keys + package_json.fetch("dependencies", {}).keys
+      dev & BUNDLER_PACKAGES
+    end
+
+    def bundler_configs
+      BUNDLER_CONFIGS.select { |path| file?(path) }
+    end
+
+    # jsbundling's esbuild default builds every file in app/javascript; rspack
+    # only builds application.* and entrypoints/*.
+    def extra_root_entries
+      Dir.glob("app/javascript/*.{js,ts}", base: root).sort.grep_v(%r{/application\.[jt]s\z})
+    end
+
+    def parse_pins(source)
+      source.each_line.filter_map do |line|
+        match = line.match(/^\s*pin\s+["']([^"']+)["'](.*)$/)
+        next unless match
+
+        rest = match[2]
+        to = rest[/to:\s*["']([^"']+)["']/, 1]
+        version = rest[/#\s*@(\S+)/, 1] || to.to_s[%r{npm:(?:@[^/]+/)?[^@/]+@([^/]+)/}, 1]
+        Pin.new(name: match[1], to: to, version: version)
+      end
+    end
+
+    private
+
+    def jsbundling?
+      read("Gemfile").to_s.match?(/^\s*gem\s+["']jsbundling-rails["']/) ||
+        package_json.dig("scripts", "build").to_s.match?(/\b(esbuild|webpack|rollup|bun build)\b/)
+    end
+
+    # A pin is app code when it, or the file it points to, lives in app/javascript.
+    def local_pin?(pin)
+      return true if pin.name == "application"
+
+      target = pin.to || "#{pin.name}.js"
+      return false if target.match?(%r{\Ahttps?://})
+
+      file?("app/javascript/#{target}")
+    end
+
+    # "@rails/actioncable/src" -> "@rails/actioncable", "lodash/debounce" -> "lodash"
+    def package_name(specifier)
+      parts = specifier.split("/")
+      specifier.start_with?("@") ? parts.first(2).join("/") : parts.first
+    end
+
+    def package_json
+      @package_json ||= file?("package.json") ? JSON.parse(read("package.json")) : {}
+    rescue JSON::ParserError
+      @package_json = {}
+    end
+
+    def file?(path)
+      root.join(path).file?
+    end
+
+    def read(path)
+      root.join(path).read if file?(path)
+    end
+  end
+end

data/lib/rspack_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RspackRails
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/rspack_rails.rb

@@ -5,6 +5,7 @@ require_relative "rspack_rails/package_manager"
 require_relative "rspack_rails/configuration"
 require_relative "rspack_rails/dev_server"
 require_relative "rspack_rails/entrypoints"
+require_relative "rspack_rails/migration"
 
 # Rspack integration for Rails: rake tasks, installer and view helpers.
 module RspackRails

data/lib/tasks/rspack_rails.rake

@@ -24,6 +24,20 @@ namespace :rspack do
     end
   end
 
+  desc "Migrate from importmap-rails or jsbundling-rails to rspack (FORCE=1 to skip the clean git check)"
+  task :migrate do
+    dirty = system("git", "rev-parse", "--is-inside-work-tree", out: File::NULL, err: File::NULL) &&
+            !`git status --porcelain`.strip.empty?
+    if dirty && ENV["FORCE"].to_s.empty?
+      raise RspackRails::Error,
+            "rspack:migrate removes and rewrites files. Commit or stash your changes first, or run with FORCE=1."
+    end
+
+    template = File.expand_path("../install/migrate.rb", __dir__)
+    system(RbConfig.ruby, "./bin/rails", "app:template", "LOCATION=#{template}") ||
+      raise(RspackRails::Error, "rspack:migrate failed")
+  end
+
   desc "Check the rspack setup of this app"
   task doctor: :environment do
     require "rspack_rails/doctor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspack_rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - tungnt
@@ -45,6 +45,7 @@ files:
 - lib/install/application.js
 - lib/install/dev
 - lib/install/install.rb
+- lib/install/migrate.rb
 - lib/install/package.json
 - lib/install/rspack.config.mjs
 - lib/install/stimulus.rb
@@ -59,6 +60,7 @@ files:
 - lib/rspack_rails/doctor.rb
 - lib/rspack_rails/entrypoints.rb
 - lib/rspack_rails/helper.rb
+- lib/rspack_rails/migration.rb
 - lib/rspack_rails/node_version.rb
 - lib/rspack_rails/package_manager.rb
 - lib/rspack_rails/railtie.rb