Technical Analysis: Resolving 'sh: react-scripts: command not found' Error in Cloned React Projects

Problem Phenomenon and Background Analysis

In React project development, developers frequently encounter dependency issues when migrating projects between different systems. Specifically, after cloning a React project from GitHub, executing the npm start command returns the error sh: react-scripts: command not found. This phenomenon occurs on both Windows and macOS systems, despite the project functioning correctly on the source system.

Root Cause Investigation

The core of this issue lies in project dependency management mechanisms. React projects typically use the package.json file to define project dependencies, but the actual dependency packages are stored in the node_modules directory. Since the node_modules directory is usually added to the .gitignore file, it is not included in version control during project cloning.

Consider the following typical project structure example:

react-project/
├── package.json
├── public/
├── src/
└── .gitignore

Where the .gitignore file typically contains:

node_modules/
package-lock.json

Solution Implementation

Basic Solution

The most direct and effective solution is to execute the dependency installation command in the project root directory:

npm install

This command reads the dependency configuration from package.json, downloads and installs all necessary packages into the node_modules directory. After installation, react-scripts becomes available as a local dependency.

Dependency Verification Process

Before installing dependencies, it is recommended to verify the integrity of the package.json file. A standard React project package.json should contain:

{
  "name": "react-app",
  "version": "0.1.0",
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1"
  },
  "scripts": {
    "start": "react-scripts start"
  }
}

Clean and Reinstall Strategy

When the basic solution is ineffective, a thorough cleanup and reinstallation of dependencies may be necessary:

rm -rf node_modules
rm -f package-lock.json
npm install

On Windows systems, the corresponding commands are:

rmdir /s node_modules
del package-lock.json
npm install

Advanced Troubleshooting

Global Installation Conflict Resolution

In some cases, globally installed react-scripts may conflict with local versions. Check and uninstall global packages:

npm uninstall -g react-scripts

Then reinstall locally in the project:

npm install react-scripts --save-dev

Using npx as Alternative Approach

For temporary execution needs, npx can be used to run directly:

npx react-scripts start

This approach temporarily downloads and executes the specified version of react-scripts, suitable for quick testing scenarios.

Best Practices Summary

Based on problem analysis and solution implementation, we summarize the following best practices:

1. The primary task after project cloning is to execute npm install to install dependencies
2. Avoid globally installing create-react-app in existing projects
3. Regularly verify the integrity of dependency declarations in package.json
4. Ensure consistency in .gitignore configuration during team collaboration
5. Use version control tools to manage dependency versions and avoid environmental differences

By following these practices, developers can effectively prevent and resolve environment configuration-related issues in React projects, ensuring project portability and stability across different systems.