Walkthrough

Rspack-related peer dependency ranges were expanded to include the v2 prerelease line (^2.0.0-0) alongside existing v1 constraints; documentation, README examples, and the install package template were updated to reflect these ranges.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through docs and tidy lines,

v1 and v2 now share the vines,
Examples fixed and ranges set,
A tiny rabbit patch — no sweat! 🥕

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Review

The change itself is correct and well-scoped: widening the peer dep range for `@rspack/plugin-react-refresh` from `^1.0.0` to `^1.0.0 || ^2.0.0-0` is the right fix now that v2.0.0 shipped, and the stale note removal from `docs/rspack.md` is clean.

One doc file was missed

`docs/peer-dependencies.md` line 38 still shows the old range and was not updated in this PR:

```text
// current (stale)
"@rspack/plugin-react-refresh": "^1.0.0"

// should be
"@rspack/plugin-react-refresh": "^1.0.0 || ^2.0.0-0"
```

That file is meant to be a human-readable mirror of `package.json`'s peer dep ranges, so it should stay in sync.

Minor: CHANGELOG

The PR checklist defers the changelog entry. Since this resolves a real user-facing peer dep warning, it warrants at minimum a one-liner under the next version's Fixed or Changed section. Happy to see it merged first and the changelog entry added in a follow-on, but worth tracking.

Everything else looks good

• The `^2.0.0-0` prerelease-inclusive semver syntax is consistent with the two other rspack peers (`@rspack/core`, `@rspack/cli`).
• `peerDependenciesMeta.optional: true` is already set for `@rspack/plugin-react-refresh`, so existing v1 users and non-rspack users are unaffected.
• No runtime code touches the plugin version; the change is purely declarative.

Greptile Summary

This PR widens the @rspack/plugin-react-refresh peer dependency from ^1.0.0 to ^1.0.0 || ^2.0.0-0, aligning it with the ranges already declared for @rspack/core and @rspack/cli, and removes the now-stale docs note that explained the deliberate v1 pin. The change is minimal and correct — the format matches the existing pattern, peerDependenciesMeta keeps the dep optional so v1 users are unaffected, and the removed doc note was the only remaining reference to the old constraint.

Confidence Score: 5/5

Safe to merge — one-line peer dep range expansion with no runtime code changes.

All findings are P2 (missing CHANGELOG entry, explicitly deferred by the author). The peer dep range format is correct, matches existing patterns, and the optional flag in peerDependenciesMeta means v1 users are unaffected.

No files require special attention.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User installs rspack v2 + shakapacker] --> B{Peer dep range check}
    B -->|Before PR - range was v1 only| C["npm resolves v2 plugin\nbut peer range says ^1.0.0"]
    C --> D["⚠️ Peer dep warning on every install"]
    B -->|After PR - range accepts v1 or v2| E["npm resolves v2 plugin\nwithin declared range"]
    E --> F["✅ No peer dep warning"]

_{Reviews (1): Last reviewed commit: "chore: widen @rspack/plugin-react-refres..." | Re-trigger Greptile}

Expanded this PR beyond the original peer-range-only change.

What was added in the latest commit:

• lib/install/package.json now widens @rspack/core and @rspack/cli to ^1.0.0 || ^2.0.0-0
• docs/examples were updated to match the new default install path

Why this matters:

• the old installer still defaulted fresh shakapacker:install runs to Rspack v1 even though the root peer metadata already allowed v2 for core/cli
• downstream React on Rails work hit exactly that mismatch

I verified this end-to-end in real fresh Rails apps using this branch as both:

1. a local path gem, and
2. a locally packed npm tarball

Verified behavior:

• shakapacker:install with SHAKAPACKER_ASSETS_BUNDLER=rspack now writes @rspack/core and @rspack/cli as ^2.0.0-0
• adding @rspack/plugin-react-refresh@^2.0.0 succeeds
• a clean later npm install succeeds
• bundle exec rails shakapacker:compile succeeds

I also verified the full downstream react_on_rails:install --rspack flow against this branch, and it succeeds cleanly with all three Rspack packages on v2.

Review

The core change — widening @rspack/plugin-react-refresh from ^1.0.0 to ^1.0.0 || ^2.0.0-0 — is correct, well-timed, and well-motivated. The removal of the stale v1-only note from docs/rspack.md is clean.

A few things worth addressing:

CHANGELOG is missing

