RFC: Tighten dependencies for Shakapacker v11

CHANGELOG.md

@@ -9,6 +9,20 @@
 
 ## [Unreleased]
 
+### 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.
+
+### 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.

docs/blog/2026-05-10-shakapacker-10-1-supplemental-packages.md

@@ -0,0 +1,75 @@
+# Shakapacker 10.1: One-Package Installs with `shakapacker-rspack` and `shakapacker-webpack`
+
+**Date:** 2026-05-10
+**Author:** Justin Gordon
+
+Shakapacker 10.1 ships two new optional npm packages — `shakapacker-rspack` and `shakapacker-webpack` — that turn a four-or-five-package install into one. Same Shakapacker, simpler `package.json`.
+
+## The 30-second pitch
+
+If you're starting a new app today:
+
+```sh
+yarn add --dev shakapacker-rspack
+```
+
+That's it. You get `shakapacker`, `@rspack/core`, `@rspack/cli`, and `rspack-manifest-plugin` together, all pinned to the exact versions Shakapacker is tested against. Webpack users get the same shape with `shakapacker-webpack`.
+
+If you're already on Shakapacker 10.0, you can drop the now-bundled deps from your `devDependencies` and rely on the supplemental package to bring them along. Nothing breaks if you don't.
+
+## What changed
+
+Until now, a typical Shakapacker install meant listing the gem, the npm package, the bundler, the bundler's CLI, the manifest plugin, and your transpiler — all as direct dependencies. That worked, but it pushed the version-matching problem onto every user. Were you on a tested combination? You had to read the changelog to find out.
+
+10.1 shifts that responsibility to the supplemental packages. Each one declares the bundler stack as direct `dependencies` with patch-tolerant `~X.Y.Z` ranges:
+
+- `shakapacker-rspack` bundles `shakapacker`, `@rspack/core`, `@rspack/cli`, `rspack-manifest-plugin`.
+- `shakapacker-webpack` bundles `shakapacker`, `webpack`, `webpack-cli`, `webpack-assets-manifest`.
+
+Optional features — transpilers (swc / babel / esbuild for webpack), CSS preprocessors, dev-server, react-refresh — stay as opt-in `peerDependencies` so you only download what you actually use. (Bundling sass into every install would force a 10MB native-binding download on apps that don't even import a `.scss` file. We're not doing that.)
+
+## Adopting in an existing app
+
+Replace the explicit deps with the supplemental package:
+
+```diff
+ {
+   "devDependencies": {
+-    "shakapacker": "^10.0.0",
+-    "@rspack/core": "^2.0.0",
+-    "@rspack/cli": "^2.0.0",
+-    "rspack-manifest-plugin": "^5.0.0"
++    "shakapacker-rspack": "~10.1.0"
+   }
+ }
+```
+
+Run `yarn install`. No changes to `config/shakapacker.yml`, `bin/shakapacker`, or your bundler config are required. The full step-by-step (including the webpack flow and the optional-peer cheatsheet) lives in [`docs/migration/v10.1-supplemental-packages.md`](../migration/v10.1-supplemental-packages.md).
+
+## What if I don't want to migrate?
+
+Don't. Adoption is opt-in for the entire 10.x line. Apps that keep their existing `package.json` will continue to work exactly as they did on 10.0. The supplemental packages are the recommended path for new projects and a cleanup for existing ones, not a forced upgrade.
+
+## Runtime safety net
+
+The supplemental packages emit two structured warnings (via Node's built-in `process.emitWarning`) when your config and your installed peers disagree:
+
+- `SHAKAPACKER_BUNDLER_MISMATCH` — you installed `shakapacker-webpack` but `config/shakapacker.yml` says `assets_bundler: rspack` (or vice versa).
+- `SHAKAPACKER_NO_TRANSPILER` — the configured `javascript_transpiler:` doesn't have its loader pair installed (e.g., `swc` configured but `@swc/core`/`swc-loader` aren't resolvable).
+
+Both are visible by default in dev and CI, suppressible with `--no-warnings`, and fire before your bundler throws a confusing module-not-found error.
+
+## Looking ahead to v11
+
+v11 will make the supplemental packages required for managed builds — core `shakapacker` will stop declaring bundler peer deps and apps that haven't adopted a supplemental package will need to switch. Custom-build users (apps that produce their own `manifest.json` from Vite, esbuild, or a hand-rolled webpack config) keep using bare `shakapacker` and aren't affected.
+
+There's no firm v11 date yet. The 10.1 line is intentionally a soak period — we want real-world adoption signal on the supplemental packages before locking the design in. The full design rationale and roadmap lives in [`docs/dependency-strategy.md`](../dependency-strategy.md).
+
+## Try it
+
+- Migration guide: [`docs/migration/v10.1-supplemental-packages.md`](../migration/v10.1-supplemental-packages.md)
+- `shakapacker-rspack` README: [`packages/shakapacker-rspack/README.md`](../../packages/shakapacker-rspack/README.md)
+- `shakapacker-webpack` README: [`packages/shakapacker-webpack/README.md`](../../packages/shakapacker-webpack/README.md)
+- Design rationale: [`docs/dependency-strategy.md`](../dependency-strategy.md)
+
+Bug reports, feedback, and "this didn't work for me" stories all welcome on [GitHub issues](https://github.com/shakacode/shakapacker/issues) — we're using the 10.1 soak window to find rough edges before v11 closes the door.