> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# pnpm Workspace Dependency Issues

> Resolving dependency issues in pnpm workspace environments

This covers dependency-related problems that occur in pnpm workspace environments and how to resolve them.

## Strict Dependency Resolution

### Symptoms

```bash theme={null}
pnpm install

 ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

.
└─┬ @types/react 19.2.7
  └── ✕ missing peer prop-types@^15.0.0

Peer dependencies that should be installed:
  prop-types@^15.8.1
```

### Cause

pnpm has stricter dependency resolution than Yarn or npm. It doesn't automatically install missing peer dependencies and requires explicit installation.

### Solutions

#### 1. Explicitly Install Peer Dependency

```bash theme={null}
pnpm add -D prop-types
```

#### 2. auto-install-peers Setting (Not Recommended)

`.npmrc`:

```ini theme={null}
auto-install-peers=true
```

**Drawback:** Dependency tree can become unpredictable

#### 3. Use pnpm.overrides

`package.json`:

```json theme={null}
{
  "pnpm": {
    "overrides": {
      "prop-types": "^15.8.1"
    }
  }
}
```

## Workspace Protocol Error

### Symptoms

```bash theme={null}
 ERR_PNPM_WORKSPACE_PKG_NOT_FOUND

In sonamu: "workspace:*" is in the dependencies but no package
named "sonamu" is present in the workspace
```

### Cause

Used `workspace:*` protocol but that package doesn't exist in the workspace.

### Solutions

#### 1. Check Workspace Packages

`pnpm-workspace.yaml`:

```yaml theme={null}
packages:
  - examples/**/*
  - modules/**/*
  - "!modules/create-sonamu/template/**/*"
```

#### 2. Check Package Name

```bash theme={null}
# Check all packages in workspace
pnpm ls -r --depth -1
```

#### 3. Fix package.json

```json theme={null}
{
  "dependencies": {
    "sonamu": "workspace:*" // sonamu package must exist in workspace
  }
}
```

## Catalog Version Mismatch

### Symptoms

```bash theme={null}
 ERR_PNPM_CATALOG_VERSION_MISMATCH

Package "react" has version "19.2.3" in catalog but "18.3.0"
in package.json
```

### Cause

Version defined in `pnpm-workspace.yaml` catalog differs from `package.json` version.

### Solutions

#### 1. Use Catalog Version (Recommended)

`package.json`:

```json theme={null}
{
  "dependencies": {
    "react": "catalog:" // Use version from pnpm-workspace.yaml
  }
}
```

#### 2. Update Catalog

`pnpm-workspace.yaml`:

```yaml theme={null}
catalog:
  react: ^19.2.3 # Update to match package.json
```

#### 3. Unify All Workspace to Catalog Version

```bash theme={null}
# Update all packages' dependencies to catalog version
pnpm update -r
```

## Hoisting Issues

### Symptoms

```bash theme={null}
Error: Cannot find module '@types/node'
Require stack:
- /path/to/your/project/src/index.ts
```

Module is installed but cannot be found.

### Cause

pnpm doesn't hoist dependencies by default. Each package is isolated under `node_modules/.pnpm`.

### Solutions

#### 1. Use public-hoist-pattern

`.npmrc`:

```ini theme={null}
public-hoist-pattern[]=@types/*
public-hoist-pattern[]=eslint-*
```

Hoists specific packages to root `node_modules`.

#### 2. shamefully-hoist (Last Resort)

`.npmrc`:

```ini theme={null}
shamefully-hoist=true
```

**Warning:** Works like npm/yarn but gives up pnpm's advantages.

#### 3. Declare Correct Dependencies

```json theme={null}
{
  "devDependencies": {
    "@types/node": "catalog:"
  }
}
```

Declaring required packages directly is safest.

## TypeScript Path Mapping Error

### Symptoms

```typescript theme={null}
import { UserModel } from "@/application/user/user.model";
// Error: Cannot find module '@/application/user/user.model'
```

### Cause

TypeScript path mapping doesn't work properly due to pnpm's strict dependency resolution.

### Solutions

#### 1. tsconfig.json Configuration

