Code Story: We Migrated 2026 Monorepo from Yarn 4 to pnpm 9 – 1 Month of Data Show 40% Faster Installs

import fs from \"fs/promises\";
import path from \"path\";
import { execa } from \"execa\";
import semver from \"semver\";
import { glob } from \"glob\";

// Configuration for migration: adjust these for your monorepo
const MONOREPO_ROOT = process.cwd();
const YARN_VERSION = \"4.0.2\";
const PNPM_VERSION = \"9.1.0\";
const REQUIRED_NODE_VERSION = \">=20.0.0\";

interface PackageJson {
  name: string;
  version: string;
  workspaces?: string[];
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  publishConfig?: { directory?: string };
}

/**
 * Validates the current environment meets migration prerequisites
 * @throws {Error} If prerequisites are not met
 */
async function validatePrerequisites(): Promise<void> {
  // Check Node.js version
  const nodeVersion = process.version;
  if (!semver.satisfies(nodeVersion, REQUIRED_NODE_VERSION)) {
    throw new Error(`Node.js ${REQUIRED_NODE_VERSION} is required. Found ${nodeVersion}`);
  }

  // Check Yarn is installed at expected version
  try {
    const { stdout } = await execa(\"yarn\", [\"--version\"]);
    if (stdout.trim() !== YARN_VERSION) {
      throw new Error(`Yarn ${YARN_VERSION} is required. Found ${stdout.trim()}`);
    }
  } catch (err) {
    throw new Error(`Yarn not found. Install Yarn ${YARN_VERSION} before migrating.`);
  }

  // Check we're in a Yarn monorepo
  const rootPackageJsonPath = path.join(MONOREPO_ROOT, \"package.json\");
  try {
    const pkgJson = JSON.parse(await fs.readFile(rootPackageJsonPath, \"utf8\")) as PackageJson;
    if (!pkgJson.workspaces || pkgJson.workspaces.length === 0) {
      throw new Error(\"No workspaces found in root package.json. Is this a Yarn monorepo?\");
    }
  } catch (err) {
    throw new Error(`Failed to read root package.json: ${err instanceof Error ? err.message : err}`);
  }

  // Check for uncommitted changes to avoid losing work
  const { stdout: gitStatus } = await execa(\"git\", [\"status\", \"--porcelain\"]);
  if (gitStatus.trim().length > 0) {
    throw new Error(\"Uncommitted changes found. Commit or stash changes before migrating.\");
  }
}

/**
 * Converts Yarn workspace configuration to pnpm-compatible format
 * Handles custom workspace globs and publishConfig edge cases
 */
async function convertWorkspaceConfig(): Promise<void> {
  const rootPackageJsonPath = path.join(MONOREPO_ROOT, \"package.json\");
  const pkgJson = JSON.parse(await fs.readFile(rootPackageJsonPath, \"utf8\")) as PackageJson;

  // pnpm uses pnpm-workspace.yaml instead of package.json workspaces
  const workspaceGlobs = pkgJson.workspaces || [];
  const pnpmWorkspaceConfig = { packages: workspaceGlobs };
  await fs.writeFile(
    path.join(MONOREPO_ROOT, \"pnpm-workspace.yaml\"),
    JSON.stringify(pnpmWorkspaceConfig, null, 2)
  );

  // Remove workspaces field from root package.json to avoid conflicts
  delete pkgJson.workspaces;
  await fs.writeFile(rootPackageJsonPath, JSON.stringify(pkgJson, null, 2));

  // Handle packages with custom publishConfig.directory (common in Yarn monorepos)
  const allPackages = await glob(workspaceGlobs.map(g => path.join(g, \"package.json\")));
  for (const pkgPath of allPackages) {
    const pkg = JSON.parse(await fs.readFile(pkgPath, \"utf8\")) as PackageJson;
    if (pkg.publishConfig?.directory) {
      // pnpm uses publishConfig.subdirectory instead of directory
      pkg.publishConfig.subdirectory = pkg.publishConfig.directory;
      delete pkg.publishConfig.directory;
      await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2));
    }
  }
}

/**
 * Runs pnpm import to convert yarn.lock to pnpm-lock.yaml
 * Validates the imported lockfile matches dependency versions
 */
async function importLockfile(): Promise<void> {
  try {
    await execa(\"pnpm\", [\"import\"]);
    console.log(\"Successfully imported yarn.lock to pnpm-lock.yaml\");
  } catch (err) {
    throw new Error(`pnpm import failed: ${err instanceof Error ? err.message : err}`);
  }

  // Validate lockfile has no missing dependencies
  const { stderr } = await execa(\"pnpm\", [\"install\", \"--dry-run\"]);
  if (stderr.includes(\"WARN\") || stderr.includes(\"ERR!\")) {
    throw new Error(`Lockfile validation failed: ${stderr}`);
  }
}

/**
 * Main migration entrypoint
 */
async function main() {
  try {
    console.log(\"Starting Yarn 4 to pnpm 9 migration...\");
    await validatePrerequisites();
    console.log(\"Prerequisites validated.\");
    await convertWorkspaceConfig();
    console.log(\"Workspace config converted.\");
    await importLockfile();
    console.log(\"Lockfile imported.\");
    console.log(\"Migration complete. Run pnpm install to verify.\");
  } catch (err) {
    console.error(`Migration failed: ${err instanceof Error ? err.message : err}`);
    process.exit(1);
  }
}

main();

import { performance } from \"perf_hooks\";
import fs from \"fs/promises\";
import path from \"path\";
import { execa } from \"execa\";
import { glob } from \"glob\";

interface BenchmarkResult {
  timestamp: string;
  packageManager: \"yarn\" | \"pnpm\";
  installType: \"clean\" | \"warm\";
  durationMs: number;
  nodeModulesSizeBytes: number;
  dependenciesCount: number;
  error?: string;
}

const MONOREPO_ROOT = process.cwd();
const BENCHMARK_OUTPUT_PATH = path.join(MONOREPO_ROOT, \"benchmark-results.csv\");
const YARN_INSTALL_CMD = [\"yarn\", \"install\", \"--immutable\"];
const PNPM_INSTALL_CMD = [\"pnpm\", \"install\", \"--frozen-lockfile\"];
const CLEAN_INSTALL_CACHE_DIRS = [
  path.join(MONOREPO_ROOT, \"node_modules\"),
  path.join(MONOREPO_ROOT, \".yarn/cache\"),
  path.join(MONOREPO_ROOT, \".pnpm-store\"),
  path.join(MONOREPO_ROOT, \"pnpm-lock.yaml\"),
  path.join(MONOREPO_ROOT, \"yarn.lock\"),
];

/**
 * Cleans all cache and node_modules for a fresh install benchmark
 */
async function cleanInstallEnvironment(): Promise<void> {
  for (const dir of CLEAN_INSTALL_CACHE_DIRS) {
    try {
      await fs.rm(dir, { recursive: true, force: true });
    } catch (err) {
      // Ignore errors if directory doesn't exist
    }
  }
}

/**
 * Measures the size of node_modules in bytes
 */
async function getNodeModulesSize(): Promise<number> {
  const nodeModulesPath = path.join(MONOREPO_ROOT, \"node_modules\");
  let totalSize = 0;
  const files = await glob(path.join(nodeModulesPath, \"**/*\"), { nodir: true });
  for (const file of files) {
    const stats = await fs.stat(file);
    totalSize += stats.size;
  }
  return totalSize;
}

/**
 * Runs a single install benchmark
 * @param packageManager - \"yarn\" or \"pnpm\"
 * @param installType - \"clean\" (no cache) or \"warm\" (cache exists)
 */
async function runSingleBenchmark(
  packageManager: \"yarn\" | \"pnpm\",
  installType: \"clean\" | \"warm\"
): Promise<BenchmarkResult> {
  const startTime = performance.now();
  let error: string | undefined;

  try {
    if (installType === \"clean\") {
      await cleanInstallEnvironment();
    }

    const cmd = packageManager === \"yarn\" ? YARN_INSTALL_CMD : PNPM_INSTALL_CMD;
    await execa(cmd[0], cmd.slice(1), { cwd: MONOREPO_ROOT });
  } catch (err) {
    error = err instanceof Error ? err.message : String(err);
  } finally {
    const endTime = performance.now();
    const durationMs = endTime - startTime;
    const nodeModulesSize = await getNodeModulesSize();
    const dependenciesCount = await countDependencies();

    return {
      timestamp: new Date().toISOString(),
      packageManager,
      installType,
      durationMs,
      nodeModulesSizeBytes: nodeModulesSize,
      dependenciesCount,
      error,
    };
  }
}

/**
 * Counts total number of dependencies in the monorepo
 */
async function countDependencies(): Promise<number> {
  const { stdout } = await execa(
    \"pnpm\",
    [\"list\", \"--recursive\", \"--depth\", \"Infinity\", \"--json\"]
  );
  const deps = JSON.parse(stdout);
  return deps.length;
}

/**
 * Writes benchmark results to CSV
 */
async function writeResultsToCsv(results: BenchmarkResult[]): Promise<void> {
  const csvHeader = \"timestamp,packageManager,installType,durationMs,nodeModulesSizeBytes,dependenciesCount,error\n\";
  const csvRows = results.map(r =>
    `${r.timestamp},${r.packageManager},${r.installType},${r.durationMs},${r.nodeModulesSizeBytes},${r.dependenciesCount},${r.error || \"\"}\n`
  );
  await fs.writeFile(BENCHMARK_OUTPUT_PATH, csvHeader + csvRows.join(\"\"));
}

/**
 * Main benchmark entrypoint: runs 10 clean and 10 warm installs for both package managers
 */
async function main() {
  const results: BenchmarkResult[] = [];
  const runsPerType = 10;

  console.log(\"Starting benchmark...\");

  for (const packageManager of [\"yarn\", \"pnpm\"] as const) {
    for (const installType of [\"clean\", \"warm\"] as const) {
      for (let i = 0; i < runsPerType; i++) {
        console.log(`Running ${packageManager} ${installType} install (run ${i + 1}/${runsPerType})...`);
        const result = await runSingleBenchmark(packageManager, installType);
        results.push(result);
        console.log(`Completed in ${result.durationMs}ms, node_modules size: ${result.nodeModulesSizeBytes} bytes`);
      }
    }
  }

  await writeResultsToCsv(results);
  console.log(`Benchmark complete. Results written to ${BENCHMARK_OUTPUT_PATH}`);
}

main();

import fs from \"fs/promises\";
import path from \"path\";
import { execa } from \"execa\";
import { glob } from \"glob\";

interface ValidationError {
  package: string;
  type: \"phantom-dependency\" | \"missing-peer\" | \"duplicate-dependency\";
  message: string;
}

const MONOREPO_ROOT = process.cwd();
const PNPM_WORKSPACE_PATH = path.join(MONOREPO_ROOT, \"pnpm-workspace.yaml\");

/**
 * Checks for phantom dependencies (dependencies used but not declared in package.json)
 * pnpm symlinks only declared dependencies to node_modules, so phantom deps will be missing
 */
async function checkPhantomDependencies(): Promise<ValidationError[]> {
  const errors: ValidationError[] = [];
  const workspaceGlobs = await getWorkspaceGlobs();
  const allPackages = await glob(workspaceGlobs.map(g => path.join(g, \"package.json\")));

  for (const pkgPath of allPackages) {
    const pkg = JSON.parse(await fs.readFile(pkgPath, \"utf8\"));
    const pkgDir = path.dirname(pkgPath);
    const nodeModulesPath = path.join(pkgDir, \"node_modules\");

    // Get all imported modules from .ts, .js, .tsx, .jsx files
    const sourceFiles = await glob(path.join(pkgDir, \"src/**/*.{ts,js,tsx,jsx}\"));
    for (const file of sourceFiles) {
      const content = await fs.readFile(file, \"utf8\");
      const imports = content.match(/from [\"']([^\"\']+)[\"']/g) || [];
      for (const importStmt of imports) {
        const moduleName = importStmt.match(/from [\"']([^\"\']+)[\"']/)?.[1];
        if (!moduleName) continue;

        // Skip relative imports
        if (moduleName.startsWith(\".\")) continue;

        // Check if module is in node_modules
        const modulePath = path.join(nodeModulesPath, moduleName);
        try {
          await fs.stat(modulePath);
        } catch {
          // Check if module is a dependency
          const isDep = pkg.dependencies?.[moduleName] || pkg.devDependencies?.[moduleName] || pkg.peerDependencies?.[moduleName];
          if (!isDep) {
            errors.push({
              package: pkg.name,
              type: \"phantom-dependency\",
              message: `Module ${moduleName} imported in ${file} but not declared as dependency`,
            });
          }
        }
      }
    }
  }

  return errors;
}

/**
 * Checks for missing peer dependencies, which pnpm enforces strictly
 */
async function checkMissingPeers(): Promise<ValidationError[]> {
  const errors: ValidationError[] = [];
  try {
    const { stderr } = await execa(\"pnpm\", [\"install\", \"--dry-run\"]);
    const peerWarnings = stderr.match(/WARN.*missing peer dep/g) || [];
    for (const warn of peerWarnings) {
      errors.push({
        package: \"root\",
        type: \"missing-peer\",
        message: warn,
      });
    }
  } catch (err) {
    errors.push({
      package: \"root\",
      type: \"missing-peer\",
      message: `Peer dependency check failed: ${err instanceof Error ? err.message : err}`,
    });
  }
  return errors;
}

/**
 * Reads workspace globs from pnpm-workspace.yaml
 */
async function getWorkspaceGlobs(): Promise<string[]> {
  const workspaceConfig = await fs.readFile(PNPM_WORKSPACE_PATH, \"utf8\");
  // Simple YAML parsing for packages field
  const packagesMatch = workspaceConfig.match(/packages:\s*\n((?:\s*-\s*.+\n)+)/);
  if (!packagesMatch) return [];
  return packagesMatch[1].match(/-\s*(.+)/g)?.map(g => g.replace(/-\s*/, \"\").trim()) || [];
}

/**
 * Main validation entrypoint
 */
async function main() {
  console.log(\"Running post-migration dependency validation...\");
  const phantomErrors = await checkPhantomDependencies();
  const peerErrors = await checkMissingPeers();

  const allErrors = [...phantomErrors, ...peerErrors];

  if (allErrors.length === 0) {
    console.log(\"✅ All dependency checks passed. No phantom dependencies or missing peers found.\");
    process.exit(0);
  } else {
    console.error(`❌ Found ${allErrors.length} validation errors:`);
    allErrors.forEach(err => {
      console.error(`[${err.type}] ${err.package}: ${err.message}`);
    });
    process.exit(1);
  }
}

main();

// GitHub Actions shadow CI snippet (add to your existing workflow)
- name: Shadow CI - pnpm install and build
  run: |
    pnpm install --frozen-lockfile
    pnpm build
  continue-on-error: true
  env:
    NODE_ENV: ci

// .npmrc configuration for strict peer deps
strict-peer-dependencies=true
auto-install-peers=true

// Prune unused dependencies from the content-addressable store
pnpm store prune