Update CHANGELOG.md for v10.1.0 (#1139)

## Summary

Stamps the v10.1.0 stable release header (was `v10.1.0-rc.2`) and
curates the prerelease entries per `/update-changelog` guidance.

## Curation applied

- **Merged PR #1133 → PR #1096** (Added: supplemental npm packages).
#1133 restructured the supplemental deps from direct → peer in rc.2, so
the original entry's "bundle the managed-build stack as direct
dependencies" description was wrong for stable consumers. Rewrote to
describe the final peer-deps shape (auto-installed on npm 7+) and credit
both PRs. The #1133 standalone Changed entry was removed.
- **Merged PR #1132 → PR #1104** (Fixed: ESM binstubs). #1132 fixed the
`export_bundler_config` dispatch regression that #1104 introduced in
rc.1 when switching from JS to Ruby binstubs; stable users never see the
bug, so the fix is RC-only churn that belongs folded into the original
entry. Also folded in #1132's minor improvements (NODE_ENV from
RAILS_ENV mapping, Node lookup without execution, friendlier non-Error
CLI messages).
- **Merged PR #1106 → PR #1086** (Fixed: local-path version detection).
Both shipped in rc.0 as iterations of the same regex fix; merged into a
single entry covering `../`, `./`, and `file:` patterns.
- **Lightened Migration Notes**: removed "bundled stack" language now
that supplementals declare required peers instead of direct deps.
- **Skipped post-rc.2 commit**: PR #1138 (skill tooling guidance) is
internal — not user-visible.
- **Compare links**: `[Unreleased]` now points from `v10.1.0`; replaced
`[v10.1.0-rc.2]` with `[v10.1.0]: v10.0.0...v10.1.0`.

## Test plan

- [x] `yarn lint` passes
- [x] `yarn prettier --check CHANGELOG.md` passes
- [x] File ends with trailing newline
- [x] No duplicate section headings
- [x] All merged PRs credited

