Why Lock Files Matter: Understanding Lock Files for Better Dependency Management

Ensuring Consistency and Security in Your Projects

Background

When I first started working with projects that used npm and Yarn, I didn’t pay much attention to the package-lock.json or yarn.lock files.  It wasn’t until I collaborated with the lead at my previous company that I realized just how essential these files are to ensuring consistency across projects. Today, as I continue volunteering at Code to Cloud and exploring pnpm, I thought it would be a good time to dive into this topic and explain why lock files matter.

What Are These Lock Files?

Think of package-lock.json (for npm) and yarn.lock (for Yarn) as the source of truth for your project’s dependencies. These files make sure that everyone is working with the same versions of your dependencies, no matter who’s running the project or where it’s running.

They are generated from the package.json file, which lists the dependencies for your project. Let’s look at an example:

{
  ...,
  "dependencies": {
    "expo": "~52.0.30",
    "expo-constants": "~17.0.5",
    "expo-status-bar": "~2.0.1",
    "react": "18.3.1",
    "react-native": "0.76.6"
  },
  "devDependencies": {
    "@babel/core": "^7.20.0",
    "@gorhom/bottom-sheet": "^5.0.6",
    "@react-native-async-storage/async-storage": "1.23.1",
    "@react-native-community/datetimepicker": "8.2.0",
    "@react-native-community/slider": "^4.5.2",
    "@storybook/addon-ondevice-actions": "^8.4.4",
    "@storybook/addon-ondevice-controls": "^8.4.4",
    "@storybook/react-native": "^8.4.4",
    "@types/react": "~18.3.12",
    "babel-loader": "^8.3.0",
    "react-dom": "18.3.1",
    "react-native-gesture-handler": "~2.20.2",
    "react-native-reanimated": "^3.16.6",
    "react-native-safe-area-context": "4.12.0",
    "react-native-svg": "15.8.0",
    "typescript": "~5.3.3"
  }
}

Here, we see that @storybook/react-native is listed as ^8.4.4. But what does that actually mean?

Understanding Versioning (^, ~, Exact)

If there is no existing lock file, npm or yarn will install dependencies based on the versioning syntax:

• "8.4.4" → Installs exactly version 8.4.4

• "~8.4.4" → Installs the latest patch within 8.4.x (e.g., 8.4.9 if available)

• "^8.4.4" → Installs the latest minor version within 8.x.x (e.g., 8.9.9 if available)

However, if a lock file is present, the package manager will install the exact version recorded in it, ensuring consistency across environments. If you update package.json or delete the lock file, a new version might be installed based on the versioning rules above.

Why Are Lock Files Important?

Without a lock file, developers might encounter “works on my machine” issues, where different environments end up with different package versions. This can lead to confusing bugs that are hard to track down. However when a lock file is present, you get a snapshot of the exact versions in use, ensuring stability for everyone on the project.

Understanding Versioning in Lock Files

package-lock.json

In package-lock.json, the version and dependencies of the package are locked down in a way that guarantees everyone uses the exact same version.

"node_modules/@storybook/react-native": {
      "version": "8.5.3",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "@storybook/core": "^8.5.1",
        "@storybook/csf": "^0.1.13",
        "@storybook/global": "^5.0.0",
        "@storybook/react": "^8.5.1",
        "@storybook/react-native-theming": "^8.5.3",
        "@storybook/react-native-ui": "^8.5.3",
        "commander": "^8.2.0",
        "dedent": "^1.5.1",
        "deepmerge": "^4.3.0",
        "prettier": "^2.4.1",
        "react-native-url-polyfill": "^2.0.0",
        "setimmediate": "^1.0.5",
        "storybook": "^8.5.1",
        "type-fest": "~2.19",
        "util": "^0.12.4",
        "ws": "^8.18.0"
      },
      "bin": {
        "sb-rn-get-stories": "bin/get-stories.js"
      },
      "engines": {
        "node": ">=8.0.0"
      },
      "peerDependencies": {
        "@gorhom/bottom-sheet": ">=4",
        "react": "*",
        "react-native": ">=0.72.0",
        "react-native-gesture-handler": ">=2",
        "react-native-safe-area-context": "*"
      }
}

