shakapacker 10.0.0 → 10.1.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08b8b40c44fa65d3a426d14596e15d7e5da7e486f0659c03822aa34a7f7e5474'
-  data.tar.gz: eadf1441efba9b99b1e9918075d12eb5cb08f4d71c63bb00d8c58c93d36d4ab6
+  metadata.gz: b2dbe6638add4651d5bd04b2c7138619f43427c71af173bc73ff10d231cefbed
+  data.tar.gz: 298bb003983f87e10e1cf61665e6bfab52bee6a8c632320f01323a6212de7c0e
 SHA512:
-  metadata.gz: c50b9fe63645ef4f2890ed6e0ddeeb73a21afe51e827ed39d5daebafda00517bf5299e72ad056ecf74650214d21407f0de948a876a7a5ac789de1581240f8e64
-  data.tar.gz: 6651deb390179edc5aea7f0abe9db2a6065b5674be9e4d8eee13de5642d590f600673eab5f7178caa12d14547cce9e1ad376e784ebee2c1377205e9112e38a05
+  metadata.gz: 40b41c276daa9b229524738cb969b3e3e6f1aa6b6c31ff7e4e77d18e1a72291a48dd9c4efca11fddfeebdeb886f16632cd6af0b94a4dde652333afb6c6d0b10d
+  data.tar.gz: 6c1b242e31123d3a331028305181fc0ca99650606b9d8273287f37cf4670d1103dd0fc670e48b91335ee5f222e605df94dbfa18d44e2555e7fd3dc25e1bae326

data/CHANGELOG.md

@@ -9,6 +9,44 @@
 
 ## [Unreleased]
 