After merge, run `bundle exec rake release` (no args) — the rake task
picks up `v10.1.0` from CHANGELOG.md and auto-creates the GitHub
release.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation-only changelog edits with no runtime or dependency
behavior changes.
> 
> **Overview**
> **Curates `CHANGELOG.md` for the v10.1.0 stable release** (replacing
the `v10.1.0-rc.2` header dated May 25, 2026) so release notes match
what stable users actually ship.
> 
> Prerelease churn is folded into fewer, accurate bullets: supplemental
npm packages (**#1096** + **#1133**) now describe **required peer
dependencies** (not direct “bundled” deps), with the standalone
**#1133** *Changed* entry removed; ESM/config binstub fixes (**#1104** +
**#1132**) and local-path version detection (**#1086** + **#1106**) are
single *Fixed* items. **Migration Notes** no longer imply a direct
bundled stack on supplementals.
> 
> Footer compare links: **`[Unreleased]`** from `v10.1.0`,
**`[v10.1.0]`** replaces the rc.2 link (`v10.0.0...v10.1.0`).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
2b57d5f. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: justin808

CHANGELOG.md

@@ -9,17 +9,17 @@
 
 ## [Unreleased]
 
-## [v10.1.0-rc.2] - May 23, 2026
+## [v10.1.0] - May 27, 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 supplemental npm packages `shakapacker-webpack` and `shakapacker-rspack`**. [PR #1096](https://github.com/shakacode/shakapacker/pull/1096), [PR #1133](https://github.com/shakacode/shakapacker/pull/1133) by [justin808](https://github.com/justin808). Optional packages that lockstep with core and declare the managed-build stack as required peer dependencies (so on npm 7+ a single `yarn add shakapacker-webpack` auto-installs `shakapacker`, `webpack`, `webpack-cli`, and `webpack-assets-manifest`; `shakapacker-rspack` declares `shakapacker`, `@rspack/core`, `@rspack/cli`, and `rspack-manifest-plugin`). Required peers eliminate the silent duplicate-bundler failure mode that direct dependencies could cause when an app or transitive dep pins a different bundler version. 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. pnpm and Yarn PnP users should keep packages imported by app config files as explicit app dependencies (the Rails installer handles this automatically). 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:
+- **Simplify your `package.json` by adopting a supplemental package**. On npm 7+ (or Yarn 2+ in `nodeLinker: node-modules` mode), existing apps can drop the explicit managed-build deps from `devDependencies` and let the supplemental package's required peers be auto-installed:
   - **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.
@@ -33,21 +33,18 @@
 
 ### Changed
 
-- **Restructured `shakapacker-webpack` and `shakapacker-rspack` dependency declarations**. [PR #1133](https://github.com/shakacode/shakapacker/pull/1133) by [justin808](https://github.com/justin808). In response to [#1131](https://github.com/shakacode/shakapacker/issues/1131), bundler singletons (`webpack`, `webpack-cli`, `webpack-assets-manifest` for webpack; `@rspack/core`, `@rspack/cli`, `rspack-manifest-plugin` for rspack) are now **required peer dependencies** instead of direct `dependencies`. This eliminates the silent duplicate-bundler failure mode that direct deps could cause when an app or transitive dep pinned a different bundler version. npm 7+ auto-installs required peers, preserving the one-command install experience there; pnpm and Yarn PnP users should keep packages imported by app config files as explicit app dependencies (the Rails installer handles this automatically). The tilde (`~`) constraints from the v10.1.0-rc.1 shape have also been loosened to caret (`^`) for all non-`shakapacker` packages, so consumers can pick up upstream patch/minor releases without waiting for a coordinated Shakapacker release. `terser-webpack-plugin` moved from optional peer to direct dependency on `shakapacker-webpack` because `package/optimization/webpack.ts` always requires it for the default production minimizer.
 - **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), [PR #1120](https://github.com/shakacode/shakapacker/pull/1120) 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`, `package.json`), 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 config helper binstubs and `shakapacker:export_bundler_config` dispatch for upgraded apps**. [PR #1132](https://github.com/shakacode/shakapacker/pull/1132) by [justin808](https://github.com/justin808). The export task now runs legacy JavaScript `bin/shakapacker-config` binstubs via Node while keeping Ruby binstubs on Ruby. Generated helper binstubs now map `NODE_ENV` from `RAILS_ENV`, locate Node without executing it during lookup, and print useful messages for non-`Error` CLI rejections. Fixes [#1123](https://github.com/shakacode/shakapacker/issues/1123).
 - **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).
+- **Fixed `NodePackageVersion#find_version` for local-path `shakapacker` installs (e.g. `yalc`, `file:`, relative paths)**. [PR #1086](https://github.com/shakacode/shakapacker/pull/1086), [PR #1106](https://github.com/shakacode/shakapacker/pull/1106) by [justin808](https://github.com/justin808). The version check now consults `package.json` first and short-circuits on `../`, `./`, and `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. 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.
+- **Fixed `bin/shakapacker-config` and `bin/diff-bundler-config` in ESM apps and on upgraded apps**. [PR #1104](https://github.com/shakacode/shakapacker/pull/1104), [PR #1132](https://github.com/shakacode/shakapacker/pull/1132) 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 (without executing it during lookup) and invoke `.cjs` package scripts shipped inside `node_modules/shakapacker/package/bin/`. The wrappers also map `NODE_ENV` from `RAILS_ENV` and print useful messages for non-`Error` CLI rejections. `shakapacker:export_bundler_config` dispatches binstubs by shebang, so upgraded apps with legacy JavaScript binstubs continue to run via Node while Ruby wrappers run via Ruby. Existing apps with the old JavaScript binstubs should re-run `bundle exec rake shakapacker:binstubs` to install the new Ruby wrappers. Fixes [#1123](https://github.com/shakacode/shakapacker/issues/1123).
 
 ## [v10.0.0] - April 8, 2026
 
@@ -949,8 +946,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.1.0-rc.2...main
-[v10.1.0-rc.2]: https://github.com/shakacode/shakapacker/compare/v10.0.0...v10.1.0-rc.2
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v10.1.0...main
+[v10.1.0]: https://github.com/shakacode/shakapacker/compare/v10.0.0...v10.1.0
 [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