7.1. Use pnpm with Medusa
In this chapter, you'll learn how to use pnpm as the package manager for your Medusa application.
What is pnpm?#
pnpm is a fast, disk space-efficient package manager. It uses a unique symlinked storage mechanism to save disk space and speed up installations.
Medusa supports pnpm, yarn, and npm as package managers. Our team recommends using either yarn or pnpm for better performance and faster installations.
To use pnpm with Medusa, you need to add some configuration to your project. This guide walks you through the necessary steps for both standalone projects and monorepos.
Who is This Guide For?#
As of Medusa v2.13.0, new Medusa projects support pnpm. You can create a new Medusa project with pnpm using the following command:
This guide is intended for developers who want to switch an existing Medusa project from npm or yarn to pnpm. Choose the section that matches your project's setup:
- Standalone Project: Your Medusa application is a single package in its own directory.
- Monorepo: Your Medusa application is one of multiple packages managed in a workspace.
Standalone Project#
Follow the steps in this section if your Medusa application is a standalone, single-package project.
Step 0: Update Medusa to the Latest Version#
If you're using a Medusa version prior to v2.13.0, you should update to the latest version to ensure compatibility with pnpm.
Refer to the Update Medusa guide to learn how to update your Medusa project.
If you're updating to v2.13.0, you also need to run the replace-zod-imports codemod.
Step 1: Remove Existing Lock File#
Delete the existing lock file in your project directory. Depending on your current package manager, this will be either package-lock.json for npm or yarn.lock for yarn.
When you install dependencies with pnpm later, a new pnpm-lock.yaml file will be created automatically.
Step 2: Add .npmrc File#
Medusa requires some packages to be installed in the top-level node_modules directory. To ensure this works correctly with pnpm, you need to create a .npmrc file that specifies the public-hoist-pattern configuration.
Create a .npmrc file in the root of your Medusa project with the following content:
This configuration tells pnpm to hoist the following packages to the top-level node_modules directory:
- All packages under the
@medusajsscope. @tanstack/react-query: Tanstack Query, used in Medusa Admin customizations. It's hoisted to avoid version and instance conflicts with the Medusa Admin.react-i18next: Used for internationalization in Medusa Admin customizations. It's hoisted to ensure compatibility with the Medusa Admin.react-router-dom: Used for routing customizations in the Medusa Admin. It's hoisted to avoid version and instance conflicts with the Medusa Admin.
Step 3: Install Dependencies with pnpm#
Finally, install your project dependencies using pnpm. Run the following command in your project directory:
This will install all your dependencies in node_modules and create a pnpm-lock.yaml file to lock the versions of your installed packages.
Monorepo#
Follow the steps in this section if your Medusa application is part of a monorepo, where it's one of multiple packages managed in a workspace.
Step 1: Set pnpm as the Package Manager#
In the root package.json file of your monorepo, set the packageManager field to the pnpm version you have installed:
If your package.json has a workspaces field, remove it. With pnpm, you define the workspace packages in a pnpm-workspace.yaml file instead, as explained in the next step.
Step 2: Define Workspace Packages#
Create a pnpm-workspace.yaml file at the root of your monorepo to define the packages in your workspace.
For example, if your packages are under an apps directory:
Adjust the patterns to match the directories where your packages are located.
Step 3: Add .npmrc File#
Medusa requires some packages to be installed in the top-level node_modules directory. To ensure this works correctly with pnpm, create a .npmrc file at the root of your monorepo with the following content:
This configuration tells pnpm to hoist the following packages to the top-level node_modules directory:
- All packages under the
@medusajsscope. @tanstack/react-query: Tanstack Query, used in Medusa Admin customizations. It's hoisted to avoid version and instance conflicts with the Medusa Admin.react-i18next: Used for internationalization in Medusa Admin customizations. It's hoisted to ensure compatibility with the Medusa Admin.react-router-dom: Used for routing customizations in the Medusa Admin. It's hoisted to avoid version and instance conflicts with the Medusa Admin.
Step 4: Remove Existing Lock Files#
Delete the existing lock file and the node_modules directory in your monorepo. Depending on your previous package manager, the lock file is either package-lock.json for npm or yarn.lock for yarn.
When you install dependencies with pnpm in the next step, a new pnpm-lock.yaml file will be created automatically.
Step 5: Install Dependencies with pnpm#
Finally, install your monorepo's dependencies using pnpm. Run the following command in the root of your monorepo:
This will install the dependencies of all packages in your workspace and create a pnpm-lock.yaml file to lock the versions of your installed packages.
Workspace Package Dependencies#
If your monorepo contains packages that import @medusajs/framework in their compiled output (for example, custom plugins or shared packages), declare @medusajs/framework as a peerDependency in those packages rather than a devDependency:
Declaring it only as a devDependency can cause a Cannot find module '@medusajs/framework/utils' error at runtime, because devDependencies are not included in production deployments.
Test Your Setup#
You can now use pnpm for your Medusa development. For example, you can start the Medusa server in development with the following command:
In a monorepo, run this command from your Medusa application's package directory, such as apps/backend.
You can also run commands from the Medusa CLI tool with pnpm. For example, to run migrations:
Refer to the Medusa CLI reference for a full list of available commands.