```json theme={null}
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

#### 2. tsx/ts-node Configuration

`tsconfig.json`:

```json theme={null}
{
  "ts-node": {
    "require": ["tsconfig-paths/register"]
  }
}
```

Install:

```bash theme={null}
pnpm add -D tsconfig-paths
```

## Phantom Dependencies

### Symptoms

A package imported directly in code doesn't exist in `package.json` but works.

```typescript theme={null}
import _ from "lodash-es"; // Not in package.json
```

Works locally but fails in CI or other environments.

### Cause

**Phantom Dependencies** - accidentally accessible through dependencies of other packages.

### Solutions

#### 1. Add Explicit Dependency

```bash theme={null}
pnpm add lodash-es
```

#### 2. Run pnpm check

```bash theme={null}
# Check phantom dependencies
pnpm ls --depth=Infinity

# Check why a package exists
pnpm why <package-name>
```

## onlyBuiltDependencies Error

### Symptoms

```bash theme={null}
 ERR_PNPM_CANNOT_RESOLVE_OPTIONAL_DEPENDENCY

Could not resolve optional dependency @parcel/watcher
```

### Cause

Packages in `onlyBuiltDependencies` list are configured to install optionally only.

### Solution

`pnpm-workspace.yaml`:

```yaml theme={null}
onlyBuiltDependencies:
  - "@parcel/watcher"
  - bcrypt
  - esbuild
  - sharp
```

These packages contain binaries and require platform-specific installation. If installation fails:

```bash theme={null}
# Retry installation
pnpm install --force

# Or specific package only
pnpm add sharp --force
```

## Overrides Not Applied

### Symptoms

`pnpm.overrides` is configured but not applied.

```json theme={null}
{
  "pnpm": {
    "overrides": {
      "axios": ">=1.0.0"
    }
  }
}
```

### Causes

1. Overrides syntax is wrong
2. Set in non-workspace-root location
3. pnpm version is old

### Solutions

#### 1. Correct Overrides Syntax

`package.json` (workspace root):

```json theme={null}
{
  "pnpm": {
    "overrides": {
      "axios@<1.0.0": ">=1.0.0",
      "lodash": "^4.17.21"
    }
  }
}
```

#### 2. Use in pnpm-workspace.yaml

```yaml theme={null}
overrides:
  axios@<0.30.0: ">=0.30.0"
  axios@>=0.8.1 <0.28.0: ">=0.28.0"
```

#### 3. Verify Applied

```bash theme={null}
# Regenerate lockfile
pnpm install --force

# Check version
pnpm why axios
```

## Circular Workspace Dependencies

### Symptoms

```bash theme={null}
 ERR_PNPM_WORKSPACE_CYCLE

There is a circular dependency in the workspace:
  @sonamu-kit/react-sui -> @sonamu-kit/ui -> @sonamu-kit/react-sui
```

### Cause

Workspace packages reference each other, causing circular dependency.

### Solutions

#### 1. Redesign Dependency Structure

```json theme={null}
// @sonamu-kit/react-sui/package.json
{
  "dependencies": {
    "@sonamu-kit/ui": "workspace:*"  // ❌ react-sui depends on ui
  }
}

// @sonamu-kit/ui/package.json
{
  "dependencies": {
    "@sonamu-kit/react-sui": "workspace:*"  // ❌ ui depends on react-sui
  }
}
```

Solution:

```json theme={null}
// Extract common dependencies into separate package
// Create @sonamu-kit/common, both reference it
```

#### 2. Use peerDependencies

```json theme={null}
{
  "peerDependencies": {
    "@sonamu-kit/ui": "workspace:*"
  }
}
```

## Cache Issues

### Symptoms

Previous version is still used even after updating dependencies.

### Solutions

#### 1. Clean pnpm store

```bash theme={null}
# Verify store
pnpm store prune

# Full cleanup
pnpm store prune --force
```

#### 2. Complete Reinstall

```bash theme={null}
# Delete node_modules
rm -rf node_modules

# Reinstall keeping lockfile
pnpm install --frozen-lockfile

# Or fresh install
rm pnpm-lock.yaml
pnpm install
```

## Related Documentation

* [Type Errors](/en/troubleshooting/common-errors/type-errors)
* [TypeScript Configuration](/en/configuration/typescript/tsconfig)
* [HMR Issues](/en/troubleshooting/common-errors/hmr-issues)