Surface v10.1 supplemental packages from README and key docs (#1134)

### Summary

v10.1 added optional `shakapacker-webpack` and `shakapacker-rspack`
packages with a dedicated migration guide at
`docs/migration/v10.1-supplemental-packages.md`, but the guide was only
linked from `CHANGELOG.md` and `docs/dependency-strategy.md`. Users
arriving via `README.md`, `docs/installation.md`, or `docs/rspack.md`
would follow the old multi-dep install flow without ever learning the
supplemental packages exist. This PR adds cross-references from those
entry points plus `docs/common-upgrades.md` and the two peer-dependency
docs so the migration guide is discoverable. The guide content itself is
unchanged.

Files touched:

- `README.md` — added a v10.1 callout in the upgrade-links list
- `docs/installation.md` — added an "Optional: Consolidate dev
dependencies (10.1+)" subsection after "Run the Installer"
- `docs/rspack.md` — added a "Recommended (10.1+): `shakapacker-rspack`"
block at the top of Installation; kept the manual install as the
alternative for 10.0 and custom setups
- `docs/common-upgrades.md` — added an "Adopting Supplemental Packages
(10.1+)" top-level section + TOC entry
- `docs/peer-dependencies.md` and `docs/optional-peer-dependencies.md` —
added tips pointing at supplementals as an alternative to managing
individual peers

### Pull Request checklist

- ~[ ] Add/update test to cover these changes~ (docs-only)
- [x] Update documentation
- ~[ ] Update CHANGELOG file~ (per project rules, docs fixes don't get
CHANGELOG entries)

### Other Information

All link targets (`docs/migration/v10.1-supplemental-packages.md` and
the two `packages/shakapacker-*/README.md` files) verified to exist;
relative paths resolve correctly from each doc's location.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk docs-only change that adds cross-links and updated install
guidance; no runtime or dependency behavior changes.
> 
> **Overview**
> **Improves discoverability of Shakapacker 10.1 supplemental
packages.** The README and several entry-point docs now call out
optional `shakapacker-webpack`/`shakapacker-rspack` packages and link to
the `v10.1 supplemental packages migration guide`.
> 
> Installation/upgrade guidance is adjusted to present supplemental
packages as the recommended single-dependency path (with manual
multi-dependency install as an alternative) and adds a new `Common
Upgrades` section describing when to adopt (or avoid) these packages.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
ef3df46. 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

README.md

@@ -11,6 +11,7 @@ _📖 **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:
+- **New in 10.1: optional `shakapacker-webpack` and `shakapacker-rspack` packages let you replace four `devDependencies` with one. See the [v10.1 supplemental packages migration guide](./docs/migration/v10.1-supplemental-packages.md).**
 - **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.

docs/common-upgrades.md

@@ -7,6 +7,7 @@ This document provides step-by-step instructions for the most common upgrade sce
 ## Table of Contents
 
 - [Upgrading Shakapacker](#upgrading-shakapacker)
+- [Adopting Supplemental Packages (10.1+)](#adopting-supplemental-packages-101)
 - [Automating Updates with Dependabot](#automating-updates-with-dependabot)
 - [Migrating Package Managers](#migrating-package-managers)
   - [Yarn to npm](#yarn-to-npm)
@@ -97,6 +98,22 @@ For major version upgrades, always consult the version-specific upgrade guides f
 
 ---
 
+## Adopting Supplemental Packages (10.1+)
+
+Shakapacker 10.1 introduces two optional npm packages — `shakapacker-webpack` and `shakapacker-rspack` — that bundle the managed-build stack as direct dependencies. Adopting one of them lets you replace four explicit `devDependencies` (`shakapacker` + bundler + CLI + manifest plugin) with a single package that lockstep-pins to the exact versions Shakapacker is tested against.
+
+**This is opt-in.** Apps that don't change anything keep working on 10.1 exactly as they did on 10.0.
+
+**Rspack apps** can replace `shakapacker` + `@rspack/core` + `@rspack/cli` + `rspack-manifest-plugin` with a single `shakapacker-rspack` dev dependency.
+
+**Webpack apps** can replace `shakapacker` + `webpack` + `webpack-cli` + `webpack-assets-manifest` with a single `shakapacker-webpack` dev dependency. One caveat: `shakapacker-webpack` pins `webpack-assets-manifest` to `~6.5.1`, so apps still on `webpack-assets-manifest@5.x` need to upgrade to v6 when adopting it.
+
+**Custom-build apps** (apps that ship their own webpack/rspack/Vite setup and only use Shakapacker to read `manifest.json`) should **not** install a supplemental package — continue using bare `shakapacker`.
+
+See the [v10.1 supplemental packages migration guide](./migration/v10.1-supplemental-packages.md) for before/after `package.json` snippets, the `webpack-assets-manifest` v5→v6 upgrade notes, and the v11 roadmap context. The per-package install references live at [`packages/shakapacker-webpack/README.md`](../packages/shakapacker-webpack/README.md) and [`packages/shakapacker-rspack/README.md`](../packages/shakapacker-rspack/README.md).
+
+---
+
 ## Automating Updates with Dependabot
 
 Because Shakapacker ships as both a Ruby gem and an npm package, both sides must

docs/installation.md

@@ -62,6 +62,20 @@ SKIP=true bundle exec rake shakapacker:install
 Accepted truthy values for `FORCE` and `SKIP` are `true`, `1`, and `yes`
 case-insensitively. If both are set, `FORCE` wins.
 
+### Optional: Consolidate dev dependencies with a supplemental package (10.1+)
+
+The installer adds the managed-build stack to `package.json` as individual
+entries (`shakapacker`, `webpack`, `webpack-cli`, `webpack-assets-manifest` for
+webpack apps; `shakapacker`, `@rspack/core`, `@rspack/cli`,
+`rspack-manifest-plugin` for rspack apps). On Shakapacker 10.1+ you can
+optionally replace those four entries with a single
+[`shakapacker-webpack`](../packages/shakapacker-webpack/README.md) or
+[`shakapacker-rspack`](../packages/shakapacker-rspack/README.md) dependency.
+The supplemental package pulls in the same managed stack at the exact tested
+versions and has no runtime impact — adoption is opt-in. See the
+[v10.1 supplemental packages migration guide](./migration/v10.1-supplemental-packages.md)
+for the before/after.
+
 ## Package Manager Selection
 
 Shakapacker uses the

docs/optional-peer-dependencies.md

@@ -1,5 +1,17 @@
 # Optional Peer Dependencies in Shakapacker
 
+> **Tip (Shakapacker 10.1+):** This document describes the optional peer
+> dependency model used by the core `shakapacker` package. If you want a
+> tested, lockstep-pinned managed-build stack without listing each peer
+> yourself, install
+> [`shakapacker-webpack`](../packages/shakapacker-webpack/README.md) or
+> [`shakapacker-rspack`](../packages/shakapacker-rspack/README.md) instead.
+> See the
+> [v10.1 supplemental packages migration guide](./migration/v10.1-supplemental-packages.md)
+> for adoption steps and
+> [`docs/dependency-strategy.md`](./dependency-strategy.md) for the design
+> rationale.
+
 ## Overview
 
 As of Shakapacker v9 (and continuing in v10), all peer dependencies are marked as optional via `peerDependenciesMeta`. This design provides maximum flexibility while maintaining clear version constraints.

docs/peer-dependencies.md

@@ -8,6 +8,17 @@ Shakapacker declares these packages as optional peer dependencies via
 chosen bundler/transpiler stack, while the ranges below document what current
 releases support.
 
+> **Tip (Shakapacker 10.1+):** If you'd rather not manage the managed-build
+> stack as individual peers, install
+> [`shakapacker-webpack`](../packages/shakapacker-webpack/README.md) or
+> [`shakapacker-rspack`](../packages/shakapacker-rspack/README.md). These
+> supplemental packages bundle the tested webpack/rspack stack as direct
+> dependencies, so a single install brings in `shakapacker` + bundler + CLI +
+> manifest plugin at the exact pinned versions. See the
+> [v10.1 supplemental packages migration guide](./migration/v10.1-supplemental-packages.md).
+> Optional peers (transpilers, dev-server, CSS preprocessors) still apply when
+> you adopt a supplemental package.
+
 ## Common Packages
 
 ```text

docs/rspack.md

@@ -30,16 +30,34 @@ See the [Rspack v2 breaking changes discussion](https://github.com/web-infra-dev
 
 ## Installation
 
-Install the required Rspack dependencies:
+### Recommended (Shakapacker 10.1+): `shakapacker-rspack`
+
+`shakapacker-rspack` bundles `shakapacker`, `@rspack/core`, `@rspack/cli`, and `rspack-manifest-plugin` as direct dependencies, so a single install pulls in the full managed Rspack stack:
+
+```bash
+npm install shakapacker-rspack -D
+# or
+yarn add shakapacker-rspack -D
+# or
+pnpm add shakapacker-rspack -D
+# or
+bun add shakapacker-rspack -D
+```
+
+See [`packages/shakapacker-rspack/README.md`](../packages/shakapacker-rspack/README.md) for the full install reference and the [v10.1 supplemental packages migration guide](./migration/v10.1-supplemental-packages.md) for swapping an existing rspack install over to the supplemental package.
+
+### Manual install (Shakapacker 10.0 and earlier, or self-managed versions)
+
+If you're on Shakapacker 10.0 or prefer to manage `@rspack/core`, `@rspack/cli`, and `rspack-manifest-plugin` versions yourself, install them directly:
 
 ```bash
-npm install @rspack/core @rspack/cli -D
+npm install @rspack/core @rspack/cli rspack-manifest-plugin -D
 # or
-yarn add @rspack/core @rspack/cli -D
+yarn add @rspack/core @rspack/cli rspack-manifest-plugin -D
 # or
-pnpm add @rspack/core @rspack/cli -D
+pnpm add @rspack/core @rspack/cli rspack-manifest-plugin -D
 # or
-bun add @rspack/core @rspack/cli -D
+bun add @rspack/core @rspack/cli rspack-manifest-plugin -D
 ```
 
 Note: These packages are already listed as optional peer dependencies in Shakapacker, so you may see warnings if they're not installed.