Managing Full Stack Monorepo with pnpm

Introduction

Modern full-stack development often involves managing multiple interconnected projects: a React frontend, a Node.js backend, shared utility libraries, and perhaps a mobile application. Traditionally, teams maintained separate repositories for each component, but this approach introduces significant challenges around code sharing, dependency management, and consistency. Enter the monorepo pattern--a development strategy that stores all related projects in a single repository, combined with pnpm's workspace feature to make this approach practical and efficient.

The monorepo approach offers compelling advantages for full-stack development teams. When your frontend and backend share types, utilities, and configurations, keeping them in the same repository eliminates version synchronization headaches and enables cross-project refactoring with confidence. However, managing a monorepo requires the right tooling, and pnpm has emerged as the package manager of choice for teams prioritizing performance and type safety. For teams building modern web applications, adopting a monorepo structure can significantly improve development velocity and code quality.

This guide explores how to effectively manage a full-stack monorepo using pnpm workspaces, with a particular emphasis on TypeScript-first development practices.

Understanding pnpm Workspaces

What Makes pnpm Different

pnpm (performant npm) takes a fundamentally different approach to dependency management compared to npm and Yarn. While npm and Yarn create nested node_modules directories that duplicate dependencies across projects, pnpm uses a content-addressable store with hard links to share a single copy of each package version across all projects on your system. This approach delivers dramatic improvements in disk usage and installation speed, particularly in monorepo environments where multiple projects might otherwise require identical dependencies.

Beyond disk efficiency, pnpm enforces strict dependency resolution that prevents phantom dependencies--packages that your code can import without being explicitly declared in your package.json. This strictness, while initially requiring more attention to your dependency declarations, ultimately leads to more predictable builds and fewer "works on my machine" scenarios. For TypeScript projects, this predictability directly translates to more reliable type checking and compilation.

The Workspace Concept

A pnpm workspace is a collection of packages that share a common node_modules directory at the root level. When you install dependencies in a workspace, pnpm hoists shared dependencies to the root while maintaining the ability for each package to declare its own dependencies. This hybrid approach combines the simplicity of having a single dependency installation with the flexibility of per-project dependency declarations.

Workspaces are defined through a pnpm-workspace.yaml file at your repository root. This file specifies which directories contain packages, allowing pnpm to understand your monorepo structure and manage cross-package dependencies appropriately.

Setting Up Your Monorepo Structure

Directory Organization

A well-organized monorepo structure separates concerns while keeping related code together. The most common approach divides your repository into three main directories: apps for applications, packages for shared libraries, and tools for development utilities.

my-monorepo/
├── apps/
│ ├── web/ # React frontend application
│ ├── api/ # Node.js backend API
│ └── admin/ # Internal admin dashboard
├── packages/
│ ├── ui/ # Shared React component library
│ ├── utils/ # Shared utility functions
│ ├── api-client/ # Type-safe API client
│ └── config/ # Shared TypeScript/Eslint configs
├── tools/
│ ├── eslint-config/ # Shared ESLint configuration
│ └── tsconfig/ # Shared TypeScript configurations
├── pnpm-workspace.yaml
└── package.json

This structure enables clear ownership patterns--teams can own specific packages while having visibility into how their changes affect the broader system.

Workspace Configuration File

The pnpm-workspace.yaml file tells pnpm which directories contain workspace packages:

# pnpm-workspace.yaml
packages:
 - 'apps/*'
 - 'packages/*'
 - 'tools/*'

Root package.json Configuration

The root package.json serves as the command center for your monorepo:

{
 "name": "my-monorepo",
 "scripts": {
 "build": "pnpm -r build",
 "test": "pnpm -r test",
 "lint": "pnpm -r lint",
 "dev": "pnpm -r --parallel dev"
 }
}

TypeScript Configuration Across Workspaces

Centralized TypeScript Configuration

TypeScript-first development in a monorepo benefits significantly from centralized configuration. By sharing a base tsconfig.json across all packages, you ensure consistent type checking rules, compiler options, and code style throughout your codebase. Teams choosing between Babel and TypeScript as their compiler should consider that TypeScript's native monorepo support makes it a strong choice for full-stack projects.

// tools/tsconfig/base.json
{
 "compilerOptions": {
 "target": "ES2022",
 "module": "ESNext",
 "moduleResolution": "bundler",
 "strict": true,
 "esModuleInterop": true,
 "declaration": true,
 "declarationMap": true,
 "sourceMap": true
 }
}

Individual packages then extend this base configuration:

// packages/utils/tsconfig.json
{
 "extends": "../../tools/tsconfig/base.json",
 "compilerOptions": {
 "outDir": "./dist",
 "rootDir": "./src"
 }
}

Type Sharing Between Packages

One of the most powerful aspects of monorepo development is the ability to share types between packages without publishing to a registry. The workspace protocol enables this:

// apps/web/package.json
{
 "dependencies": {
 "@my-org/api-client": "workspace:*",
 "@my-org/utils": "workspace:^1.0.0"
 }
}

Project References for Faster Builds