+## [v10.1.0-rc.1] - May 21, 2026
+
+### Added
+
+- **Added supplemental npm packages `shakapacker-webpack` and `shakapacker-rspack`**. [PR #1096](https://github.com/shakacode/shakapacker/pull/1096) by [justin808](https://github.com/justin808). Optional packages that lockstep with core and bundle the managed-build stack as direct `dependencies` (so a single `yarn add shakapacker-webpack` pulls in `shakapacker`, `webpack`, `webpack-cli`, and `webpack-assets-manifest`; the rspack package bundles `shakapacker`, `@rspack/core`, `@rspack/cli`, and `rspack-manifest-plugin`). Optional features (transpilers, dev-server, CSS preprocessors, react-refresh) remain as opt-in `peerDependencies` so SCSS/native-binding bloat isn't forced on every install. The wrappers emit structured warnings (`SHAKAPACKER_BUNDLER_MISMATCH`, `SHAKAPACKER_NO_TRANSPILER`) when `config.assets_bundler` or `javascript_transpiler` doesn't match the installed peers. See the [v10.1 migration guide](docs/migration/v10.1-supplemental-packages.md) for adoption steps and [`docs/dependency-strategy.md`](docs/dependency-strategy.md) for the design rationale and v11 roadmap.
+- **Added `shakapacker:doctor` check for disabled Rspack cache**. [PR #1100](https://github.com/shakacode/shakapacker/pull/1100) by [justin808](https://github.com/justin808). The doctor now inspects the Rspack config file for an explicit `cache: false`, warns when found (disabling cache causes significantly slower builds), and also flags Rspack v1 installs (where persistent cache is experimental) with a recommendation to upgrade to v2.
+- **Added a `shakapacker:doctor` hint to compiler output**. [PR #1100](https://github.com/shakacode/shakapacker/pull/1100) by [justin808](https://github.com/justin808). The compiler now logs a one-time tip suggesting `bundle exec rake shakapacker:doctor` after a failed compilation, so healthy build loops stay quiet.
+
+### Migration Notes
+
+- **Simplify your `package.json` by adopting a supplemental package**. Existing apps can drop the explicit managed-build deps from `devDependencies` and rely on the bundled stack:
+  - **Rspack apps** can replace `shakapacker` + `@rspack/core` + `@rspack/cli` + `rspack-manifest-plugin` with a single `shakapacker-rspack`. See `packages/shakapacker-rspack/README.md` §"Simplifying an existing rspack install" for the before/after.
+  - **Webpack apps** can replace `shakapacker` + `webpack` + `webpack-cli` + `webpack-assets-manifest` with a single `shakapacker-webpack`. See `packages/shakapacker-webpack/README.md` §"Simplifying an existing webpack install" for the before/after.
+  - Optional peers (transpilers, `webpack-dev-server`, CSS preprocessors, react-refresh) stay only if your app uses those features.
+  - Adoption is opt-in: leaving your `package.json` untouched on v10.1 also continues to work.
+
+- **Adopting `shakapacker-webpack` requires `webpack-assets-manifest@^6.0.0`**. Core `shakapacker` still accepts both v5 and v6 (`^5.0.6 || ^6.0.0`), but `shakapacker-webpack` pins `~6.5.1`. Apps still on `webpack-assets-manifest@5.x` must upgrade when switching to the supplemental package; v6 fixed an ENOENT crash on clean builds with `merge: true` and dropped a Node 14 install path. See [the v5→v6 release notes](https://github.com/webdeveric/webpack-assets-manifest/releases) and `packages/shakapacker-webpack/README.md` for details.
+
+### ⚠️ Breaking Changes
+
+- **Breaking: tightened `package.json` `engines.node` to `^20.19.0 || >=22.12.0`**. [PR #1099](https://github.com/shakacode/shakapacker/pull/1099) by [justin808](https://github.com/justin808). Raised from `>= 20`, dropping support for Node 20.0.0–20.18.x and Node 21.x to match `@rspack/core@2.0.0-rc.0`. Consumers on those versions will hit an engine error with `--engine-strict` or yarn workspaces and need to upgrade. The PR also bumps `.node-version` to `22.20.0` and updates `conductor-setup.sh` to enforce the same disjoint range up front, so contributors get a clear error before `yarn install` fails with a confusing engine mismatch.
+
+### Changed
+
+- **Changed `shakapacker:install` to default fresh Rspack installs to v2 (`^2.0.0-0`)**. [PR #1091](https://github.com/shakacode/shakapacker/pull/1091) by [ihabadham](https://github.com/ihabadham). `lib/install/package.json` now declares `@rspack/core` and `@rspack/cli` as `^1.0.0 || ^2.0.0-0`; fresh installs pick the v2 range. Existing apps are unaffected. Note: Rspack v2 requires Node.js 20.19.0+.
+- **Slimmed the published gem from ~486K (294 files) to ~121K (75 files)**. [PR #1110](https://github.com/shakacode/shakapacker/pull/1110) by [justin808](https://github.com/justin808). Replaced the broad `git ls-files` gem manifest with an explicit runtime/install allowlist (`CHANGELOG.md`, `MIT-LICENSE`, `README.md`, gemspec, `lib`, `sig`), excluding repo-only docs, tests, JavaScript package source, CI/tooling files, and `test_files` metadata from the published gem. Fixes [#987](https://github.com/shakacode/shakapacker/issues/987).
+
+### Fixed
+
+- **Fixed webpack-dev-server `static` config defaulting to watch `public/` directory unnecessarily**. [PR #1032](https://github.com/shakacode/shakapacker/pull/1032) by [ihabadham](https://github.com/ihabadham). Three bugs fixed: (1) `static` now defaults to `false` instead of a misconfigured object that caused webpack-dev-server to watch the `public/` directory, which is already served by Rails via `ActionDispatch::Static`; (2) setting `static: false` in `shakapacker.yml` is no longer silently ignored; (3) the default template no longer includes `static.watch`, which was a v3→v4 migration artifact. Fixes [#1031](https://github.com/shakacode/shakapacker/issues/1031).
+- **Fixed Rspack React Refresh plugin loading with `@rspack/plugin-react-refresh` v2**. [PR #1116](https://github.com/shakacode/shakapacker/pull/1116) by [justin808](https://github.com/justin808). Shakapacker now reads the v2 named `ReactRefreshRspackPlugin` export while retaining compatibility with v1 direct/default CommonJS export shapes, preventing `TypeError: ReactRefreshRspackPlugin is not a constructor` during rspack dev-server startup.
+- **Widened `@rspack/plugin-react-refresh` peer range to `^1.0.0 || ^2.0.0-0`**. [PR #1091](https://github.com/shakacode/shakapacker/pull/1091) by [ihabadham](https://github.com/ihabadham). Fixes the `ERESOLVE` conflict when installing `@rspack/plugin-react-refresh@^2.0.0` alongside `shakapacker@10.0.0`.
+- **Fixed `NodePackageVersion#find_version` for local-path `shakapacker` installs (e.g. `yalc`, `file:`, relative paths)**. [PR #1086](https://github.com/shakacode/shakapacker/pull/1086) by [justin808](https://github.com/justin808). The version check now consults `package.json` first and short-circuits on `../` or `file:` dependencies, so stale lockfile semvers no longer trigger false gem↔node version mismatches. `package_json_dependency` also consults `devDependencies` in addition to `dependencies`. The `LOCAL_PATH_REGEX` constant replaces a duplicated inline regex and anchors both alternatives to the start of the string, removing a latent false-positive on version strings containing `..` mid-value.
+- **Detected single-dot (`./...`) local-path declarations in `NodePackageVersion#find_version`**. [PR #1106](https://github.com/shakacode/shakapacker/pull/1106) by [justin808](https://github.com/justin808). Extended `LOCAL_PATH_REGEX` to treat `./vendor/shakapacker`-style declarations as local-path installs (alongside the `../` and `file:` patterns added in [#1086](https://github.com/shakacode/shakapacker/pull/1086)), so version checks short-circuit before consulting potentially stale lockfile semvers. Fixes [#1103](https://github.com/shakacode/shakapacker/issues/1103).
+- **Fix rspack setup not reusing certain shared webpack-rspack config settings**. [PR #1085](https://github.com/shakacode/shakapacker/pull/1085) by [brunodccarvalho](https://github.com/brunodccarvalho). Default config changes include `optimization.splitChunks.chunks="all"`, `optimization.runtimeChunk="single"`, the webpack compression plugin in production, and the removal of minimization plugins in development. Fixes [#984](https://github.com/shakacode/shakapacker/issues/984).
+- **Fixed Rspack Sass rule blocking `sass-embedded` users by requiring the `sass` package**. [PR #1105](https://github.com/shakacode/shakapacker/pull/1105) by [justin808](https://github.com/justin808). Rspack Sass detection now only checks for `sass-loader`; the implementation (`sass`, `sass-embedded`, etc.) is resolved by the loader at build time, matching the webpack code path.
+- **Fixed `bin/shakapacker-config` and `bin/diff-bundler-config` in ESM apps**. [PR #1104](https://github.com/shakacode/shakapacker/pull/1104) by [justin808](https://github.com/justin808). Apps with `"type": "module"` in `package.json` failed to run the JavaScript binstubs because Node parsed them as ESM. The binstubs are now Ruby wrappers that locate Node and invoke `.cjs` package scripts shipped inside `node_modules/shakapacker/package/bin/`. Existing apps with the old JavaScript binstubs should re-run `bundle exec rake shakapacker:binstubs` to install the new Ruby wrappers.
+
 ## [v10.0.0] - April 8, 2026
 
 ### Added
@@ -909,7 +947,8 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v10.0.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v10.1.0-rc.1...main
+[v10.1.0-rc.1]: https://github.com/shakacode/shakapacker/compare/v10.0.0...v10.1.0-rc.1
 [v10.0.0]: https://github.com/shakacode/shakapacker/compare/v9.7.0...v10.0.0
 [v9.7.0]: https://github.com/shakacode/shakapacker/compare/v9.6.1...v9.7.0
 [v9.6.1]: https://github.com/shakacode/shakapacker/compare/v9.6.0...v9.6.1

data/README.md

@@ -1,8 +1,8 @@
-# Shakapacker (v9)
+# Shakapacker (v10)
 
 ---
 
-_🚀 Shakapacker 9 supports [Rspack](https://rspack.rs/)! 10x faster than webpack!_
+_🚀 Shakapacker 10 supports [Rspack](https://rspack.rs/) — up to 17x faster than webpack per [upstream benchmarks](./docs/transpiler-performance.md#published-benchmarks)!_
 
 _📖 **Full documentation at [shakapacker.com](https://shakapacker.com)**_
 
@@ -11,7 +11,8 @@ _📖 **Full documentation at [shakapacker.com](https://shakapacker.com)**_
 _Official, actively maintained successor to [rails/webpacker](https://github.com/rails/webpacker). ShakaCode stands behind the long-term maintenance and development of this project for the Rails community._
 
 - ⚠️ See the [6-stable](https://github.com/shakacode/shakapacker/tree/6-stable) branch for Shakapacker v6.x code and documentation. :warning:
-- **See [V9 Upgrade](./docs/v9_upgrade.md) for upgrading from the v8 release.**
+- **See the [v10.0.0 release notes](https://github.com/shakacode/shakapacker/releases/tag/v10.0.0) for upgrading from v9 to v10.**
+- **See [V9 Upgrade](./docs/v9_upgrade.md) for upgrading from v8 to v9.**
 - See [V8 Upgrade](./docs/v8_upgrade.md) for upgrading from the v7 release.
 - See [V7 Upgrade](./docs/v7_upgrade.md) for upgrading from the v6 release.
 - See [V6 Upgrade](./docs/v6_upgrade.md) for upgrading from v5 or prior v6 releases.
@@ -21,7 +22,7 @@ _Official, actively maintained successor to [rails/webpacker](https://github.com
 [![Rubocop](https://github.com/shakacode/shakapacker/workflows/Rubocop/badge.svg)](https://github.com/shakacode/shakapacker/actions)
 [![JS lint](https://github.com/shakacode/shakapacker/workflows/JS%20lint/badge.svg)](https://github.com/shakacode/shakapacker/actions)
 
-[![node.js](https://img.shields.io/badge/node-%3E%3D%2020-brightgreen.svg)](https://www.npmjs.com/package/shakapacker)
+[![node.js](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.12.0-brightgreen.svg)](https://www.npmjs.com/package/shakapacker)
 [![Gem](https://img.shields.io/gem/v/shakapacker.svg)](https://rubygems.org/gems/shakapacker)
 [![npm version](https://badge.fury.io/js/shakapacker.svg)](https://badge.fury.io/js/shakapacker)
 
@@ -133,7 +134,7 @@ Here's a testimonial from Jon Rajavuori of [Academia.edu](https://www.academia.e
 
 - Ruby 2.7+
 - Rails 5.2+
-- Node.js 20+
+- Node.js `^20.19.0` or `>=22.12.0`
 
 ## Features
 
@@ -159,6 +160,8 @@ _Requires extra packages to be installed._
 
 ## Installation
 
+See the [Installation guide](./docs/installation.md) for a step-by-step walkthrough.
+
 ### Rails v6+
 
 With Rails v6+, skip JavaScript for a new app and follow below Manual Installation Steps to manually add the `shakapacker` gem to your Gemfile.
@@ -238,7 +241,7 @@ Depending on your setup, you'll need different subsets of the optional peer depe
 ```json
 {
   "dependencies": {
-    "shakapacker": "^9.0.0",
+    "shakapacker": "^10.0.0",
     "@babel/core": "^7.17.9",
     "@babel/plugin-transform-runtime": "^7.17.0",
     "@babel/preset-env": "^7.16.11",
@@ -261,7 +264,7 @@ Depending on your setup, you'll need different subsets of the optional peer depe
 ```json
 {
   "dependencies": {
-    "shakapacker": "^9.0.0",
+    "shakapacker": "^10.0.0",
     "@swc/core": "^1.3.0",
     "swc-loader": "^0.2.0",
     "compression-webpack-plugin": "^9.0.0",
@@ -274,14 +277,14 @@ Depending on your setup, you'll need different subsets of the optional peer depe
 }
 ```
 
-**For Rspack + SWC (10x faster bundling):**
+**For Rspack + SWC (largest end-to-end speedup — see [transpiler-performance guide](./docs/transpiler-performance.md#published-benchmarks)):**
 
 ```json
 {
   "dependencies": {
-    "shakapacker": "^9.0.0",
-    "@rspack/core": "^1.0.0",
-    "@rspack/cli": "^1.0.0",
+    "shakapacker": "^10.0.0",
+    "@rspack/core": "^2.0.0-0",
+    "@rspack/cli": "^2.0.0-0",
     "@swc/core": "^1.3.0",
     "swc-loader": "^0.2.0",
     "rspack-manifest-plugin": "^5.0.0"
@@ -923,7 +926,7 @@ You can also change your Babel configuration by removing these lines in your `pa
 
 ### SWC configuration
 
-SWC is the recommended JavaScript transpiler in Shakapacker v9+ (20x faster than Babel). New installations use SWC by default via the installation template. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
+SWC is the recommended JavaScript transpiler in Shakapacker v10 (this default was introduced in v9). SWC's own benchmark reports being [20x faster than Babel on a single thread and 70x faster on four cores](https://swc.rs/); end-to-end Shakapacker speedups are typically smaller but still substantial. New installations use SWC by default via the installation template. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
 
 **Note on defaults**: The installation template explicitly sets `javascript_transpiler: "swc"` for new projects. However, for backward compatibility, webpack's runtime default (when no explicit config exists) remains `"babel"`. Rspack always defaults to `"swc"`.
 
@@ -1272,13 +1275,19 @@ npm install shakapacker@next
 
 Also, consult the [CHANGELOG](./CHANGELOG.md) for additional upgrade links.
 
+#### Automating Updates with Dependabot
+
+Shakapacker is shipped as both a Ruby gem and an npm package, so they must be
+upgraded together. See [Dependabot configuration for Shakapacker](./docs/dependabot.md)
+for a `.github/dependabot.yml` example that updates both in a single PR.
+
 #### Common Upgrade Scenarios
 
 For step-by-step guides on common migrations, see the [Common Upgrades Guide](./docs/common-upgrades.md):
 
 - [Migrating Package Managers](./docs/common-upgrades.md#migrating-package-managers) (Yarn ↔ npm, pnpm)
-- [Migrating from Babel to SWC](./docs/common-upgrades.md#migrating-from-babel-to-swc) (20-70x faster builds)
-- [Migrating from Webpack to Rspack](./docs/common-upgrades.md#migrating-from-webpack-to-rspack) (5-10x faster builds)
+- [Migrating from Babel to SWC](./docs/common-upgrades.md#migrating-from-babel-to-swc) (upstream: ~20x faster transpilation)
+- [Migrating from Webpack to Rspack](./docs/common-upgrades.md#migrating-from-webpack-to-rspack) (upstream: ~8–17x faster bundler)
 
 ### Paths
 

data/lib/install/bin/diff-bundler-config

@@ -1,64 +1,45 @@
-#!/usr/bin/env node
-
-const { createRequire } = require("module")
-
-const PACK_CONFIG_DIFF_PACKAGE = "pack-config-diff"
-
-function formatError(error) {
-  return error instanceof Error ? error.message : String(error)
-}
-
-function exitWithCode(exitCode) {
-  if (!Number.isInteger(exitCode)) {
-    console.error(
-      `[Shakapacker] ${PACK_CONFIG_DIFF_PACKAGE} returned a non-integer exit code: ${String(exitCode)}`
-    )
-    process.exit(2)
-  }
-
-  // Forward only pack-config-diff's documented exit codes (0 = no diffs, 1 = diffs found).
-  // Any other code is a tool failure — normalize to 2.
-  process.exit(exitCode <= 1 ? exitCode : 2)
-}
-
-let run
-
-try {
-  // Resolve pack-config-diff via shakapacker's dependency tree so strict package
-  // managers (pnpm, Yarn PnP) can find the transitive dependency.
-  const shakapackerRequire = createRequire(
-    require.resolve("shakapacker/package.json")
-  )
-  const loadedModule = shakapackerRequire("pack-config-diff")
-  run = loadedModule.run
-} catch (error) {
-  console.error(
-    `[Shakapacker] Failed to load ${PACK_CONFIG_DIFF_PACKAGE}: ${formatError(error)}`
-  )
-  process.exit(2)
-}
-
-if (typeof run !== "function") {
-  console.error(
-    `[Shakapacker] ${PACK_CONFIG_DIFF_PACKAGE} did not export a run() function`
-  )
-  process.exit(2)
-}
-
-try {
-  const runResult = run(process.argv.slice(2))
-
-  if (runResult && typeof runResult.then === "function") {
-    runResult
-      .then((exitCode) => exitWithCode(exitCode))
-      .catch((error) => {
-        console.error(formatError(error))
-        process.exit(2)
-      })
-  } else {
-    exitWithCode(runResult)
-  }
-} catch (error) {
-  console.error(formatError(error))
-  process.exit(2)
-}
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Keep in sync with lib/install/bin/shakapacker-config and the template in
+# package/configExporter/cli.ts (createBinStub).
+def shakapacker_app_root
+  candidate = File.expand_path("..", __dir__)
+  return candidate if File.exist?(File.join(candidate, "Gemfile"))
+
+  warn "[Shakapacker] No Gemfile found at #{candidate.inspect}; " \
+       "falling back to the current directory (#{Dir.pwd.inspect})."
+  Dir.pwd
+end
+
+def shakapacker_node_binary
+  node_bin = "node"
+  return node_bin if system(node_bin, "--version", out: File::NULL, err: File::NULL)
+
+  warn "[Shakapacker] Could not find Node.js executable #{node_bin.inspect}. " \
+       "Install Node.js and try again."
+  exit 1
+end
+
+ENV["RAILS_ENV"] ||= ENV["RACK_ENV"] || "development"
+ENV["NODE_ENV"] ||= "development"
+
+app_root = shakapacker_app_root
+node_bin = shakapacker_node_binary
+script_path = File.join(
+  app_root,
+  "node_modules",
+  "shakapacker",
+  "package",
+  "bin",
+  "diff-bundler-config.cjs"
+)
+
+unless File.file?(script_path)
+  warn "[Shakapacker] Could not find #{script_path}. Run your package manager install command and try again."
+  exit 1
+end
+
+Dir.chdir(app_root) do
+  exec node_bin, script_path, *ARGV
+end

data/lib/install/bin/shakapacker-config

@@ -1,11 +1,45 @@
-#!/usr/bin/env node
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-// Minimal shim - all logic is in the TypeScript module
-const { run } = require("shakapacker/configExporter")
+# Keep in sync with lib/install/bin/diff-bundler-config and the template in
+# package/configExporter/cli.ts (createBinStub).
+def shakapacker_app_root
+  candidate = File.expand_path("..", __dir__)
+  return candidate if File.exist?(File.join(candidate, "Gemfile"))
 
-run(process.argv.slice(2))
-  .then((exitCode) => process.exit(exitCode))
-  .catch((error) => {
-    console.error(error.message)
-    process.exit(1)
-  })
+  warn "[Shakapacker] No Gemfile found at #{candidate.inspect}; " \
+       "falling back to the current directory (#{Dir.pwd.inspect})."
+  Dir.pwd
+end
+
+def shakapacker_node_binary
+  node_bin = "node"
+  return node_bin if system(node_bin, "--version", out: File::NULL, err: File::NULL)
+
+  warn "[Shakapacker] Could not find Node.js executable #{node_bin.inspect}. " \
+       "Install Node.js and try again."
+  exit 1
+end
+
+ENV["RAILS_ENV"] ||= ENV["RACK_ENV"] || "development"
+ENV["NODE_ENV"] ||= "development"
+
+app_root = shakapacker_app_root
+node_bin = shakapacker_node_binary
+script_path = File.join(
+  app_root,
+  "node_modules",
+  "shakapacker",
+  "package",
+  "bin",
+  "shakapacker-config.cjs"
+)
+
+unless File.file?(script_path)
+  warn "[Shakapacker] Could not find #{script_path}. Run your package manager install command and try again."
+  exit 1
+end
+
+Dir.chdir(app_root) do
+  exec node_bin, script_path, *ARGV
+end

data/lib/install/config/shakapacker.yml

@@ -165,9 +165,6 @@ development:
     # port than your Rails server and the browser blocks cross-origin asset requests):
     # headers:
     #   "Access-Control-Allow-Origin": "*"
-    static:
-      watch:
-        ignored: "**/node_modules/**"
 
 test:
   <<: *default

data/lib/install/package.json

@@ -1,7 +1,7 @@
 {
   "rspack": {
-    "@rspack/cli": "^1.0.0",
-    "@rspack/core": "^1.0.0",
+    "@rspack/cli": "^1.0.0 || ^2.0.0-0",
+    "@rspack/core": "^1.0.0 || ^2.0.0-0",
     "rspack-manifest-plugin": "^5.0.0"
   },
   "webpack": {

data/lib/shakapacker/compiler.rb

@@ -9,6 +9,14 @@ class Shakapacker::Compiler
   # Shakapacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
   cattr_accessor(:env) { {} }
 
+  # Class-level state keeps the compile-time doctor hint once-per-process.
+  @doctor_hint_shown = false
+  DOCTOR_HINT_MUTEX = Mutex.new
+
+  class << self
+    attr_accessor :doctor_hint_shown
+  end
+
   delegate :config, :logger, :strategy, to: :instance
   delegate :fresh?, :stale?, :after_compile_hook, to: :strategy
 
@@ -184,6 +192,7 @@ class Shakapacker::Compiler
       else
         non_empty_streams = [stdout, stderr].delete_if(&:empty?)
         logger.error "\nCOMPILATION FAILED:\nEXIT STATUS: #{status}\nOUTPUTS:\n#{non_empty_streams.join("\n\n")}"
+        show_doctor_hint_once
       end
 
       status.success?
@@ -201,4 +210,24 @@ class Shakapacker::Compiler
     def bin_shakapacker_path
       config.root_path.join("bin/shakapacker")
     end
+
+    # Fires only after a failed compile, so users in a healthy loop never see the tip.
+    def show_doctor_hint_once
+      return if self.class.doctor_hint_shown
+
+      DOCTOR_HINT_MUTEX.synchronize do
+        return if self.class.doctor_hint_shown
+
+        begin
+          logger.info "Tip: run 'bundle exec rake shakapacker:doctor' to diagnose configuration issues."
+        rescue StandardError => _e
+          # Non-critical tip; never abort a build because the logger failed.
+          # Named (but unused) variable makes the deliberate swallow explicit.
+          return
+        end
+
+        # Assignment is outside the rescue so a flag-setter failure propagates rather than being silenced.
+        self.class.doctor_hint_shown = true
+      end
+    end
 end