Break stuff. Now.

On Dependencies And Lock Files

Developers still seem to have a hard time with them

July 1, 2023

Close-up on Branches of Tree Photo by Kadir Akman from Pexels

Earlier this week, we had another brown-bag developer discussion. This time it revolved around a broken CI build caused by conflicting dependencies. Drupal 9's end-of-life is also coming up, a jump to Drupal 10 for all our projects is underway as well. In both fronts, PHP (composer) and JavaScript (npm, yarn), we're dealing with dependency changes.

Now when it comes to dependencies, the issue of lock files always comes up. And it annoys me sometimes that many developers don't really seem to get how lock files work. This isn't just be being arrogant, it's a problem in the broader community. I've met "senior" developers who don't seem to get it. I've seen countless Stack Overflow answers and Github issue comments recommend "deleting the lock file and run install" or "just don't check in the lock file". And I've had to untangle a neglected lock file for a project just recently, I'm even surprised that project didn't fall apart.

Now to get back in the right direction:

  • The lock file (e.g. package-lock.json, yarn.lock, composer.lock) defines the exact versions of all the dependencies in a project, and is what install will follow if present. This ensures that developers install the same exact dependencies, regardless of when they install, where they install, or what revision of the code they install.
  • The dependencies file (e.g. package.json, composer.json) declares the minimum versions and acceptable ranges of direct dependencies. This informs what update can update to, what audit can replace with, and informs conflict resolution in negotiating what version to install.

Of course, this is a really short and broad summary, there are finer details like what happens when the lock file is missing, projects vs libraries, lock files going out of sync, etc. But these short descriptions of these files should set the correct mindset on how to think when it comes to these two files. This is how I've been reminding myself how they work, and it hasn't failed me eversince.