Widening a peer dep range to include a new major version is a user-visible change. The checklist marks this as "deferred", but per the project guidelines this should have an entry under [Unreleased]. The @rspack/plugin-react-refresh v2 support is exactly the kind of thing users on rspack v2 are waiting to see in a changelog.

lib/install/package.json change not mentioned in the PR description

The diff also updates the installer defaults for @rspack/cli and @rspack/core from ^1.0.0 to ^1.0.0 || ^2.0.0-0. That's a meaningful change: new shakapacker:install runs will now write the wider range into users' package.json. It's the right call, but it should be called out explicitly in the PR description (currently only package.json and docs/rspack.md are listed as changed).

Version example bumps in README / docs are out of scope for the title

The diff also updates shakapacker: "^9.0.0" → "^10.0.0" and rspack ^1.0.0 → ^2.0.0-0 in README.md and docs/optional-peer-dependencies.md. These are reasonable corrections (v10 is current), but they're unrelated to widening the plugin peer dep and should be called out or split out so reviewers know what to check.

Minor doc inaccuracy (see inline)

The new sentence in docs/rspack.md describes the installer range as "the Rspack v2 prerelease line (^2.0.0-0)", but the actual range is ^1.0.0 || ^2.0.0-0. Suggested fix left as an inline suggestion.

Code Review

Summary: This PR correctly fixes an inconsistency where PR #975 widened the root peer ranges to support Rspack v2, but the installer template lib/install/package.json was still pinned to v1. The constraints.last mechanism in template.rb cleanly handles the ^1.0.0 || ^2.0.0-0 format, so widening those ranges is all that was needed.

Correctness ✅

The core fix is sound:

• lib/install/package.json updated to ^1.0.0 || ^2.0.0-0 for @rspack/cli and @rspack/core
• template.rb already does constraints.last which picks ^2.0.0-0 — so fresh installs will default to the v2 prerelease line as intended
• @rspack/plugin-react-refresh peer dep widened to match — necessary since v2 of the plugin carries a peer dep on @rspack/core@^2.0.0-0, which caused conflicts on v2 installs

Issues

