Examples

Real-world examples and use cases to help you get the most out of PCU. From simple updates to complex monorepo management.

Basic Workflows

Daily Dependency Check

Check for updates as part of your daily development routine:

# Check for updates with simple output
pcu -c --format minimal

# Example output:
# react           ^18.2.0  →  ^18.3.0
# typescript      ^5.0.0   →  ^5.2.0
# @types/node     ^18.0.0  →  ^20.0.0

Safe Updates with Backup

Update dependencies safely with automatic backups:

# Interactive updates with backup
pcu -i -b

# Or automated minor updates with backup
pcu -u --target minor --create-backup

Target-Specific Updates

Update only specific types of changes:

# Only patch updates (bug fixes)
pcu -u --target patch

# Only minor updates (new features, no breaking changes)
pcu -u --target minor

Multi-Catalog Workspaces

Legacy Support Scenario

Managing multiple React versions in one workspace:

packages:
  - "apps/*"
  - "packages/*"

catalog:
  # Default catalog - latest versions
  react: ^18.2.0
  react-dom: ^18.2.0
  @types/react: ^18.2.0

catalogs:
  # Legacy support
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2
    @types/react: ^17.0.62

  # Beta testing
  react-next:
    react: ^19.0.0-beta
    react-dom: ^19.0.0-beta

Package Usage

package.json

{
  "name": "@myorg/modern-app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  }
}

Legacy package.json

{
  "name": "@myorg/legacy-app",
  "dependencies": {
    "react": "catalog:react17",
    "react-dom": "catalog:react17"
  }
}

Configuration Examples

React Ecosystem Management

Coordinated updates for React and related packages:

.pcurc.json

{
  "packageRules": [
    {
      "patterns": ["react", "react-dom"],
      "target": "minor",
      "requireConfirmation": true,
      "relatedPackages": [
        "@types/react",
        "@types/react-dom",
        "react-router-dom",
        "@testing-library/react"
      ]
    }
  ],
  "security": {
    "autoFixVulnerabilities": true,
    "allowMajorForSecurity": true
  }
}

TypeScript Project Configuration

Conservative TypeScript updates with automatic type definitions:

.pcurc.json

{
  "packageRules": [
    {
      "patterns": ["typescript"],
      "target": "minor",
      "requireConfirmation": true
    },
    {
      "patterns": ["@types/*"],
      "target": "latest",
      "autoUpdate": true
    },
    {
      "patterns": ["eslint*", "@typescript-eslint/*"],
      "target": "minor",
      "groupUpdate": true
    }
  ]
}

Enterprise Configuration

Enterprise-ready configuration with strict controls:

.pcurc.json

{
  "defaults": {
    "target": "minor",
    "createBackup": true
  },
  "exclude": ["typescript", "@types/node", "react", "react-dom"],
  "security": {
    "autoFixVulnerabilities": true,
    "allowMajorForSecurity": true,
    "notifyOnSecurityUpdate": true
  },
  "advanced": {
    "concurrency": 3,
    "timeout": 60000,
    "retries": 5
  },
  "ui": {
    "theme": "minimal",
    "animations": false
  }
}

CI/CD Integration

GitHub Actions

Automate dependency checking in your CI pipeline:

name: Check Dependencies

on:
  schedule:
    - cron: '0 9 * * MON'  # Every Monday at 9 AM
  workflow_dispatch:

