There are tons of articles on how Bootstrap v5 simplifies modern CSS and markup itself, but migrating a big, long-running project from v4 to v5 is not so easy. It requires major changes, like removing the dependency on jQuery and updating core components.
In this blog post, I am going to share my migration experience, highlighting the difficulties I and my other team members faced, common pitfalls to avoid, and required steps to test the upgrade of your application. I hope this resource will serve as a valuable guide for other developers planning for Bootstrap v4 to v5 upgrade.
So, before we dive into the details, let’s talk about some of the breaking changes that Bootstrap v5 brings in.
What are the breaking changes in Bootstrap v5
Class name changes
Many class names have been introduced in Bootstrap v5, with few classes being renamed or removed altogether.
Use of CSS variables internally
Bootstrap v5 now uses CSS variables internally, offering more flexibility for customizing the project.
The JavaScript components
The JavaScript components of Bootstrap v5 no longer rely on jQuery and have been updated accordingly. Therefore, the proper working of Bootstrap components (e.g., modals, tooltips) needs to be thoroughly tested if used within your project.
Challenges faced during Bootstrap v4 to v5 upgrade
As we began migrating our project from v4 to v5, we encountered challenges like:
Dependency upgrade
The most notable change in Bootstrap v5 is that it no longer relies on jQuery. This required us to refactor any code that relied on it. While this brought us some challenges, the changes made sense given the requirements of the project and the workarounds we applied.
React version compatibility
For stable version of React v16, Reactstrap and React-bootstrap have their own stable versions compatible with bootstrap v5. Significant changes, including component removal, are mentioned in their changelog.
Mistakes committed during the Bootstrap v4 to v5 upgrade
Despite thorough planning, we made some mistakes along the way.
Replacing classes with an external library
Inductive Case 1: I tried to replace the Bootstrap v4 utility class name with a third-party library. This filtered and replaced bootstrap classes and other custom classes with strings like those of bootstrap classes.
Pressing for a manual redesign
We should have known that creating an open-source project on a third-party library would become frustrating over time. The best approach would probably have been to manually track down all the classes that were replaced, as listed in the changelog section on the Bootstrap website.
Steps for a smooth Bootstrap v4 to v5 conversion
Audit your codebase
Begin by auditing your project codebase. Identify all the Bootstrap v4 classes, components, and JavaScript dependencies used throughout the site. Ensure that you don’t override any Bootstrap class names with your custom class names. This audit will provide insight into the extent of changes required and highlight the areas that need the most attention.
Choosing your code editor
Select a code editor that effectively highlights the differences between the old and new code, such as VSCode. Avoid using basic text editors like Notepad on Windows or equivalent options on Linux and macOS, as they may not provide the necessary functionality.
List folders
Create a list of all folders or parts of your project, organizing them by their flow. This categorization will streamline the conversion process.
Backup and Git branching
Create a stable branch of your repository to perform the upgrade. Use this base for new branches aimed at the upgrade, while keeping one branch stable for ongoing work. This approach is crucial as it minimizes the risk of complex merge conflicts when using Git, especially if your branches are kept up to date.
Upgrade planning
Before starting the conversion, ensure that all package dependencies are updated and maintained in a separate Git branch.
Testing the application
Some changes can affect how your site displays across different browsers, especially older ones. Cross-browser testing ensures that your application looks and functions as intended on all browsers.
Visual regression testing
Combine automated visual regression tools with manual testing. Manual testing allows you to catch changes as they occur. Additionally, testing every component, folder, and flow after migration can save you time and ensure that no bugs are left behind during the migration process.
Conclusion
A large project can be difficult to upgrade from Bootstrap v4 to v5. It requires careful planning and multiple updates, especially when various components and elements need to be addressed within the framework. While automated tools can suggest changes for class replacements, I have found that the risks often outweigh the benefits they claim to provide, as we experienced during this Bootstrap v4 to v5 upgrade. Therefore, transitioning your application to Bootstrap 5 through a systematic, step-by-step approach will help ensure that everything is properly configured.
The lessons from this article emphasize that highly unique and complex projects should be developed with greater control. By following the detailed steps outlined in this post, you should feel well-equipped to navigate the migration to Bootstrap v5 successfully.