1. CHANGELOG not updated (acknowledged in PR checklist, but this is a user-visible installer behaviour change — it warrants an entry under ### Fixed in the unreleased section.)

2. @rspack/plugin-react-refresh is absent from lib/install/package.json (pre-existing gap, but this PR makes it more visible). React projects using Rspack need this package, but shakapacker:install won't install it automatically. Now that the peer dep is widened to v2, fresh React+Rspack v2 installs will pull plugin v2, yet the installer never writes it. Consider adding it to the rspack section of lib/install/package.json, or at minimum add a note to the rspack docs pointing users to install it manually.

3. Minor: doc wording will date quickly — docs/rspack.md now says "which is currently the Rspack v2 prerelease line (^2.0.0-0)". Once Rspack v2 stable ships, "prerelease line" becomes misleading. Something like "Fresh installs default to ^2.0.0-0 (the current entry in lib/install/package.json)." ages better.

Minor notes

• Tests in spec/shakapacker/doctor_optional_peer_spec.rb and optional_dependencies_spec.rb that assert "@rspack/core" => "^1.0.0" are testing the doctor against a user-supplied package.json (not the installer), so they remain valid as-is.
• The README and docs examples now show ^2.0.0-0 (installer default) rather than the full supported range — acceptable for a "getting started" snippet.

Verdict

The fix is correct and minimal. The two things to address before merging: missing CHANGELOG entry, and a decision on whether to add @rspack/plugin-react-refresh to the installer (or open a follow-up issue).

Code Review: PR #1091 — Align rspack v2 peer deps and installer defaults

Summary

The PR correctly fixes a real inconsistency: PR #975 widened the root peer ranges for @rspack/core/@rspack/cli, but the installer template (lib/install/package.json) and the @rspack/plugin-react-refresh peer dep were left behind. The installer's constraints.last logic is already designed for exactly this pattern — the range widening here works correctly and will cause fresh installs to pick ^2.0.0-0.

Issues

Medium — CI does not test @rspack/plugin-react-refresh v2

The peer range for @rspack/plugin-react-refresh is widened to ^1.0.0 || ^2.0.0-0, but the devDependencies in package.json still pin it at a v1 version (it's not even listed as a devDep). CI has no coverage to confirm plugin v2 is actually compatible with the Shakapacker integration. Since this fixes a downstream ERESOLVE conflict it should be fine in practice, but the gap is worth noting.

Low — devDependency pin is behind the verified version

package.json devDependencies pin @rspack/cli and @rspack/core at 2.0.0-rc.0, but the PR description says verification was done with 2.0.0-rc.1. The CI coverage note in docs/rspack.md also still references rc.0. Consider bumping the dev pin to rc.1 to keep CI in sync with what was actually tested.

Low — no automated test for installer version selection

The PR checklist acknowledges this. For future reference, spec/generator_specs/generator_spec.rb is where the rspack install path is exercised — a test asserting that the resulting package.json contains ^2.0.0-0 (or at minimum a 2.x range) for @rspack/core/@rspack/cli would lock in this behavior.

Low — README example exposes the prerelease range

README.md now shows @rspack/core: "^2.0.0-0" as the copy-paste example. The -0 suffix (meaning "allow prereleases") may be confusing to users who don't know semver prerelease semantics. A one-liner note in the example block or a link to the rspack docs would help.

What looks good

• The constraints.last logic correctly picks ^2.0.0-0 from the ^1.0.0 || ^2.0.0-0 range — no template changes needed.
• The stale "plugin v1-only" note is correctly removed from docs/rspack.md.
• CHANGELOG entries are correctly formatted and cover both the "Changed" (installer default) and "Fixed" (peer dep conflict) aspects.
• The peer dep triple (@rspack/core, @rspack/cli, @rspack/plugin-react-refresh) is now internally consistent.

Address-review summary

Scan scope: full PR history (no prior summary comment existed).

Mattered

• package.json:105 (@greptile-apps[bot]) — "Missing CHANGELOG entry." Addressed in commit a0968df6 with one entry under Changed (installer default) and one under Fixed (peer range widening), matching the precedent from PR Add rspack v2 support #975 and PR Allow webpack-cli v7 in peer dependencies #1021. Thread resolved.

Optional

• docs/rspack.md:11 (@claude[bot], range-mismatch framing) — Declined. @rspack/core and @rspack/cli are still in RC (2.0.0-rc.3 latest), so the "prerelease line" wording is factually accurate today. The docs describe what the installer selects (^2.0.0-0), not the concatenated range. Thread resolved.
• docs/rspack.md:11 (@claude[bot], "currently" will go stale) — Declined. Same reason: 2.0.0 stable has not shipped. Will revisit wording when it does. Thread resolved.
• lib/install/package.json:3-4 (@claude[bot], add @rspack/plugin-react-refresh) — Declined. Shakapacker's install defaults are framework-agnostic — the webpack section doesn't include @pmmmwh/react-refresh-webpack-plugin either. Adding a React-specific package to the rspack section only would break that cross-bundler symmetry. Thread resolved.
• package.json:105 (@claude[bot], plugin v2 devDep for CI) — Declined. Shakapacker's CI doesn't exercise @rspack/plugin-react-refresh at any version today; adding only v2 would create asymmetric coverage. HMR-plugin runtime validation belongs in its own PR that covers both v1 and v2. End-to-end verification for this PR was done via fresh Rails apps. Thread resolved.
• docs/rspack.md:17 (@claude[bot], bump 2.0.0-rc.0 dev pin) — Declined. Pre-existing pin, unrelated to peer-range widening or installer default. Can be its own PR. Thread resolved.

Skipped

• CodeRabbit walkthrough comments, Greptile 5/5 approval boilerplate, CodeRabbit rate-limit notice, and author status updates (non-actionable noise).
• Pre-squash claude[bot] general-comment reviews flagging CHANGELOG / PR description / docs/peer-dependencies.md:38 / doc inaccuracy — all obsoleted by later commits (CHANGELOG added, PR description rewritten, docs/peer-dependencies.md updated in the same PR).
• CodeRabbit review summary body (2026-04-17) — duplicate of inline thread 3067442516 (already resolved above).

Next default scan starts after this comment. Say check all reviews to rescan the full PR.

Thanks for the thorough triage. The dispositions all look reasonable:

• CHANGELOG addressed in a0968df6 ✓
• "Prerelease line" wording is factually accurate while 2.0.0-rc.x is still the latest — no issue there
• Framework-agnostic install defaults is a sound principle; the React-specific plugin not belonging in the base installer is consistent with the webpack side
• Dev dep / CI coverage for the HMR plugin being its own PR makes sense given the symmetric v1+v2 coverage concern

Nothing left to block merge from my side. LGTM.

Tip: You can customize Greptile's behavior for this repo with .greptile/rules and .greptile/config.