packages:
  - 'apps/*'
  - 'packages/*'

{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

// apps/checkout/package.json
{
  "dependencies": {
    "@company/ui": "workspace:*",
    "@company/utils": "workspace:^1.0.0"
  }
}

my-monorepo/
├── pnpm-workspace.yaml
├── package.json              # root: no source, just scripts & devDeps
├── turbo.json                # task pipeline (covered in Part 2)
├── tsconfig.base.json        # shared TypeScript paths and compiler options
├── apps/
│   ├── web/                  # Next.js application
│   │   ├── package.json
│   │   └── tsconfig.json     # extends ../../tsconfig.base.json
│   └── dashboard/            # React SPA
│       ├── package.json
│       └── tsconfig.json
└── packages/
    ├── ui/                   # Shared component library
    │   ├── package.json
    │   ├── tsconfig.json
    │   └── src/
    ├── utils/                # Shared utility functions
    │   ├── package.json
    │   └── src/
    └── types/                # Shared TypeScript types
        ├── package.json
        └── src/

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev":   "turbo run dev --parallel",
    "test":  "turbo run test",
    "lint":  "turbo run lint"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "typescript": "^5.5.0"
  }
}

apps/checkout/node_modules/
└── @company/
    └── ui -> ../../../../packages/ui   # symlink to local package

# Yarn/npm hoisted flat structure
node_modules/            # root — hoisted packages live here
├── react/               # hoisted — used by both apps/web and packages/ui
├── lodash/              # hoisted — used by packages/utils
├── @company/
│   ├── ui -> packages/ui
│   └── utils -> packages/utils
apps/
└── checkout/
    └── node_modules/    # only packages that couldn't be hoisted (version conflicts)
packages/
└── ui/
    └── node_modules/    # only packages that couldn't be hoisted

// packages/ui/package.json
{
  "name": "@company/ui",
  "dependencies": {
    "clsx": "^2.1.0"
    // lodash is NOT listed here
  }
}

// packages/ui/src/utils.ts
import { merge } from 'lodash'  // ❌ Phantom dependency — lodash not in package.json

export function mergeStyles(...args: object[]) {
  return merge({}, ...args)
}

# packages/ui/src/utils.ts:1
Cannot find module 'lodash' or its corresponding type declarations.

// packages/ui/package.json
{ "dependencies": { "react": "^18.0.0" } }

// packages/legacy-widget/package.json
{ "dependencies": { "react": "^17.0.0" } }

~/.pnpm-store/
└── v3/
    └── files/
        ├── 00/
        │   └── a3f2b...  # react@18.3.1 index.js (content hash)
        ├── 1c/
        │   └── 8d4e1...  # react@17.0.2 index.js (content hash)
        └── ...

node_modules/
├── .pnpm/
│   ├── react@18.3.1/
│   │   └── node_modules/
│   │       └── react/       # hard link to ~/.pnpm-store/
│   ├── react@17.0.2/
│   │   └── node_modules/
│   │       └── react/       # hard link to ~/.pnpm-store/
│   ├── lodash@4.17.21/
│   │   └── node_modules/
│   │       └── lodash/      # hard link to ~/.pnpm-store/
│   └── clsx@2.1.0/
│       └── node_modules/
│           └── clsx/        # hard link to ~/.pnpm-store/
├── @company/
│   ├── ui -> ../../packages/ui
│   └── utils -> ../../packages/utils
└── (only declared direct deps appear here)

// packages/ui/src/utils.ts
import { merge } from 'lodash'  // lodash not in packages/ui/package.json

node_modules/.pnpm/react@18.3.1/node_modules/react/  ← packages/ui resolves here
node_modules/.pnpm/react@17.0.2/node_modules/react/  ← packages/legacy-widget resolves here

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "esModuleInterop": true,
    "skipLibCheck": false
  }
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "references": [
    { "path": "../../packages/ui" },
    { "path": "../../packages/utils" }
  ],
  "include": ["src/**/*"]
}

{
  "files": [],
  "references": [
    { "path": "packages/ui" },
    { "path": "packages/utils" },
    { "path": "packages/types" },
    { "path": "apps/checkout" },
    { "path": "apps/dashboard" }
  ]
}

# Full build — tsc computes the graph and builds only what changed
npx tsc --build

# Force clean rebuild
npx tsc --build --force

# Watch mode — incremental rebuilds on file save
npx tsc --build --watch

// ❌ Using paths aliases only — no build order, no incremental cache
{
  "compilerOptions": {
    "paths": {
      "@company/ui": ["../../packages/ui/src/index.ts"]
    }
  }
}