6.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.
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.
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#
The first step is to 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.
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:
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.
