pnpm Workspaces

pnpm Workspaces is the foundational architecture for the Total Ventures monorepo, enabling efficient dependency management and build orchestration across distinct web applications, backend services, and shared libraries.

What it is

pnpm Workspaces is a feature of the pnpm package manager that allows multiple packages to reside in a single repository, sharing dependencies and facilitating inter-package linking. Unlike other package managers, pnpm uses a content-addressable store for `node_modules`, meaning each package version is stored only once on disk. This approach creates hard links to the store for each project's `node_modules`, resulting in significant disk space savings and faster installation times. It's designed for scalability, handling complex dependency graphs without the bloat typically associated with large JavaScript projects. For a solo operator running multiple brands like Total Formula 1, Pregnancy Power Hour, and Inky, this efficiency is critical. It simplifies the development experience by centralizing dependency updates and ensuring consistency across all projects within the monorepo.

How I use it

My entire Total Ventures operation runs on a single monorepo, and pnpm Workspaces glues it together. Each brand, like Total Formula 1 or Pregnancy Power Hour, has its own web application and often a corresponding backend service, all living as separate workspaces within the monorepo. I also maintain a `shared` workspace for common UI components, utility functions, and API types. This setup means that when I update a core utility in `shared`, all dependent workspaces automatically get the change without manual linking or publishing private packages. This is crucial for agentic engineering workflows, where agents can modify shared components and see the impact across multiple applications instantly. For instance, a common authentication module used by Total Formula 1 and Inky lives in `shared`; pnpm ensures both applications reference the exact same, deduped dependency. When deploying, services like Turbo leverage pnpm's workspace awareness to only rebuild what's changed, further accelerating CI/CD pipelines. This integration streamlines everything from local development to production deployments, reducing friction and operational overhead.

Why this over alternatives

I chose pnpm Workspaces after years of dealing with `npm` and `yarn` in various professional settings. The primary driver was efficiency. With `npm` or `yarn` workspaces, even with hoisting, the `node_modules` directory can become a sprawling mess, especially with many projects. I learned the hard way that disk space and installation time compound quickly. pnpm's unique content-addressable store fundamentally solves this by hard-linking dependencies. This means a single `node_modules` folder for the entire monorepo, drastically reducing disk footprint and making installs consistently faster, even with 10+ distinct workspaces. This speed is not just a convenience; it translates directly to faster feedback loops during development and quicker CI builds, which is vital for a solo operator. The strictness of pnpm's dependency resolution also means fewer "phantom dependencies" – packages that work by accident because they were hoisted, not explicitly declared. This leads to more reliable builds and fewer surprises down the line. While Slack handles my cross-brand communication and Sentry catches errors across services, pnpm Workspaces ensures the underlying code structure is robust and efficient from the ground up.

Where it falls short

While pnpm Workspaces delivers on its promises, it's not without its quirks. The strict `node_modules` structure, while beneficial for correctness, can sometimes cause issues with tools or libraries that expect a more traditional, hoisted `node_modules` layout. I've encountered situations where certain build tools or legacy packages struggle to resolve dependencies correctly, requiring specific `pnpm-workspace.yaml` configurations or `pnpmfile.js` hooks to adapt. This is less common now, but it was a steeper learning curve initially. Debugging dependency resolution can also be less intuitive than with `npm` or `yarn` if you're not familiar with pnpm's unique approach. Additionally, the content-addressable store, while efficient, can sometimes feel like a black box if you need to manually inspect or modify dependencies directly. For a solo builder, understanding these nuances is part of the operational overhead. It's a trade-off I'm willing to make for the performance gains, but it's not entirely frictionless.