TypeScript's project references feature enables incremental builds across your monorepo:

// packages/api-client/tsconfig.json
{
 "extends": "../../tools/tsconfig/base.json",
 "compilerOptions": {
 "composite": true,
 "outDir": "./dist",
 "rootDir": "./src"
 },
 "references": [
 { "path": "../utils" }
 ]
}

Managing Shared Packages

Creating a Utility Package

Shared utility packages contain pure functions and helpers that multiple applications can use without modification:

// packages/utils/src/index.ts
export function formatCurrency(
 amount: number,
 currency = 'USD'
): string {
 return new Intl.NumberFormat('en-US', {
 style: 'currency',
 currency,
 }).format(amount);
}

export function debounce<T extends (...args: any[]) => any>(
 func: T,
 wait: number
): (...args: Parameters<T>) => void {
 let timeout: NodeJS.Timeout;
 return (...args: Parameters<T>) => {
 clearTimeout(timeout);
 timeout = setTimeout(() => func.apply(this, args), wait);
 };
}

Building a Type-safe API Client Package

API client packages demonstrate TypeScript's power in a monorepo context. By sharing types between your backend API definitions and your frontend client package, you create a type-safe layer:

// packages/api-client/src/types.ts
export interface User {
 id: string;
 email: string;
 name: string;
 createdAt: string;
}

export interface CreateUserRequest {
 email: string;
 name: string;
}

Component Library Packages

Shared UI component packages enforce design system consistency across applications. For teams using modern frontend tooling like Vite, creating a centralized component library ensures consistent styling and behavior across all applications:

// packages/ui/src/components/Button/Button.tsx
interface ButtonProps {
 children: React.ReactNode;
 variant?: 'primary' | 'secondary' | 'danger';
 size?: 'sm' | 'md' | 'lg';
 onClick?: () => void;
}

Best Practices for Monorepo Management

Use the Workspace Protocol Correctly

The workspace protocol is essential for internal package references:

• workspace:* -- Matches any version of the local package
• workspace:^1.0.0 -- Requires the local package to have major version 1

Organize by Purpose, Not by Layer

Group packages by their purpose rather than by technical layer. A structure organized as packages/checkout, packages/user-profile creates clearer ownership boundaries than packages/ui, packages/api.

Centralize Configuration When Possible

Configuration duplication across packages leads to inconsistency. Centralize ESLint, TypeScript, Prettier, and other tool configurations. Modern linting tools like ESLint alternatives can be integrated into your monorepo's shared configuration for consistent code quality across all packages:

// packages/eslint-config/base.js
module.exports = {
 extends: [
 'eslint:recommended',
 'plugin:@typescript-eslint/recommended',
 'prettier',
 ],
 rules: {
 '@typescript-eslint/explicit-function-return-type': 'error',
 },
};

Implement Consistent Build Pipelines

Every package should follow consistent patterns:

{
 "scripts": {
 "build": "tsup src/index.ts --format cjs,esm --dts",
 "dev": "tsup src/index.ts --watch",
 "test": "vitest",
 "lint": "eslint src --ext .ts,.tsx",
 "type-check": "tsc --noEmit"
 }
}

Performance Optimization

Leveraging pnpm's Hard Links

pnpm's content-addressable storage provides substantial performance benefits. Unlike npm, which creates nested node_modules with duplicated packages, pnpm's node_modules contains only direct dependencies and symlinks to the shared store.

Reducing Installation Time

• Use pnpm dedupe to remove unnecessary package copies
• Configure pnpm to prune dev dependencies in production builds
• Consider using pnpm's catalogs feature to define shared dependency versions

Build Caching Strategies

Combine pnpm with a build caching tool like Turborepo to dramatically reduce CI/CD times. Turborepo caches build outputs based on file hashes, replaying cached results when inputs haven't changed. For teams focused on AI automation services, efficient monorepo management ensures faster deployment cycles for AI-powered applications:

// turbo.json
{
 "pipeline": {
 "build": {
 "dependsOn": ["^build"],
 "outputs": ["dist/**", ".next/**"]
 },
 "test": {
 "outputs": ["coverage/**"]
 }
 }
}

Conclusion

Managing a full-stack monorepo with pnpm workspaces combines the code-sharing benefits of a unified repository with the performance and type-safety advantages that TypeScript-first development provides. By understanding pnpm's unique approach to dependency management, structuring your monorepo thoughtfully, and centralizing configuration where it makes sense, you can build a development environment that scales with your team and your codebase.

The key principles to remember are: use the workspace protocol for internal dependencies, centralize configuration while allowing package-specific customization, implement consistent build and test patterns across all packages, and leverage TypeScript's project references for incremental builds. With these practices in place, your monorepo becomes a competitive advantage rather than a maintenance burden, enabling your team to move faster while maintaining code quality.

Sources

• pnpm.io: Workspace Configuration
• pnpm.io: Catalogues
• Glen Thomas Blog: Mastering pnpm Workspaces
• Peerlist: Complete Monorepo Guide
• LogRocket: pnpm tutorial
• GitHub: Turborepo