Skip to main content

Migration to pnpm

  • Status: Accepted
  • Authors: Marcus Taugner
  • Deciders: Abyss Team
  • Date: 2026-02-18

Context​

The Abyss monorepo and other related repositories currently use npm as the package manager. As the codebase has grown to include multiple packages (abyss-api, abyss-core, abyss-mobile, abyss-parcels, abyss-web), products (abyss-mobile-app, abyss-nextjs-15, abyss-docs-web, abyss-test, etc.), and related repositories (abyss-qe, abyss-pipelines), we're encountering challenges with:

  • Installation Speed: Long installation times, especially in CI/CD pipelines
  • Dependency Management: Potential for version inconsistencies across the monorepo
  • Workspace Support: npm workspaces work but lack some advanced features available in other package managers
  • Loose Dependency Resolution: npm's permissive approach allows packages to access dependencies they don't explicitly declare (phantom dependencies), which can lead to unexpected behavior and hard-to-debug issues

pnpm (performant npm) offers a more efficient approach to dependency management through:

  • Content-addressable storage (single global store with hard links)
  • Strict dependency resolution (prevents phantom dependencies by ensuring packages can only access declared dependencies)
  • Better monorepo/workspace support
  • Faster installation and lower disk usage
  • Compatible with npm registry and existing package.json structure

Decision​

We will migrate all Abyss codebases from npm to pnpm as the primary package manager. This migration will include:

  1. Package Manager Switch: Replace npm with pnpm across all packages and products
  2. Lock File Migration: Convert package-lock.json to pnpm-lock.yaml
  3. Dependency Cleanup: Identify and fix any phantom dependencies by adding missing packages to package.json files
  4. CI/CD Updates: Update all GitHub Actions, Docker files, and deployment scripts to use pnpm
  5. Documentation: Update developer onboarding and contribution guides
  6. Team Training: Provide guidance on pnpm commands and workflow differences

Alternatives Considered​

Continue with npm​

  • Pros: No migration effort, team familiarity, most widely adopted package manager
  • Cons: Slower installs, less efficient monorepo handling, permissive dependency resolution allows phantom dependencies

Yarn​

  • Pros: Faster than npm, good workspace support, widely adopted
  • Cons:
    • More complex CI/CD setup coming from npm
    • Less efficient disk usage than pnpm

Bun​

  • Pros: Extremely fast, modern tooling
  • Cons:
    • Relatively new and less battle-tested
    • Smaller ecosystem and community support
    • Higher risk for enterprise adoption

Consequences​

Positive​

  • Performance: 2-3x faster installation times in local development and CI/CD
  • Cost Savings: Reduced CI/CD compute time from faster installs translates to lower infrastructure costs
  • Disk Space: Significant reduction (potentially 50-70%) in disk usage across developer machines and build servers
  • Reliability: Stricter dependency resolution prevents phantom dependencies and ensures consistency
  • Monorepo Efficiency: Better support for workspace protocols and cross-package dependencies
  • Developer Experience: Faster feedback loops during development
  • Security Overrides: pnpm's overrides feature enables patching vulnerable dependencies (e.g., in transitive dependencies like those used by Appium) that npm's override mechanism cannot address, improving our security posture

Negative​

Migration Impact​

  • All developers must install pnpm: npm install -g pnpm
  • Remove existing package-lock.json files
  • CI/CD pipelines require updates
  • README and documentation updates across all repositories
  • Additional repositories impacted: abyss-qe and abyss-pipelines

Future Considerations​

  • Monitoring: Track installation times and disk usage to measure improvement
  • Tooling Evaluation: Periodically evaluate if pnpm continues to meet our needs
  • Version Updates: Stay current with pnpm releases for performance improvements and bug fixes
  • Workspace Optimization: Explore advanced pnpm features for better monorepo management (e.g., catalog protocol, workspace ranges)
  • Developer Tooling: Consider pnpm-specific optimizations in IDE configurations

References​

Revision History​

  • 02/18/2026: Initial commit
  • 04/17/2026: Status moved to Accepted - abyss, abyss-qe, and abyss-pipelines repos now running pnpm
Table of Contents