Guide to Using pnpm for Efficient Monorepo Setup

1. Project Initialization: The First Step

The first step of any monorepo setup is to initialize the project. To use pnpm, you first need to install pnpm globally. Execute the following command to begin installation:

npm install -g pnpm

Once pnpm is installed, you can initialize a new project from the root directory by running the following command:

pnpm init

This command generates the `package.json` file for your project, marking the beginning of your monorepo setup.

2. Configuring pnpm Workspace

In a monorepo environment, where multiple packages are managed in one place, pnpm’s workspace feature comes in handy. Workspaces are powerful tools that make managing dependencies between packages easier. To define which packages will be part of the workspace, create a `pnpm-workspace.yaml` file in the root of the project and specify the packages it will include:

# pnpm-workspace.yaml
packages:
  - 'packages/*'

Now, all packages under the `packages` directory are automatically included in the workspace, laying the groundwork for easy management of multiple packages.

3. Package Structure: Organizing the Project

To create the packages you want to manage in the monorepo, create a `packages` directory and initialize individual packages under it. For instance, let’s assume you want to create `ui` and `api` packages.

mkdir -p packages/ui
mkdir -p packages/api

Within each package directory, run the following command to create a `package.json` file for each:

cd packages/ui
pnpm init
cd ../api
pnpm init

Now, the `ui` and `api` packages have been added to your monorepo.

4. Installing and Sharing Dependencies: Reusing Code Efficiently

One of the biggest advantages of a monorepo is the ease of sharing code between packages. For instance, if the `ui` package depends on the `api` package, you can install the dependency like this:

cd packages/ui
pnpm add ../api

This command adds the `api` package as a dependency for the `ui` package, allowing easy code reuse between packages.

5. Managing Common Dependencies

In a monorepo project, common dependencies used across packages can be managed from the root of the project. For instance, to install a common dependency like `typescript`, use the following command:

pnpm add -D typescript

This command installs `typescript` at the root, creating a shared `node_modules` directory. pnpm’s caching mechanism prevents redundant installations of the same dependency. This approach not only reduces installation time but also saves storage space.

6. Running Scripts: Performing Tasks Across Packages

In a monorepo environment, you can either run scripts for individual packages or run scripts across multiple packages simultaneously. For example, to run the `build` script for all packages, use this command:

pnpm -r run build

This command runs the `build` script for every package in the monorepo. If you want to run a script for a specific package only, use the following command:

pnpm --filter ui run build

This command runs the `build` script for only the `ui` package.

7. Efficient Cache Management

pnpm manages the dependencies of each package using a central cache. This means that when multiple packages use the same dependency, it is downloaded only once and shared among packages. This approach saves disk space and significantly speeds up dependency installations.

Conclusion

In this guide, we’ve explored how to set up a monorepo environment using pnpm. Monorepos are becoming increasingly popular among developers for their efficient management of multiple projects. Especially, pnpm provides fast and efficient dependency management, greatly improving the scalability and maintainability of your projects.

If you’re new to monorepos, I recommend starting with small projects using the methods introduced today. Soon, you’ll appreciate the ease of managing and reusing code. Feel free to ask if you have any questions. I wish you success in setting up your monorepo!