Migrating a TurboRepo Monorepo from Yarn Classic to Pnpm

This post summarizes the process and results of migrating a TurboRepo monorepo that used Yarn Classic to Pnpm in order to solve phantom dependency issues.

Yarn Classic reduces duplicate dependencies through hoisting, but in doing so it can create phantom dependencies, where packages not explicitly declared are implicitly referenced. In a monorepo, this problem surfaced more often and more critically, and depcheck actually confirmed multiple phantom dependencies.

The alternatives were Yarn Berry and Pnpm, but since the project was using TurboRepo, Yarn Berry's PnP was difficult to choose. In the end, Pnpm was chosen considering performance, security, and migration difficulty, and its npm-like usage was also an advantage.

Instead of hoisting, Pnpm works via a Content-addressable Store. Packages are stored once in a global store, then hard-linked into the project's node_modules/.pnpm, and finally connected via symbolic links, achieving both disk savings and strict dependency management at the same time.

The adoption process proceeded in the following order:

• Install pnpm globally
• Create pnpm-workspace.yaml at the root to declare the workspace
• Reference internal packages as workspace:* in each app's package.json
• Delete existing node_modules and cache, then run pnpm install
• Find and clean up phantom dependencies using depcheck
• Migrate existing dependency settings such as resolutions to fit the Pnpm environment

One exception had to be handled in the deployment environment. Amplify Preview does not support symbolic links, so it didn't work with the default Pnpm configuration; this was resolved by using node-linker=hoisted in .npmrc only during the build stage. Production, on the other hand, used GitHub Actions, so Pnpm caching could be attached and it ran normally.

After the migration, production deployments completed without issues, and install speed also improved significantly. On Amplify Preview, it went from Done in 74.52s to about Done in 25.1s, roughly 3 times faster, and on GitHub Actions, installs that used to take an average of 45-50 seconds dropped to 25-30 seconds.

However, the node_modules size actually increased slightly, which was attributed to phantom dependencies now being installed directly, as well as the structure where different versions of the same library are used within the monorepo. In such cases, optimization by cleaning up version mismatches with syncpack is effective.

In conclusion, migrating to Pnpm fits especially well for a TurboRepo monorepo, allowing teams to target both the removal of phantom dependencies and improved install speed at the same time. It also involves less configuration burden than Yarn Berry PnP, making it a worthwhile option for teams running monorepos to consider adopting.