I loathe loathe loathe dependency management, especially on projects with large numbers of dependencies. It takes forever, is always confusing and I’m never quite sure that I’m doing it correctly.
Whenever I finally get a major package updated, I always breathe a sigh of relief and feel lucky that all my stuff still works.
Updating dependencies sounds simple, but it’s something we’re not usually taught. Which is why many of us feel like we’re figuring it out on our own.
This is the post I wish I had read when I was learning how to update dependencies in a frontend project. There’s more than one way to peel a potato, so you may know different strategies, but this is how I approach it.
Hopefully these six steps will be enough to get you going!
- Note: I have officially switched from the
yarnpackage manager tonpmso this post will refer tonpmthroughout. For context, this post explains many devs’ experiences coming back to npm and as of v7, npm handles peer dependencies automatically.
Step 1: Choose 1 dependency to update
When I’m starting to update my dependencies, I never want to update them all at once. This can result in a spaghetti mess of errors, warnings and confusing mismatched versions.
Instead, I choose one dependency to update and start there. By the time I’m done updating that single dependency, I’ll most likely have touched many others that depend on it either explicitly or implicitly.
Step 2: Start by making updates to the latest minor version
Before I worry about jumping a major version, I like to update my chosen dependency as much as possible while respecting the current semver in the package.json.
Said another way, I jump to the highest minor version while keeping the same major version.
Just a note that npm update package-name will do this for you automatically.
Step 3: Run your application
At this point, you will probably be fine. Since you didn’t jump any major versions, your app should still run. However, you may see a lot of warnings in your console. Most often these will be deprecation warnings or dependency warnings.
Deprecation warnings inform you about current features that won’t be available soon, most likely in the next major version of a package. These warnings will often tell you or link you to documentation on how to remove the deprecated functionality and replace it with the supported alternative.
Dependency warnings usually alert you to unmet peer dependencies (less likely if you are using npm >= v7) or incompatible package versions after your update. Read the warnings and resolve them accordingly.
If you have unmet peer dependencies, you’ll have to choose to explicitly install the needed dependencies or ignore them. This can happen if a dependent package has fallen behind the package you’re updating. Sometimes this happens because the dependent package is no longer maintained or it hasn’t been tested and updated with the newer version.
In either case, you’ll need to decide to explicitly install the version it’s asking for or ignore it.
npm install package-name@x.x.x where x.x.x is the required version number will update the package to the specified version.
When you see errors and warnings in the console, don’t panic! Slow down and read them thoroughly. Google the warning if you need to.
It’s important to resolve as many of the errors and warnings you see at this step because it will make the rest of the upgrade much easier.
Step 4: Make the git commit
Once you have all of your errors and warnings resolved and the code is working, commit it!
There’s nothing worse than forgetting to commit the incremental steps of an upgrade and then realize you broke something and can’t go back because the changes in package-lock.json are too numerous and hard to understand.
Small incremental commits during an upgrade are a huge timesaver. You can stash or check out what broke and get back to the most recent working version quickly and easily.
Step 5: Review the documentation
Before you upgrade your chosen dependency to the next major version, review their release notes for breaking changes. Every well-maintained package will have release notes for all their versions and will document what to expect when you jump a major version.
Look at their breaking changes and assess your codebase to see if you will be affected by them. You’ll want to know if there are any changes you won’t be able to remediate before you upgrade.
Sometimes we are using functionality in a lower version that’s removed in the next version and we need time to investigate other libraries or solutions.
Step 6: Bump the major version
Now you’re ready to update your chosen dependency to the next major version. You can do this by editing the package.json directly and specifying the major version "package-name": "^3.0.0 and running npm install.
This will install the latest package within that major version.
If you don’t need to upgrade multiple major versions, you can run npm install package-name@latest.
At this point, you’ll want to resolve any of the documented breaking changes that affect this codebase. Follow the directions in the documentation. When you think you have everything resolved, run the app and go back to Step 3.
Once you have a clean console, free from errors and warnings (or as free as you can make it), commit your code.
You did it! You successfully updated a dependency by a full major version. And you probably updated a lot more packages than you expected.
If you have more dependencies that you want to update, feel free to start at Step 1 and repeat this process until you have an up-to-date app. 🌈