rspack_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3eb3563c7877029531bd93b2ed9036ce92b8a89c4008600ea251dfad3b641ff
+  data.tar.gz: 5d210e018044764c5e2f3f94cd06e3cb296d16e1da97d010b9e18907c1416644
+SHA512:
+  metadata.gz: 5dc66b20aadec8d3695d98448c80eb39e31a0d2c55d693002c6d318ac25c95a96ff81b8ac4829d0e60a6e09af7959ceca287f1f5c440a09af333069b6ffa0458
+  data.tar.gz: fc965e7fd0ddd80f60d120b77cf135ce9e4da264b87e66e298767c5e14e367cf9bbfda64130abc6d03d2f0368528196826e5425f8dcae8ddbe36714e9c534da8

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-11-13
+
+- `rspack:doctor`: checks Node.js against rspack's `engines`, packages, config, entry, build output, layout, Procfile.dev, Stimulus and the dev server
+- `rspack:install:stimulus`: Stimulus with automatic controller registration and hot-swapping under `rspack serve`
+- `rspack_javascript_tag` / `rspack_stylesheet_tag` helpers that load from `rspack serve` in development and fall back to the asset pipeline
+- Dev server with hot module replacement (`npm run dev`), configured via `RSPACK_DEV_SERVER_*` env vars or `RspackRails.configure`
+- Installer adds `@rspack/dev-server` and upgrades Phase 1 layouts and `Procfile.dev`
+- Railtie with `rspack:install`, `rspack:build`, `rspack:dependencies` and `rspack:clobber` tasks
+- Hook `rspack:build` into `assets:precompile` and test prepare tasks
+- Package manager detection (bun, yarn, pnpm, npm)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 tungnt
+
+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,104 @@
+# rspack_rails
+
+Bundle your Rails app's JavaScript with [Rspack](https://rspack.rs), the Rust-powered, webpack-compatible bundler.
+
+rspack_rails follows the `jsbundling-rails` model: rspack writes bundles to `app/assets/builds`, and Propshaft (or Sprockets) serves and fingerprints them.
+
+## Installation
+
+```bash
+bundle add rspack_rails
+bin/rails rspack:install
+```
+
+The installer:
+
+- creates `rspack.config.mjs` and `app/javascript/application.js`
+- adds `build`, `build:watch` and `dev` (`rspack serve`) scripts
+- adds `rspack_javascript_tag "application"` to your layout
+- 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)
+
+## Usage
+
+Run `bin/dev` to start Rails and the rspack dev server (with hot module replacement) together.
+
+### View helpers
+
+```erb
+<%= rspack_javascript_tag "application", "data-turbo-track": "reload" %>
+<%= rspack_stylesheet_tag "application" %>
+```
+
+In development, when `rspack serve` is reachable, the helpers load bundles from the dev server (`http://localhost:3036/application.js`), so edits are hot-reloaded. Otherwise they fall back to `javascript_include_tag` / `stylesheet_link_tag`, served and fingerprinted by Propshaft from `app/assets/builds`. Production always uses the asset pipeline. `rspack_javascript_tag` adds `defer` by default.
+
+### Dev server settings
+
+`rspack.config.mjs` and the gem read the same environment variables, so a `.env` file (loaded by foreman) changes both:
+
+| Variable | Default |
+|---|---|
+| `RSPACK_DEV_SERVER_HOST` | `localhost` |
+| `RSPACK_DEV_SERVER_PORT` | `3036` |
+| `RSPACK_DEV_SERVER=false` | turns the dev server check off |
+
+Rails-side settings can also go in an initializer (this does not change `rspack.config.mjs`, so prefer env vars for host and port):
+
+```ruby
+RspackRails.configure do |config|
+  config.dev_server_port = 4000
+  config.dev_server_enabled = false
+end
+```
+
+### Stimulus
+
+```bash
+bin/rails rspack:install:stimulus
+```
+
+This installs `@hotwired/stimulus` and adds `app/javascript/controllers/autoload.js`, imported from `application.js`. Every `*_controller.js` under `app/javascript/controllers` is registered automatically, with the usual naming (`admin/user_card_controller.js` becomes `admin--user-card`). There is no manifest to keep up to date.
+
+Under `rspack serve`, editing a controller or adding a new one hot-swaps it in the open page without a reload, so form input and other page state survive.
+
+If `application.js` imported `./controllers` (the stimulus-rails index), the installer switches it to `./controllers/autoload`. stimulus-rails may still rewrite `controllers/index.js` when you run `bin/rails generate stimulus`, but nothing imports that file any more.
+
+### Tasks
+
+| Task | What it does |
+|---|---|
+| `bin/rails rspack:install:stimulus` | Sets up Stimulus with controller autoloading |
+| `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` |
+
+`rspack:build` runs automatically before `assets:precompile`, `test:prepare`, `spec:prepare` and `db:test:prepare`. Set `SKIP_RSPACK_BUILD=1` to turn that off.
+
+When `RAILS_ENV` or `NODE_ENV` is `production`, the generated config builds in production mode (minified). Lazy-loaded chunks are named `*.digested.js`, so Propshaft serves them without fingerprinting them a second time.
+
+### Doctor
+
+`bin/rails rspack:doctor` checks the setup and prints a hint for anything missing:
+
+```
+✓ Node.js: v22.12.0 (rspack needs ^20.19.0 || >=22.12.0)
+✓ @rspack/core: 2.3.2
+✓ Layout: uses rspack_javascript_tag
+! Dev server: not running at http://localhost:3036
+    → Start it with bin/dev; until then pages use app/assets/builds
+
+0 error(s), 1 warning(s).
+```
+
+The required Node.js version comes from the `engines` field of the installed `@rspack/core`. The task exits with status 1 when there are errors, so it can run in CI.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake   # specs + rubocop
+```
+
+## License
+
+Available under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/install/application.js

@@ -0,0 +1,2 @@
+// Entry point for rspack. Import your JavaScript here.
+console.log("Hello from rspack_rails")

data/lib/install/dev

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+
+if ! gem list foreman -i --silent; then
+  echo "Installing foreman..."
+  gem install foreman
+fi
+
+export PORT="${PORT:-3000}"
+
+exec foreman start -f Procfile.dev "$@"

data/lib/install/install.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Rails application template run by `bin/rails rspack:install`.
+require "json"
+
+pm = RspackRails::PackageManager.detect(Rails.root)
+
+say "Creating app/assets/builds"
+empty_directory "app/assets/builds"
+create_file "app/assets/builds/.keep", "" unless File.exist?("app/assets/builds/.keep")
+
+if File.exist?(".gitignore") && !File.read(".gitignore").include?("/app/assets/builds/*")
+  append_to_file ".gitignore", "\n/app/assets/builds/*\n!/app/assets/builds/.keep\n/node_modules\n"
+end
+
+if Rails.root.join("app/assets/config/manifest.js").exist?
+  append_to_file "app/assets/config/manifest.js", %(//= link_tree ../builds\n)
+end
+
+say "Creating rspack entry point"
+unless File.exist?("app/javascript/application.js")
+  copy_file "#{__dir__}/application.js",
+            "app/javascript/application.js"
+end
+copy_file "#{__dir__}/rspack.config.mjs", "rspack.config.mjs"
+
+say "Configuring package.json"
+copy_file "#{__dir__}/package.json", "package.json" unless File.exist?("package.json")
+package = JSON.parse(File.read("package.json"))
+package["scripts"] ||= {}
+package["scripts"]["build"] = "rspack build"
+package["scripts"]["build:watch"] = "rspack build --watch"
+package["scripts"]["dev"] = "rspack serve"
+File.write("package.json", "#{JSON.pretty_generate(package)}\n")
+
+include_tag = %(<%= rspack_javascript_tag "application", "data-turbo-track": "reload" %>)
+layout = Rails.root.join("app/views/layouts/application.html.erb")
+if layout.exist?
+  content = File.read(layout)
+  if content.include?("javascript_importmap_tags")
+    say "Found javascript_importmap_tags in your layout. Remove it if you are replacing importmap with rspack.",
+        :yellow
+  end
+  if content.match?(/javascript_include_tag "application".*$/)
+    say "Switching javascript_include_tag to rspack_javascript_tag"
+    gsub_file layout, /<%= javascript_include_tag "application".*%>/, include_tag
+  elsif !content.include?("rspack_javascript_tag")
+    say "Adding rspack_javascript_tag to application layout"
+    insert_into_file layout, "    #{include_tag}\n", before: %r{^[ \t]*</head>}
+  end
+else
+  say "Add this to your layout: #{include_tag}", :yellow
+end
+
+say "Configuring bin/dev"
+js_process = "js: #{pm.run_command("dev")}"
+if !File.exist?("Procfile.dev")
+  create_file "Procfile.dev", "web: env RUBY_DEBUG_OPEN=true bin/rails server\n#{js_process}\n"
+elsif File.read("Procfile.dev").match?(/^js: .*build:watch$/)
+  gsub_file "Procfile.dev", /^js: .*build:watch$/, js_process
+elsif !File.read("Procfile.dev").match?(/^js:/)
+  append_to_file "Procfile.dev", "#{js_process}\n"
+end
+
+unless File.exist?("bin/dev") && File.read("bin/dev").include?("Procfile.dev")
+  copy_file "#{__dir__}/dev", "bin/dev", force: true
+  chmod "bin/dev", 0o755, verbose: false
+end
+
+say "Installing @rspack/cli, @rspack/core and @rspack/dev-server"
+run pm.add_dev_command("@rspack/cli", "@rspack/core", "@rspack/dev-server")
+
+say "rspack_rails installed. Run bin/dev to start developing.", :green

data/lib/install/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "app",
+  "private": true
+}

data/lib/install/rspack.config.mjs

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "@rspack/cli";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const isDevServer = process.argv.includes("serve");
+const isProduction =
+  !isDevServer &&
+  (process.env.RAILS_ENV === "production" || process.env.NODE_ENV === "production");
+
+// Keep these in sync with RspackRails.config (same env vars, same defaults).
+const host = process.env.RSPACK_DEV_SERVER_HOST || "localhost";
+const port = Number(process.env.RSPACK_DEV_SERVER_PORT || 3036);
+
+export default defineConfig({
+  mode: isProduction ? "production" : "development",
+  devtool: "source-map",
+  entry: {
+    application: "./app/javascript/application.js",
+  },
+  output: {
+    path: path.resolve(root, "app/assets/builds"),
+    filename: "[name].js",
+    // ".digested" tells Propshaft the file is already fingerprinted.
+    chunkFilename: "[name]-[contenthash].digested.js",
+    // Under `rspack serve`, chunks and hot updates load from the dev server.
+    publicPath: isDevServer ? `http://${host}:${port}/` : "/assets/",
+  },
+  devServer: {
+    host,
+    port,
+    hot: true,
+    allowedHosts: "all",
+    headers: { "Access-Control-Allow-Origin": "*" },
+    client: {
+      webSocketURL: `ws://${host}:${port}/ws`,
+      overlay: true,
+    },
+  },
+});