jobs:
  check-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install PCU
        run: npm install -g pcu

      - name: Check for updates
        run: pcu -c --format json > updates.json

      - name: Create Issue if Updates Available
        if: success()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const updates = JSON.parse(fs.readFileSync('updates.json', 'utf8'));
            if (updates.length > 0) {
              github.rest.issues.create({
                owner: context.repo.owner,
                repo: context.repo.repo,
                title: 'Dependencies Update Available',
                body: `Found ${updates.length} packages that can be updated:

` +
                      updates.map(u => `- ${u.package}: ${u.current} → ${u.available}`).join('
')
              });
            }

Error Handling and Troubleshooting

Network Issues

Handle network problems and registry access:

# Increase timeout for slow connections
pcu -c --timeout 60000

# Reduce concurrency for unstable networks
pcu -u --concurrency 2

Workspace Validation

Validate your workspace setup:

# Check workspace configuration
pcu -s --validate

# Get detailed workspace information
pcu -s --stats --verbose

Private Registries

PCU automatically reads .npmrc and .pnpmrc configurations:

@myorg:registry=https://npm.private-registry.com/
//npm.private-registry.com/:_authToken=${NPM_TOKEN}

registry=https://registry.npmjs.org/

Advanced Use Cases

Impact Analysis

Analyze the impact of updating specific packages:

# Analyze React update impact
pcu -a default react

# Analyze with specific version
pcu -a default react 18.3.0

# Check impact across all catalogs
pcu -a react17 react 17.0.3

Selective Updates

Update only specific packages or patterns:

# Update only React-related packages
pcu -u --include "react*"

# Update everything except core frameworks
pcu -u --exclude "react*,vue*,angular*"

# Update only type definitions
pcu -u --include "@types/*" --target latest

Dry Run Analysis

Preview changes before applying them:

# See what would be updated
pcu -u --dry-run --verbose

# Preview with specific targets
pcu -u --dry-run --target minor --include "@types/*"

Best Practices

Daily Workflow

Morning Check: pcu -c to see available updates
Review Impact: Use pcu -a for significant updates
Safe Update: pcu -i -b for interactive updates with backup
Test: Run your test suite after updates
Commit: Commit dependency updates separately

Team Workflow

Shared Configuration: Commit .pcurc.json to version control
Regular Reviews: Schedule weekly dependency review meetings
Security Priority: Always prioritize security updates
Documentation: Document major dependency decisions
Rollback Plan: Keep backups for easy rollback

Release Workflow

Pre-release Check: pcu -c --target patch before releases
Security Scan: Enable autoFixVulnerabilities in CI
Version Pinning: Use exact versions for production releases
Update Schedule: Plan dependency updates between releases

Security Monitoring

Continuous Security Scanning

Integrate security scanning into your development workflow:

# Quick security scan
pcu security

# Automated fix for vulnerabilities
pcu security --fix-vulns

# Focus on high and critical issues only
pcu security --severity high --fix-vulns

Security-Focused CI/CD

.github/workflows/security.yml

name: Security Audit

on:
  schedule:
    - cron: '0 2 * * *' # Daily at 2 AM
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install PCU
        run: npm install -g pcu

      - name: Security Scan
        run: pcu security --fix-vulns --format json > security-results.json

      - name: Upload Security Report
        uses: actions/upload-artifact@v4
        with:
          name: security-report
          path: security-results.json

Theme Customization

Interactive Theme Setup

Configure PCU's appearance for your team:

# Launch interactive theme wizard
pcu theme --interactive

# Set specific theme
pcu theme --set modern

# List all available themes with previews
pcu theme --list

Team Theme Configuration

.pcurc.json

{
  "ui": {
    "theme": "modern",
    "progressBars": true,
    "animations": true,
    "colorScheme": "auto"
  },
  "output": {
    "format": "table",
    "color": true,
    "verbose": false
  }
}

Performance Optimization

Large Monorepo Configuration

Optimize PCU for large workspaces with hundreds of packages:

.pcurc.json

{
  "advanced": {
    "concurrency": 10,
    "timeout": 120000,
    "retries": 3,
    "cacheResults": true,
    "batchSize": 50
  },
  "performance": {
    "skipUnchanged": true,
    "useCache": true,
    "parallelAnalysis": true
  }
}

Selective Processing

# Process only changed packages since last commit
pcu -c --changed-only

# Skip packages that haven't been modified in 30 days
pcu -c --skip-stale --stale-days 30

# Parallel processing for faster results
pcu -c --concurrency 15

Migration Examples

From npm-check-updates

Migrating from ncu to PCU:

# Old ncu commands → New PCU equivalents

# ncu
pcu -c

# ncu -u
pcu -u

# ncu --target minor
pcu -u --target minor

# ncu --interactive
pcu -i

# ncu --packageFile package.json
pcu -w ./path/to/workspace

Converting to pnpm Catalogs

Transform existing workspace to use pnpm catalogs:

# Analyze current dependencies
pcu workspace --stats

# Initialize catalog structure
pcu init --create-workspace

# Convert dependencies to catalog references
pcu convert --to-catalog --dry-run
pcu convert --to-catalog --backup

Migration Guides

Migrating from npm-check-updates

Transition smoothly from npm-check-updates to PCU for pnpm catalog management:

# Old workflow with ncu
ncu --upgrade --packageFile package.json
ncu --upgrade --packageFile packages/*/package.json
npm install

Migration Steps

Install PCU alongside ncu temporarily for comparison
Initialize PCU configuration:
pcu init --template standard

Compare outputs to ensure equivalent functionality:

ncu --format minimal > ncu-output.txt
pcu -c --format minimal > pcu-output.txt
diff ncu-output.txt pcu-output.txt

Migrate package rules from ncu configuration
Remove ncu once comfortable with PCU

Migrating from Dependabot

Replace Dependabot with PCU for more granular control:

version: 2
updates:
  - package-ecosystem: 'npm'
    directory: '/'
    schedule:
      interval: 'weekly'
    open-pull-requests-limit: 5

Migrating from Renovate

Transition from Renovate to PCU with advanced configuration:

Key Differences

Feature	Renovate	PCU
Scope	Individual packages	Catalog-level updates
Configuration	renovate.json	.pcurc.json
UI	Web dashboard	Terminal + CI integration
Monorepo	Complex config	Built-in workspace support

Migration Configuration

{
  "extends": ["config:base"],
  "schedule": ["before 5am on monday"],
  "packageRules": [
    {
      "matchPackageNames": ["react", "react-dom"],
      "groupName": "React"
    }
  ]
}

CI/CD Workflow Integration

GitHub Actions Integration

Complete GitHub Actions setup for automated dependency management:

name: Dependency Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  dependency-check:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: latest
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Install PCU
        run: pnpm add -g pnpm-catalog-updates

      - name: Check for updates
        run: pcu -c --format table

      - name: Security scan
        run: pcu security --severity high

GitLab CI Integration

GitLab CI pipeline for PCU dependency management:

stages:
  - check
  - security
  - update

variables:
  PNPM_CACHE_FOLDER: .pnpm-store

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .pnpm-store

before_script:
  - corepack enable
  - pnpm config set store-dir $PNPM_CACHE_FOLDER
  - pnpm install
  - pnpm add -g pnpm-catalog-updates

dependency-check:
  stage: check
  script:
    - pcu -c --format table
    - pcu workspace --validate
  artifacts:
    reports:
      junit: dependency-report.xml
  only:
    - merge_requests
    - main

security-scan:
  stage: security
  script:
    - pcu security --format json --severity moderate > security.json
    - |
      if [ -s security.json ] && [ "$(cat security.json | jq length)" -gt 0 ]; then
        echo "Security vulnerabilities found:"
        cat security.json | jq '.'
        exit 1
      fi
  artifacts:
    reports:
      security: security.json
  only:
    - merge_requests
    - main

weekly-update:
  stage: update
  script:
    - git config user.name "PCU Bot"
    - git config user.email "pcu@gitlab.com"
    - pcu -c --format json > updates.json
    - |
      if [ -s updates.json ]; then
        pcu -u --target minor --create-backup
        git add .
        git commit -m "chore: weekly dependency updates"
        git push origin HEAD:pcu/weekly-updates
      fi
  only:
    - schedules
  variables:
    GIT_STRATEGY: clone

Jenkins Pipeline Integration

Jenkins pipeline for enterprise dependency management:

pipeline {
    agent any

    tools {
        nodejs '18'
    }

    environment {
        PNPM_HOME = "${env.WORKSPACE}/.pnpm"
        PATH = "${env.PNPM_HOME}:${env.PATH}"
    }

    stages {
        stage('Setup') {
            steps {
                sh 'corepack enable'
                sh 'pnpm install'
                sh 'pnpm add -g pnpm-catalog-updates'
            }
        }

        stage('Dependency Check') {
            steps {
                sh 'pcu -c --format json > dependency-check.json'

                script {
                    def updates = readJSON file: 'dependency-check.json'
                    if (updates.size() > 0) {
                        env.HAS_UPDATES = 'true'
                        echo "Found ${updates.size()} packages to update"
                    } else {
                        env.HAS_UPDATES = 'false'
                        echo "No updates available"
                    }
                }
            }
            post {
                always {
                    archiveArtifacts artifacts: 'dependency-check.json'
                }
            }
        }

        stage('Security Scan') {
            when {
                environment name: 'HAS_UPDATES', value: 'true'
            }
            steps {
                sh 'pcu security --format json --severity high > security-report.json'

                script {
                    def securityReport = readJSON file: 'security-report.json'
                    if (securityReport.vulnerabilities && securityReport.vulnerabilities.size() > 0) {
                        error "Critical security vulnerabilities found: ${securityReport.vulnerabilities.size()}"
                    }
                }
            }
            post {
                always {
                    publishHTML([
                        allowMissing: false,
                        alwaysLinkToLastBuild: true,
                        keepAll: true,
                        reportDir: '.',
                        reportFiles: 'security-report.json',
                        reportName: 'Security Report'
                    ])
                }
            }
        }

        stage('Update Dependencies') {
            when {
                allOf {
                    environment name: 'HAS_UPDATES', value: 'true'
                    branch 'main'
                }
            }
            steps {
                sh 'pcu -u --target minor --create-backup'
                sh 'pnpm test'

                script {
                    sh '''
                        git config user.name "Jenkins PCU"
                        git config user.email "jenkins@company.com"
                        git add .
                        git commit -m "chore: automated dependency updates [skip ci]"
                    '''

                    // Create merge request (GitLab) or pull request (GitHub)
                    sh '''
                        git push origin HEAD:pcu/automated-updates-${BUILD_NUMBER}
                    '''
                }
            }
        }
    }

    post {
        always {
            cleanWs()
        }

        success {
            echo 'PCU dependency check completed successfully'
        }

        failure {
            emailext (
                subject: "PCU Dependency Check Failed - ${env.JOB_NAME} - ${env.BUILD_NUMBER}",
                body: "Dependency check failed. Please review the console output.",
                to: "${env.CHANGE_AUTHOR_EMAIL}"
            )
        }
    }
}

Azure DevOps Pipeline

Azure DevOps pipeline for PCU integration:

trigger:
  branches:
    include:
      - main
      - develop

schedules:
  - cron: '0 8 * * 1'
    displayName: Weekly dependency check
    branches:
      include:
        - main
    always: true

pool:
  vmImage: 'ubuntu-latest'

variables:
  PNPM_CACHE_FOLDER: $(Pipeline.Workspace)/.pnpm-store

stages:
  - stage: DependencyCheck
    displayName: 'Dependency Check'
    jobs:
      - job: CheckUpdates
        displayName: 'Check for updates'
        steps:
          - task: Cache@2
            inputs:
              key: 'pnpm | "$(Agent.OS)" | pnpm-lock.yaml'
              restoreKeys: |
                pnpm | "$(Agent.OS)"
              path: $(PNPM_CACHE_FOLDER)
            displayName: Cache pnpm

          - script: |
              corepack enable
              pnpm config set store-dir $(PNPM_CACHE_FOLDER)
              pnpm install
              pnpm add -g pnpm-catalog-updates
            displayName: 'Setup PNPM and PCU'

          - script: |
              pcu -c --format json > $(Agent.TempDirectory)/updates.json
              pcu workspace --validate
            displayName: 'Check dependencies'

          - script: |
              pcu security --format json --severity moderate > $(Agent.TempDirectory)/security.json
            displayName: 'Security scan'

          - task: PublishTestResults@2
            condition: always()
            inputs:
              testResultsFormat: 'JUnit'
              testResultsFiles: '**/*-results.xml'
              failTaskOnFailedTests: true
            displayName: 'Publish security results'

          - task: PublishBuildArtifacts@1
            inputs:
              pathToPublish: '$(Agent.TempDirectory)'
              artifactName: 'dependency-reports'
            displayName: 'Publish artifacts'

  - stage: UpdateDependencies
    displayName: 'Update Dependencies'
    condition: and(succeeded(), or(eq(variables['Build.Reason'], 'Schedule'), eq(variables['Build.Reason'], 'Manual')))
    jobs:
      - job: UpdateCatalog
        displayName: 'Update catalog dependencies'
        steps:
          - checkout: self
            persistCredentials: true

          - script: |
              corepack enable
              pnpm install
              pnpm add -g pnpm-catalog-updates
            displayName: 'Setup environment'

          - script: |
              git config user.name "Azure DevOps PCU"
              git config user.email "devops@company.com"

              pcu -u --target minor --create-backup

              if [ -n "$(git status --porcelain)" ]; then
                git add .
                git commit -m "chore: update catalog dependencies [skip ci]"
                git push origin HEAD:refs/heads/pcu/automated-updates-$(Build.BuildNumber)
              fi
            displayName: 'Update dependencies'

          - script: pnpm test
            displayName: 'Run tests'

Docker Integration

Containerized PCU for consistent CI/CD environments:

FROM node:18-alpine

# Install pnpm and PCU
RUN corepack enable
RUN pnpm add -g pnpm-catalog-updates

# Set working directory
WORKDIR /workspace

# Copy package files
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .pcurc.json ./

# Install dependencies
RUN pnpm install --frozen-lockfile

# Set entrypoint
ENTRYPOINT ["pcu"]
CMD ["--help"]

Enterprise Workflows

Multi-Environment Management

Manage dependencies across development, staging, and production environments:

{
  "defaults": {
    "target": "latest",
    "createBackup": true,
    "interactive": true
  },
  "ui": {
    "theme": "modern",
    "progressBarStyle": "fancy"
  },
  "packageRules": [
    {
      "patterns": ["*"],
      "target": "latest",
      "requireConfirmation": false
    }
  ]
}

Approval Workflows

Implement approval workflows for critical updates:

# Production update workflow
pcu -c --config .pcurc.production.json > updates-pending.json

# Generate approval request
pcu analyze default typescript --format json > impact-analysis.json

# After approval, apply updates
pcu -u --config .pcurc.production.json --create-backup

# Rollback if issues found
git checkout HEAD~1 -- package.json pnpm-lock.yaml
pnpm install