2.1 What Is It?#

package.json is the metadata file for every Node.js / front-end project, recording the project’s basic information, dependencies, script commands, and more. You can think of it as the project’s ID card + instruction manual.

2.2 A Typical package.json#

1
{
2
    "name": "my-awesome-app",
3
    "version": "1.0.0",
4
    "private": true,
5
    "type": "module",
6
    "scripts": {
7
        "dev": "vite",
8
        "build": "vite build",
9
        "preview": "vite preview"
10
    },
11
    "dependencies": {
12
        "react": "^19.0.0",
13
        "react-dom": "^19.0.0"
14
    },
15
    "devDependencies": {
16
        "vite": "^8.0.0",
17
        "@vitejs/plugin-react": "^5.0.0",
18
        "typescript": "^5.8.0"
19
    }
20
}

2.3 Key Fields Explained#

3.1 The Difference#

1
Production dependencies (dependencies):
2
  → Code that must be loaded when users visit your website
3
  → For example: react, vue, lodash, axios
4

5
Development dependencies (devDependencies):
6
  → Only take effect during the development phase, and do not enter the final build output after bundling
7
  → For example: vite, webpack, typescript, eslint, prettier, vitest

3.2 Install Commands#

1
# Install as a production dependency (default)
2
npm install react
3

4
# Install as a development dependency
5
npm install -D vite typescript
6

7
# Equivalent syntax
8
npm install --save-dev vite

3.3 Why Distinguish Between Them?#

In production environments (CI/CD or Docker), using npm install --production can significantly reduce installation time and disk usage.

4.1 Semantic Versioning#

npm uses Semantic Versioning (SemVer for short), with the format:

1
Major version number.Minor version number.Patch number
2
 MAJOR . MINOR . PATCH

Example: 3.2.1 = major version 3, minor version 2, patch number 1.

4.2 Version Range Symbols#

Version numbers in package.json usually have a symbol in front of them:

1
# Concrete example
2
^1.2.3  →  >=1.2.3 <2.0.0   # Recommended, allows new features
3
~1.2.3  →  >=1.2.3 <1.3.0   # Conservative, only allows fixes
4
1.2.3   →  1.2.3 only       # Fully locked down

Recommendation: For everyday development, use ^ (caret) to let the project automatically receive bug fixes and new features. Critical libraries can use exact versions.

5.1 What Does npm install Do?#

1
npm install

When you run this command, npm will:

1. Read dependencies and devDependencies from package.json
2. Resolve the dependency tree, finding all dependencies of dependencies (transitive dependencies)
3. Download each package’s code to the node_modules/ directory
4. Generate or update package-lock.json

5.2 The “Black Hole” of node_modules#

The node_modules directory is notorious for its size. A medium-sized project can contain hundreds of MB and tens of thousands of files:

1
node_modules/
2
├── react/
3
├── react-dom/
4
├── vite/
5
├── typescript/
6
├── ... (hundreds of packages)

Important: node_modules should not be committed to Git. .gitignore should include:

1
node_modules/

After team members clone the project, they can run npm install to regenerate it.

6.1 Why Are Lock Files Needed?#

package.json uses range versions like ^1.2.3, meaning that npm install at different times may install different versions:

1
Installed on March 1: react ^19.0.0 → 19.0.0
2
Installed on May 1: react ^19.0.0 → 19.2.3  ← Not the same!

This leads to the classic “it works on my machine” problem.

6.2 The Role of Lock Files#

Lock files record the exact version of every layer of dependencies, ensuring that dependencies installed by team members and CI/CD are completely identical.

1
// package-lock.json snippet
2
"node_modules/react": {
3
    "version": "19.2.3",
4
    "resolved": "https://registry.npmjs.org/react/-/react-19.2.3.tgz",
5
    "integrity": "sha512-..."
6
}

Lock files must be committed to Git. They are the key to ensuring environment consistency.

7.1 Development History#

1
npm (2010)
2
  → The first Node.js package manager, installed alongside Node.js
3

4
yarn (2016)
5
  → Created by Facebook, solving npm's slowness and inconsistency issues
6

7
pnpm (2017)
8
  → Best disk efficiency, strict dependency handling

7.2 Core Comparison#

7.3 The “Phantom Dependency” Problem#

npm and yarn Classic flatten all dependencies at the top level of node_modules. This allows you to require('express') even if you didn’t declare it in package.json (if some package depends on express).

pnpm uses strict nested dependencies, so you can only access dependencies you declared yourself in package.json, exposing missing dependencies at code-writing time.

7.4 How to Choose?#

8.1 What is scripts?#

The scripts field in package.json allows you to give short aliases to complex commands:

1
{
2
    "scripts": {
3
        "dev": "vite --host 0.0.0.0 --port 3000",
4
        "build": "tsc && vite build",
5
        "lint": "eslint . --ext .ts,.tsx",
6
        "format": "prettier --write .",
7
        "test": "vitest run",
8
        "test:watch": "vitest"
9
    }
10
}

When using:

1
npm run dev    # Equivalent to running vite --host 0.0.0.0 --port 3000
2
npm run build  # Equivalent to running tsc && vite build
3
npm run lint   # Equivalent to running eslint . --ext .ts,.tsx

8.2 Special Scripts#

Some script names can omit run directly:

1
npm start      # Equivalent to npm run start
2
npm test       # Equivalent to npm run test
3
npm stop       # Equivalent to npm run stop
4
npm restart    # Equivalent to npm run restart

8.3 pre and post Hooks#

npm has built-in lifecycle hooks:

1
{
2
    "scripts": {
3
        "prebuild": "npm run clean",    // Runs before build
4
        "build": "vite build",           // Main command
5
        "postbuild": "npm run analyze"   // Runs after build
6
    }
7
}

When executing npm run build, npm executes in the order of prebuild → build → postbuild.

9.1 Why Do We Need Build Tools?#

Browsers cannot directly run .vue, .tsx, .scss files, nor do they support import path aliases. The role of build tools is to transform development code into code that browsers can run:

1
Source files (.tsx / .vue / .scss)
2
   ￬ Build tools (Vite / Webpack)
3
Final output (.js / .css / .html)

9.2 Webpack#

Webpack was once the absolute king of frontend building (2014-2022). Its core philosophy: everything is a module, handle all files through Loader and Plugin.

1
module.exports = {
2
    entry: './src/index.js',
3
    output: {
4
        path: path.resolve(__dirname, 'dist'),
5
        filename: 'bundle.js',
6
    },
7
    module: {
8
        rules: [
9
            { test: /\.css$/, use: ['style-loader', 'css-loader'] },
10
            { test: /\.tsx?$/, use: 'ts-loader' },
11
        ],
12
    },
13
    plugins: [
14
        new HtmlWebpackPlugin({ template: './index.html' }),
15
    ],
16
};

9.3 Vite#

Vite (French for “fast”) was created by Vue author Evan You, and quickly became mainstream after 2022:

1
import { defineConfig } from 'vite';
2
import react from '@vitejs/plugin-react';
3

4
export default defineConfig({
5
    plugins: [react()],
6
    server: { port: 3000 },
7
});

The core differences between Vite and Webpack:

9.4 How to Choose?#