data/lib/install/stimulus/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus = application
+
+export { application }

data/lib/install/stimulus/autoload.js

@@ -0,0 +1,31 @@
+// Registers every app/javascript/controllers/**/*_controller.js with Stimulus.
+// Managed by rspack_rails: new controllers need no manual import, and edited
+// controllers are hot-swapped under `rspack serve` without a page reload.
+import { application } from "./application"
+
+const controllers = () =>
+  import.meta.webpackContext("./", { recursive: true, regExp: /_controller\.js$/ })
+
+// "./users/profile_controller.js" -> "users--profile"
+const identifierFor = (key) =>
+  key
+    .replace(/^\.\//, "")
+    .replace(/_controller\.js$/, "")
+    .replace(/\//g, "--")
+    .replace(/_/g, "-")
+
+const registerAll = (context) => {
+  context.keys().forEach((key) => {
+    const controller = context(key).default
+    if (controller) application.register(identifierFor(key), controller)
+  })
+}
+
+const context = controllers()
+registerAll(context)
+
+if (import.meta.webpackHot) {
+  // Stimulus unloads an identifier before registering it again, so
+  // re-registering swaps connected controllers in place.
+  import.meta.webpackHot.accept(context.id, () => registerAll(controllers()))
+}

data/lib/install/stimulus/hello_controller.js

@@ -0,0 +1,8 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="hello"
+export default class extends Controller {
+  connect() {
+    this.element.textContent = "Hello from Stimulus + rspack!"
+  }
+}

data/lib/install/stimulus.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Rails application template run by `bin/rails rspack:install:stimulus`.
+pm = RspackRails::PackageManager.detect(Rails.root)
+entry = "app/javascript/application.js"
+
+say "Installing Stimulus with controller autoloading"
+unless File.exist?("app/javascript/controllers/application.js")
+  copy_file "#{__dir__}/stimulus/application.js", "app/javascript/controllers/application.js"
+end
+copy_file "#{__dir__}/stimulus/autoload.js", "app/javascript/controllers/autoload.js"
+
+if Dir.glob("app/javascript/controllers/**/*_controller.js").empty?
+  copy_file "#{__dir__}/stimulus/hello_controller.js", "app/javascript/controllers/hello_controller.js"
+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).include?("./controllers/autoload")
+  append_to_file entry, %(import "./controllers/autoload"\n)
+end
+
+if File.exist?("app/javascript/controllers/index.js")
+  say "app/javascript/controllers/index.js is no longer imported; controllers/autoload.js replaces it.", :yellow
+end
+
+say "Installing @hotwired/stimulus"
+run pm.add_command("@hotwired/stimulus")
+
+say "Stimulus installed. Controllers in app/javascript/controllers are registered automatically.", :green

data/lib/rspack_rails/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RspackRails
+  # Settings shared by the dev server check and the view helpers.
+  # Defaults come from the same environment variables rspack.config.mjs reads.
+  class Configuration
+    attr_accessor :dev_server_host, :dev_server_port
+    attr_writer :dev_server_enabled
+
+    def initialize(env = ENV)
+      @env = env
+      @dev_server_host = env.fetch("RSPACK_DEV_SERVER_HOST", "localhost")
+      @dev_server_port = Integer(env.fetch("RSPACK_DEV_SERVER_PORT", 3036))
+      @dev_server_enabled = nil
+    end
+
+    # Unless set explicitly, the dev server is used only in development and
+    # can be switched off with RSPACK_DEV_SERVER=false.
+    def dev_server_enabled
+      return @dev_server_enabled unless @dev_server_enabled.nil?
+
+      return false if @env["RSPACK_DEV_SERVER"] == "false"
+
+      defined?(::Rails.env) ? ::Rails.env.development? : false
+    end
+
+    def dev_server_url
+      "http://#{dev_server_host}:#{dev_server_port}"
+    end
+  end
+end

data/lib/rspack_rails/dev_server.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module RspackRails
+  # Answers whether `rspack serve` is reachable. The result is cached briefly
+  # so a page with several tags does not open a socket per tag.
+  class DevServer
+    CONNECT_TIMEOUT = 0.05
+
+    def initialize(config, check_interval: 1.0)
+      @config = config
+      @check_interval = check_interval
+      @checked_at = nil
+      @running = false
+    end
+
+    def running?
+      return false unless @config.dev_server_enabled
+
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return @running if @checked_at && now - @checked_at < @check_interval
+
+      @checked_at = now
+      @running = reachable?
+    end
+
+    def url(path)
+      "#{@config.dev_server_url}/#{path.to_s.delete_prefix("/")}"
+    end
+
+    private
+
+    def reachable?
+      Socket.tcp(@config.dev_server_host, @config.dev_server_port, connect_timeout: CONNECT_TIMEOUT) { true }
+    rescue SystemCallError, SocketError, IOError
+      false
+    end
+  end
+end

data/lib/rspack_rails/doctor.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "pathname"
+require_relative "node_version"
+
+module RspackRails
+  # Inspects a Rails app's rspack setup and reports what is missing.
+  class Doctor
+    Check = Struct.new(:status, :name, :detail, :hint)
+    SYMBOLS = { ok: "✓", warn: "!", error: "✗" }.freeze
+
+    def initialize(root, config: RspackRails.config, dev_server: RspackRails.dev_server, node_version: nil)
+      @root = Pathname(root)
+      @config = config
+      @dev_server = dev_server
+      @node_version = node_version
+    end
+
+    def checks
+      @checks ||= [
+        node_check, package_check(:cli), package_check(:core), package_check(:"dev-server"),
+        config_check, scripts_check, entry_check, build_check, layout_check, procfile_check,
+        stimulus_check, dev_server_check
+      ].compact
+    end
+
+    def ok?
+      checks.none? { |check| check.status == :error }
+    end
+
+    def report(io = $stdout)
+      checks.each do |check|
+        io.puts "#{SYMBOLS.fetch(check.status)} #{check.name}: #{check.detail}"
+        io.puts "    → #{check.hint}" if check.hint && check.status != :ok
+      end
+      io.puts
+      io.puts summary
+    end
+
+    def summary
+      errors = checks.count { |c| c.status == :error }
+      warnings = checks.count { |c| c.status == :warn }
+      return "Everything looks good." if errors.zero? && warnings.zero?
+
+      "#{errors} error(s), #{warnings} warning(s)."
+    end
+
+    private
+
+    def node_check
+      version = node_version
+      return Check.new(:error, "Node.js", "not found", "Install Node.js and make sure `node` is on PATH") unless version
+
+      required = installed_package("core")&.dig("engines", "node")
+      return Check.new(:ok, "Node.js", version) unless required
+
+      case NodeVersion.check(version, required)
+      when true then Check.new(:ok, "Node.js", "#{version} (rspack needs #{required})")
+      when false then Check.new(:error, "Node.js", "#{version}, but rspack needs #{required}", "Upgrade Node.js")
+      else Check.new(:warn, "Node.js", "#{version}; could not read rspack's requirement #{required}")
+      end
+    end
+
+    def package_check(name)
+      package = installed_package(name)
+      label = "@rspack/#{name}"
+      if package
+        Check.new(:ok, label, package["version"])
+      else
+        Check.new(name == :"dev-server" ? :warn : :error, label, "not installed",
+                  "Run `#{package_manager.add_dev_command(label)}`")
+      end
+    end
+
+    def config_check
+      return Check.new(:ok, "rspack.config.mjs", "found") if exist?("rspack.config.mjs")
+
+      Check.new(:error, "rspack.config.mjs", "missing", "Run `bin/rails rspack:install`")
+    end
+
+    def scripts_check
+      scripts = package_json&.fetch("scripts", {}) || {}
+      missing = %w[build dev].reject { |name| scripts.key?(name) }
+      return Check.new(:ok, "package.json scripts", "build, dev") if missing.empty?
+
+      Check.new(missing.include?("build") ? :error : :warn, "package.json scripts",
+                "missing #{missing.join(", ")}", "Run `bin/rails rspack:install`")
+    end
+
+    def entry_check
+      return Check.new(:ok, "Entry point", "app/javascript/application.js") if exist?("app/javascript/application.js")
+
+      Check.new(:error, "Entry point", "app/javascript/application.js is missing",
+                "Create it, or point `entry` in rspack.config.mjs at your entry file")
+    end
+
+    def build_check
+      built = @root.join("app/assets/builds/application.js")
+      return Check.new(:ok, "Build output", "app/assets/builds/application.js (#{built.size} bytes)") if built.exist?
+
+      Check.new(:warn, "Build output", "app/assets/builds/application.js not built yet",
+                "Run `bin/rails rspack:build` (only needed without the dev server)")
+    end
+
+    def layout_check
+      layout = read("app/views/layouts/application.html.erb")
+      return Check.new(:warn, "Layout", "app/views/layouts/application.html.erb not found") unless layout
+
+      if layout.include?("javascript_importmap_tags")
+        return Check.new(:warn, "Layout", "still includes javascript_importmap_tags",
+                         "Remove it if rspack replaces importmap, or the app may load JavaScript twice")
+      end
+      return Check.new(:ok, "Layout", "uses rspack_javascript_tag") if layout.include?("rspack_javascript_tag")
+
+      Check.new(:warn, "Layout", "does not use rspack_javascript_tag",
+                %(Add <%= rspack_javascript_tag "application" %> to get the dev server and HMR))
+    end
+
+    def procfile_check
+      procfile = read("Procfile.dev")
+      if procfile&.match?(/^js: .*\bdev$/)
+        Check.new(:ok, "Procfile.dev", "runs the dev server")
+      elsif procfile&.match?(/^js:/)
+        Check.new(:warn, "Procfile.dev", "js process does not run `dev`",
+                  "Use `js: #{package_manager.run_command("dev")}` for HMR")
+      else
+        Check.new(:warn, "Procfile.dev", "no js process", "Run `bin/rails rspack:install`")
+      end
+    end
+
+    def stimulus_check
+      return unless exist?("app/javascript/controllers/autoload.js")
+
+      if node_modules_package("@hotwired/stimulus")
+        Check.new(:ok, "Stimulus", "autoload enabled")
+      else
+        Check.new(:error, "Stimulus", "@hotwired/stimulus is not installed",
+                  "Run `#{package_manager.add_command("@hotwired/stimulus")}`")
+      end
+    end
+
+    def dev_server_check
+      return Check.new(:ok, "Dev server", "disabled in this environment") unless @config.dev_server_enabled
+      return Check.new(:ok, "Dev server", "running at #{@config.dev_server_url}") if @dev_server.running?
+
+      Check.new(:warn, "Dev server", "not running at #{@config.dev_server_url}",
+                "Start it with bin/dev; until then pages use app/assets/builds")
+    end
+
+    def node_version
+      return @node_version if @node_version
+
+      out, status = Open3.capture2("node", "--version")
+      status.success? ? out.strip : nil
+    rescue SystemCallError
+      nil
+    end
+
+    def installed_package(name)
+      node_modules_package("@rspack/#{name}")
+    end
+
+    def node_modules_package(name)
+      path = @root.join("node_modules", name, "package.json")
+      JSON.parse(path.read) if path.exist?
+    rescue JSON::ParserError
+      nil
+    end
+
+    def package_json
+      JSON.parse(read("package.json")) if exist?("package.json")
+    rescue JSON::ParserError
+      nil
+    end
+
+    def package_manager
+      @package_manager ||= PackageManager.detect(@root)
+    end
+
+    def exist?(path)
+      @root.join(path).exist?
+    end
+
+    def read(path)
+      file = @root.join(path)
+      file.read if file.exist?
+    end
+  end
+end

data/lib/rspack_rails/helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RspackRails
+  # View helpers that load bundles from `rspack serve` when it is running
+  # and fall back to the asset pipeline (app/assets/builds) otherwise.
+  module Helper
+    def rspack_javascript_tag(*entries, **options)
+      options = { defer: true }.merge(options)
+      return javascript_include_tag(*entries, **options) unless RspackRails.dev_server.running?
+
+      safe_join(entries.map { |entry| javascript_include_tag(RspackRails.dev_server.url("#{entry}.js"), **options) },
+                "\n")
+    end
+
+    def rspack_stylesheet_tag(*entries, **options)
+      return stylesheet_link_tag(*entries, **options) unless RspackRails.dev_server.running?
+
+      safe_join(entries.map { |entry| stylesheet_link_tag(RspackRails.dev_server.url("#{entry}.css"), **options) },
+                "\n")
+    end
+  end
+end

data/lib/rspack_rails/node_version.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RspackRails
+  # Minimal semver range matching for package.json "engines" fields.
+  # Supports `||`, space-separated comparators, ^, ~, >=, <=, >, <, = and
+  # partial versions (20, 20.x).
+  module NodeVersion
+    COMPARATOR = /\A(\^|~|>=|<=|>|<|=)?v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?\z/
+
+    OPERATORS = {
+      "^" => ->(cmp, current, target) { cmp >= 0 && current[0] == target[0] },
+      "~" => ->(cmp, current, target) { cmp >= 0 && current[0..1] == target[0..1] },
+      ">=" => ->(cmp, _, _) { cmp >= 0 },
+      "<=" => ->(cmp, _, _) { cmp <= 0 },
+      ">" => ->(cmp, _, _) { cmp.positive? },
+      "<" => ->(cmp, _, _) { cmp.negative? }
+    }.freeze
+
+    Comparator = Struct.new(:operator, :parts) do
+      def match?(current)
+        target = parts + ([0] * (3 - parts.size))
+        operation = OPERATORS[operator]
+        return current.take(parts.size) == parts unless operation
+
+        operation.call(current <=> target, current, target)
+      end
+    end
+
+    module_function
+
+    def parse(version)
+      version.to_s.strip.match(/\Av?(\d+)\.(\d+)\.(\d+)/)&.captures&.map(&:to_i)
+    end
+
+    # true or false when the range can be read; nil when the version or any
+    # part of the range is in a form this matcher does not support.
+    def check(version, range)
+      current = parse(version)
+      sets = parse_range(range)
+      return nil unless current && sets
+
+      sets.any? { |comparators| comparators.all? { |comparator| comparator.match?(current) } }
+    end
+
+    def parse_range(range)
+      sets = range.to_s.split("||").map { |set| set.strip.split(/\s+/).map { |c| parse_comparator(c) } }
+      sets.flatten.all? ? sets : nil
+    end
+
+    def parse_comparator(text)
+      match = text.match(COMPARATOR)
+      return unless match
+
+      parts = match.captures.drop(1).take_while { |part| part&.match?(/\A\d+\z/) }.map(&:to_i)
+      Comparator.new(match[1], parts)
+    end
+  end
+end

data/lib/rspack_rails/package_manager.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RspackRails
+  # Detects the JavaScript package manager of an app from its lockfile and
+  # builds the shell commands rspack_rails needs.
+  class PackageManager
+    LOCKFILES = {
+      bun: %w[bun.lock bun.lockb],
+      yarn: %w[yarn.lock],
+      pnpm: %w[pnpm-lock.yaml],
+      npm: %w[package-lock.json]
+    }.freeze
+
+    INSTALL = {
+      bun: "bun install",
+      yarn: "yarn install",
+      pnpm: "pnpm install",
+      npm: "npm install"
+    }.freeze
+
+    ADD = {
+      bun: "bun add",
+      yarn: "yarn add",
+      pnpm: "pnpm add",
+      npm: "npm install"
+    }.freeze
+
+    ADD_DEV = {
+      bun: "bun add --dev",
+      yarn: "yarn add --dev",
+      pnpm: "pnpm add --save-dev",
+      npm: "npm install --save-dev"
+    }.freeze
+
+    attr_reader :root, :name
+
+    def self.detect(root = Dir.pwd)
+      new(root)
+    end
+
+    def initialize(root)
+      @root = root.to_s
+      @name = LOCKFILES.find { |_, files| files.any? { |f| File.exist?(File.join(@root, f)) } }&.first || :npm
+    end
+
+    def install_command
+      INSTALL.fetch(name)
+    end
+
+    def add_command(*packages)
+      [ADD.fetch(name), *packages].join(" ")
+    end
+
+    def add_dev_command(*packages)
+      [ADD_DEV.fetch(name), *packages].join(" ")
+    end
+
+    def run_command(script)
+      "#{name} run #{script}"
+    end
+  end
+end

data/lib/rspack_rails/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module RspackRails
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/rspack_rails.rake", __dir__)
+    end
+
+    initializer "rspack_rails.helper" do
+      require_relative "helper"
+      ActiveSupport.on_load(:action_view) { include RspackRails::Helper }
+    end
+  end
+end

data/lib/rspack_rails/version.rb

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

data/lib/rspack_rails.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "rspack_rails/version"
+require_relative "rspack_rails/package_manager"
+require_relative "rspack_rails/configuration"
+require_relative "rspack_rails/dev_server"
+
+# Rspack integration for Rails: rake tasks, installer and view helpers.
+module RspackRails
+  class Error < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def dev_server
+      @dev_server ||= DevServer.new(config)
+    end
+  end
+end
+
+require_relative "rspack_rails/railtie" if defined?(Rails::Railtie)

data/lib/tasks/rspack_rails.rake

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+namespace :rspack do
+  desc "Set up rspack in this Rails app"
+  task :install do
+    template = File.expand_path("../install/install.rb", __dir__)
+    system(RbConfig.ruby, "./bin/rails", "app:template", "LOCATION=#{template}") ||
+      raise(RspackRails::Error, "rspack:install failed")
+  end
+
+  namespace :install do
+    desc "Set up Stimulus with automatic controller registration"
+    task :stimulus do
+      template = File.expand_path("../install/stimulus.rb", __dir__)
+      system(RbConfig.ruby, "./bin/rails", "app:template", "LOCATION=#{template}") ||
+        raise(RspackRails::Error, "rspack:install:stimulus failed")
+    end
+  end
+
+  desc "Check the rspack setup of this app"
+  task doctor: :environment do
+    require "rspack_rails/doctor"
+    doctor = RspackRails::Doctor.new(Rails.root)
+    doctor.report
+    exit 1 unless doctor.ok?
+  end
+
+  desc "Install JavaScript dependencies"
+  task :dependencies do
+    command = RspackRails::PackageManager.detect(Rails.root).install_command
+    system(command, chdir: Rails.root) || raise(RspackRails::Error, "#{command} failed")
+  end
+
+  desc "Build JavaScript bundles with rspack"
+  task build: :dependencies do
+    command = RspackRails::PackageManager.detect(Rails.root).run_command("build")
+    system(command, chdir: Rails.root) || raise(RspackRails::Error, "#{command} failed")
+  end
+
+  desc "Remove rspack build output"
+  task :clobber do
+    Dir[Rails.root.join("app/assets/builds/**/*.{js,js.map,css,css.map}")].each { |f| File.delete(f) }
+  end
+end
+
+unless ENV["SKIP_RSPACK_BUILD"]
+  %w[assets:precompile test:prepare spec:prepare db:test:prepare].each do |name|
+    Rake::Task[name].enhance(["rspack:build"]) if Rake::Task.task_defined?(name)
+  end
+end
+
+Rake::Task["assets:clobber"].enhance(["rspack:clobber"]) if Rake::Task.task_defined?("assets:clobber")

data/sig/rspack_rails.rbs

@@ -0,0 +1,38 @@
+module RspackRails
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class PackageManager
+    attr_reader root: String
+    attr_reader name: Symbol
+    def self.detect: (?untyped root) -> PackageManager
+    def initialize: (untyped root) -> void
+    def install_command: () -> String
+    def add_command: (*String packages) -> String
+    def add_dev_command: (*String packages) -> String
+    def run_command: (String script) -> String
+  end
+end
+
+module RspackRails
+  def self.config: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.dev_server: () -> DevServer
+
+  class Configuration
+    attr_accessor dev_server_host: String
+    attr_accessor dev_server_port: Integer
+    attr_writer dev_server_enabled: bool?
+    def initialize: (?Hash[String, String] env) -> void
+    def dev_server_enabled: () -> bool
+    def dev_server_url: () -> String
+  end
+
+  class DevServer
+    def initialize: (Configuration config, ?check_interval: Float | Integer) -> void
+    def running?: () -> bool
+    def url: (String | Symbol path) -> String
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: rspack_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tungnt
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'Bundle Rails JavaScript with Rspack: one-command installer, dev server
+  with hot module replacement, Stimulus controller autoloading and a setup doctor.
+  Works with Propshaft and Sprockets.'
+email:
+- tungnguyen120301@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/install/application.js
+- lib/install/dev
+- lib/install/install.rb
+- lib/install/package.json
+- lib/install/rspack.config.mjs
+- lib/install/stimulus.rb
+- lib/install/stimulus/application.js
+- lib/install/stimulus/autoload.js
+- lib/install/stimulus/hello_controller.js
+- lib/rspack_rails.rb
+- lib/rspack_rails/configuration.rb
+- lib/rspack_rails/dev_server.rb
+- lib/rspack_rails/doctor.rb
+- lib/rspack_rails/helper.rb
+- lib/rspack_rails/node_version.rb
+- lib/rspack_rails/package_manager.rb
+- lib/rspack_rails/railtie.rb
+- lib/rspack_rails/version.rb
+- lib/tasks/rspack_rails.rake
+- sig/rspack_rails.rbs
+homepage: https://github.com/tungnt1203/rspack_rails
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tungnt1203/rspack_rails
+  changelog_uri: https://github.com/tungnt1203/rspack_rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Rspack integration for Ruby on Rails
+test_files: []