Here, the @storybook/react-native package is locked to version 8.5.3. Its direct dependencies are also listed, such as @storybook/core (which is at version ^8.5.1), and it specifies the peer dependencies, such as react and react-native.

This file ensures that anyone running npm install on this project will get exactly the same versions of @storybook/react-native and its dependencies, regardless of the environment.

yarn.lock

Now, let’s look at how the same package would appear in yarn.lock. The content is structured differently, but the purpose remains the same - ensuring consistency across installations.

"@storybook/react-native@^8.4.4":
  version "8.5.3"
  resolved "https://registry.yarnpkg.com/@storybook/react-native/-/react-native-8.5.3.tgz#c0e5b1c322b037e2b57e59e7eb191028872c4b51"
  integrity sha512-A4vDjBCL93hTr67wpLdATiLhrLLqS6Qmrdfm1/cojXXTNqVN1bFwPjTrdRDiSQqouyhS8tyK+oeuCrA9wjLe5A==
  dependencies:
    "@storybook/core" "^8.5.1"
    "@storybook/csf" "^0.1.13"
    "@storybook/global" "^5.0.0"
    "@storybook/react" "^8.5.1"
    "@storybook/react-native-theming" "^8.5.3"
    "@storybook/react-native-ui" "^8.5.3"
    commander "^8.2.0"
    dedent "^1.5.1"
    deepmerge "^4.3.0"
    prettier "^2.4.1"
    react-native-url-polyfill "^2.0.0"
    setimmediate "^1.0.5"
    storybook "^8.5.1"
    type-fest "~2.19"
    util "^0.12.4"
    ws "^8.18.0"

In yarn.lock, the version 8.5.3 of @storybook/react-native is also locked, but the package manager resolves the package from the Yarn registry and records its exact integrity (hash) to verify the package’s authenticity.

The dependencies listed here are essentially the same as in package-lock.json, but the structure focuses on the resolved URL for the package and its integrity check, adding a layer of security.

Things to Consider

1. Lock File Conflicts

   
   Conflicts can arise when multiple developers update dependencies or when the lock file is accidentally omitted from version control. These conflicts can introduce discrepancies in the dependency tree, leading to bugs or unexpected behaviour in your application.
   

   1. To resolve lock file conflicts:

      1. Commit Lock Files Regularly: Encourage your team to commit lock files whenever dependencies are updated. This ensures that everyone is using the same version and avoids issues when pulling or pushing to version control.

      2. Resolve Conflicts Efficiently: If a conflict does arise, use git diff to see the exact differences in the lock file and run npm install or yarn install to regenerate the lock file and restore consistency.

         
         

2. Security Considerations

   
   Lock files play a crucial role in securing your application by ensuring the exact versions of dependencies are used consistently across all environments. In the ever-evolving world of software development, supply chain attacks—where malicious actors target third-party package dependencies—are becoming increasingly prevalent. Your project could inadvertently pull the latest versions of dependencies, which may contain unpatched vulnerabilities, leaving your application exposed to attacks, so maintaining your lock file is key.

   In October 2021, a significant supply chain attack occurred with the popular npm package ua-parser-js. This library, responsible for parsing user-agent strings in JavaScript applications, was compromised when attackers introduced a malicious payload into an update. The attack, aimed at mining cryptocurrency through the resources of affected systems, impacted numerous businesses relying on the package. This breach serves as a reminder that even trusted and widely-used packages can be exploited, highlighting the need for developers to take proactive steps to secure their projects.

   1. Security Best Practices

      1. Regularly Audit Dependencies: Use npm audit or yarn audit to scan your project for known vulnerabilities. These tools check your lock files and dependencies for any security issues, helping you stay on top of potential risks.

      2. Use tools like Dependabot or Snyk: Set up Dependabot or Snyk for your projects to automatically create pull requests for dependencies with known vulnerabilities, keeping your lock files updated with secure versions.

      3. Pin Versions Explicitly: Avoid using flexible version ranges (e.g., ^1.0.0) for critical dependencies. Instead, pin to specific versions to ensure consistency and security across all environments.

Conclusion

Lock files may seem like just another file in your project, but actually play a role in ensuring consistency and security. By paying attention to them and committing them regularly, you’ll save yourself and your team a lot of headaches down the road. So next time you’re working with npm or Yarn, take a moment to appreciate the role of your lock files—they’re more important than you might think.