What is pnpm? Usage Guide

In the realm of frontend development, package managers are tools we interact with daily. From the earliest npm, to the later yarn, and now the "most advanced" **pnpm**, the evolution of these tools has always revolved around three core metrics: **speed, space efficiency, and dependency safety**.

This article will introduce you to pnpm and teach you how to use it.

**pnpm** (Performant npm) is an extremely fast, disk-space-efficient package manager.

### Core Advantages

-   **Blazing Fast (Performance):** pnpm is much faster than npm and yarn (often 2x or more). This is because it uses a unique installation mechanism that avoids redundant copying of a large number of files.
-   **Space Efficient (Efficiency):** This is pnpm's killer feature. It uses **Content-addressable storage**. If you have 10 projects that all use the same version of `lodash`, it will only be stored once on disk.
-   **Perfectly Solves 'Phantom Dependencies' (Safety):** Traditional npm/yarn 'flatten' dependencies, which can lead to you being able to access packages in your code that you haven't declared in `package.json`. pnpm uses **Symlinks** to build a strict dependency tree, ensuring that only declared packages can be accessed.

## The 'Right Way' to Use pnpm

### Installing pnpm

If you have Node.js installed, it's recommended to install it directly via Corepack:

```Bash
corepack enable
corepack prepare pnpm@latest --activate
```

Or use npm for global installation: `npm install -g pnpm`

### Common Command Comparison Table

| **Operation**         | **npm Command**           | **pnpm Command**                        |
| --------------------- | ------------------------- | --------------------------------------- |
| Install dependencies  | `npm install`             | `pnpm install` (or `pnpm i`)            |
| Add package           | `npm install <pkg>`       | `pnpm add <pkg>`                        |
| Add dev dependency    | `npm i <pkg> -D`          | `pnpm add <pkg> -D`                     |
| Remove package        | `npm uninstall <pkg>`     | `pnpm remove <pkg>`                     |
| Run script            | `npm run <script>`        | `pnpm <script>` (no `run` keyword needed) |
| Global install        | `npm install -g`          | `pnpm add -g`                           |

### Managing Node Versions

pnpm has built-in version management, so you might not even need to install nvm:

-   Install a specific version: `pnpm env use --global 20`

## Advanced

### Setting the Store Path

pnpm's core logic is to store all packages in a global `store` and then map them to each project's `node_modules` via hard links.

By default, the store will be located in the root directory of the current drive. If you want to customize the storage location (e.g., concerned about C drive space):

```Bash
# View current store path
pnpm store path

# Set custom path
pnpm config set store-dir D:\.pnpm-store
```

### Monorepo Best Practices

pnpm is currently the best choice for handling **Monorepos** (multi-package management projects). You just need to create a `pnpm-workspace.yaml` file in the root directory:

```yaml
packages:
  - 'packages/*'
  - 'apps/*'
```

Then you can install dependencies across projects: `pnpm add lodash --filter @my-app/web`.

### Differences from npm/yarn

-   **npm/yarn (v1):** Uses a flattened structure, prone to dependency conflicts, and high disk space usage.
-   **yarn (v2/v3) Berry:** Introduced PnP mode, which is fast but poses greater compatibility challenges.
-   **pnpm:** Found a balance. It maintains the physical structure of `node_modules` (through soft and hard links), ensuring extremely high compatibility, while achieving ultimate performance.

## Migrating Old Projects to pnpm

Perform the following operations in your project's root directory:

1.  **Install pnpm** (if not already installed):

    ```Bash
    npm install -g pnpm
    ```

2.  **Generate pnpm lock file**: Execute the following command, which will automatically read your existing `package-lock.json` or `yarn.lock` and generate `pnpm-lock.yaml` without downloading packages.

    ```Bash
    pnpm import
    ```

3.  **Delete old files**: To keep the project tidy, delete the old `node_modules` and old lock files.

    ```Bash
    # Windows users can use the del command or manually delete
    rm -rf node_modules package-lock.json yarn.lock
    ```

4.  **Reinstall dependencies**: Use pnpm to complete the final step:

    ```Bash
    pnpm install
    ```