Do not lock dependency versions ('"react": "*"')

The Catastrophic Consequences of Not Locking Dependency Versions

The notation "react": "*" may seem convenient, automatically fetching the latest version and saving the hassle of manual upgrades. But in real-world projects, this is equivalent to planting a ticking time bomb. On a sunny morning, the CI pipeline suddenly turns red, code that runs perfectly in the local development environment results in a blank screen in production, and it turns out to be due to an API being deprecated after React 18 auto-upgraded.

// package.json
{
  "dependencies": {
    "react": "*",  // The beginning of disaster
    "react-dom": "*"
  }
}

The Phantom Issue of Indirect Dependencies

Even if direct dependency versions are locked, indirect dependencies can still introduce breaking changes through ^ or ~ range symbols. After an npm install, the project suddenly exhibits bizarre style misalignments. Two days of debugging later, it’s discovered that the indirect dependency css-tree of styled-components auto-upgraded to 2.0, causing parsing logic changes.

# View the actual dependency tree
npm ls css-tree
project@1.0.0
└─┬ styled-components@5.3.0
  └─┬ css-tree@1.1.3 → 2.0.0  # Auto-upgraded indirect dependency

Non-Reproducible Build Issues

When dependency versions are not fixed, dependencies installed at different times or on different machines can vary drastically. A new hire runs npm install and the project fails to start, while it runs fine on a senior developer's machine. Checking package-lock.json reveals it was ignored by Git, leaving everyone on the team running different combinations of dependency versions.

// A typical problematic scenario
function Component() {
  // This works in React 17 but throws an error in 18
  return React.createElement(Modal, null, [
    React.createElement(Header, { key: 'header' }),
    React.createElement(Body, { key: 'body' }) // Suddenly throws a children type error
  ]);
}

The Nightmare of Automated Deployment

Every time the CI/CD pipeline executes npm install, it may introduce unknown dependency versions. After a production deployment, monitoring systems suddenly alert, and a rollback reveals that a minor dependency version introduced a memory leak. Worse, without locked versions, it’s impossible to pinpoint which package caused it.

# A typical troubleshooting process
$ git bisect start
$ git bisect bad
$ git bisect good v1.2.3
Bisecting: 37 revisions left to test...
# Eventually, it’s discovered the code didn’t change—only the dependencies auto-updated

Debugging Hell

When errors like Cannot read property 'xxx' of undefined occur, unfixed dependency versions force developers to waste hours debugging the wrong code paths. Late at night, a developer spends three hours on a mysterious bug, only to find that lodash.get auto-upgraded from 4.4.2 to 4.5.0 and changed its null handling logic.

// Code that worked yesterday
_.get({ a: { b: null } }, 'a.b.c.d', 'default'); 
// Today it returns undefined instead of 'default'

The Paradox of Security Patches

While keeping dependencies up-to-date helps with security updates, auto-upgrades may introduce untested patches. After a security update, the project starts crashing intermittently. Investigation reveals the security patch accidentally introduced a memory leak in Promise handling, and the team spends two weeks linking the issue to the auto-upgrade.

// Regression introduced by a security patch
axios.get('/api').then(res => {
  // The new version fails to release closure memory in some cases
  const heavyObject = process(res.data);
  updateState(heavyObject); 
});

The Domino Effect in Monorepos

In monorepo projects, dependency version drift in one package affects all others. A utility package suddenly throws Invalid hook call errors because a subproject auto-upgraded to React 18 while others stayed on React 17, crashing the hooks system.

// packages/shared/src/useCustomHook.js
import { useEffect } from 'react'; // Could be 17 or 18, depending on which project installed first

export function useCustomHook() {
  // Crashes in a mixed React 17/18 environment
  useEffect(() => { ... }, []);
}

The False Security of Type Systems

Even with TypeScript, unlocked versions can cause type definitions to diverge from runtime behavior. After @types/react 18 was released, component props type checks suddenly started failing, while runtime worked fine because the installed React version was still 17.

// Type definitions mismatch runtime behavior
const Component: React.FC<{ 
  children: React.ReactNode // Type error but runs fine
}> = ({ children }) => (<div>{children}</div>);

The Dark Side of Solutions

Simply switching to ^ or ~ range symbols doesn’t solve the problem. A project replaced * with ^16.8.0, thinking it was safe, only to be hit when React 17 was released because ^ allows major version upgrades if the current version is 0.x.x (a pitfall of semantic versioning).

{
  "dependencies": {
    "react": "^16.8.0", // Actually allows upgrades to 17.0.0
    "react-dom": "^16.8.0"
  }
}

The Trap of Lock Files

Committing package-lock.json or yarn.lock to version control is just the first step. A team using npm ci in Docker builds to ensure consistency overlooked how global Node modules in the base image could affect dependency resolution, leading to subtle differences in production.

# Problematic Dockerfile
FROM node:16-alpine # Different builds may get different 16.x versions
WORKDIR /app
COPY package*.json .
RUN npm ci # Still susceptible to issues due to base image differences

The Fragility of Continuous Integration

CI systems caching node_modules can cause even subtler issues. A team found CI tests passing intermittently, ultimately tracing it to cached dependencies of different versions, where test results depended entirely on which agent last ran the build.

# Problematic CI configuration
steps:
  - restore_cache:
      keys:
        - v1-npm-{{ checksum "package.json" }} # Only validates against package.json
  - run: npm install

The Disaster of Cross-Team Collaboration

When multiple teams share a frontend architecture, unlocked versions lead to dependency hell. Team A’s component library requires React 18, while Team B’s micro-frontend needs React 17. The final build includes two React copies, causing state management to break entirely.

// Disaster in a micro-frontend scenario
window.app1 = require('react'); // 17.0.2
window.app2 = require('react'); // 18.2.0
// Global hooks system crashes

The Betrayal of Browser Caching

CDN imports of unversioned dependencies are even worse. A website suddenly shows blank screens for many users because https://unpkg.com/react@latest upgraded from 16 to 17, and browsers cached both versions, causing rendering crashes when components mixed versions.

<!-- A suicidal approach -->
<script src="https://unpkg.com/react@latest/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@latest/umd/react-dom.production.min.js"></script>

Extreme Cases of Version Locking

Even with all versions locked, system-level dependency issues can still arise. After a macOS update, Node.js 16 fails to compile native modules because the project locked an old dependency version that relies on a C++ library no longer available in the new system.

# Example compilation error
node-gyp rebuild
ERROR: Could not find any Visual Studio installation to use
# Because the locked old version of node-sass requires a specific VS version