Broken styling after react-bootstrap v1 to v2 upgrade: how to roll back cleanly or finish the migration

Immediate Resolution

The broken styling and import errors are caused by a version mismatch: react-bootstrap v2 requires Bootstrap 5 CSS, but your project is still loading Bootstrap 4 CSS. Because react-bootstrap provides the JavaScript logic and not the styles, the CSS must be updated independently.

Option A: Clean Rollback

Choose this if you do not have the immediate bandwidth to refactor removed props (like Button block) or update custom CSS selectors.

1. Revert Configuration: Restore package.json and your lockfile (package-lock.json or yarn.lock) to the last known-good commit.
2. Purge Artifacts: Delete node_modules to ensure no v2 remnants persist.
3. Fresh Install: Run npm install or yarn install.
4. Verify CSS: Ensure your entry point (e.g., index.js or App.js) is importing the Bootstrap 4 CSS bundle.

Option B: Complete the Migration

Choose this if you need Bootstrap 5 features or are already committed to the upgrade.

1. Update CSS: Install Bootstrap 5 (npm install bootstrap@5) and update your CSS import to point to the v5 bundle.
2. Fix Import Errors: Replace renamed or removed components/props. For example, Button block is removed in v2; use layout utilities (like d-grid) instead.
3. Audit Custom CSS: Review any custom styles targeting Bootstrap 4 classes, as many have changed in v5.

Technical Analysis

Rollback vs. Migration Risk

The decision depends on the volume of API-breaking changes. If your project relies heavily on v1-specific props or complex custom CSS targeting v4 internals, a rollback is lower risk. If you only have a few import errors, completing the migration is preferable to avoid technical debt.

Guaranteeing Pre-Upgrade State

Reverting the package.json and lockfile is sufficient provided you delete the node_modules folder. While the lockfile ensures the same versions are requested, a stale node_modules directory can occasionally contain orphaned files or cached build artifacts that cause unpredictable runtime behavior.

CSS Pinning

Yes, the Bootstrap CSS version should be pinned independently. Since react-bootstrap does not bundle the CSS, the pairing is a manual dependency. To prevent this from happening again, remove the caret (^) from the version numbers in package.json for both bootstrap and react-bootstrap to lock them to exact versions.

Verification Steps

To confirm the fix, run the following command to verify installed versions:

npm ls react-bootstrap bootstrap

Then, inspect a component (e.g., a Button) in the browser DevTools. If you see Bootstrap 5 classes but the styling is missing, the CSS bundle is either not loading or is the wrong version.

Missing Diagnostic: Are you using a custom Sass theme or the pre-compiled CSS bundle? If using Sass, the migration requires updating the @import paths to the Bootstrap 5 source files.