Configuration

Configure PCU to match your workflow and project needs. Learn about configuration files, package-specific rules, and advanced settings.

Configuration File Types

PCU supports multiple configuration file formats and locations to accommodate different development workflows.

Supported Configuration Files

PCU searches for configuration files in the following order (first found wins):

Name
.pcurc.json
Type
JSON
Description
Primary JSON configuration file in project root
Name
.pcurc.js
Type
JavaScript
Description
JavaScript configuration file with dynamic configuration support
Name
pcu.config.js
Type
JavaScript
Description
Alternative JavaScript configuration filename
Name
~/.pcurc.json
Type
JSON
Description
Global user configuration in home directory
Name
package.json
Type
JSON
Description
Configuration within package.json under "pcu" key

JavaScript Configuration Support

JavaScript configuration files enable dynamic configuration based on environment, workspace structure, or other runtime conditions:

module.exports = {
  defaults: {
    target: process.env.NODE_ENV === 'production' ? 'minor' : 'latest',
    createBackup: true,
  },
  workspace: {
    autoDiscover: true,
    catalogMode: 'strict',
  },
  // Dynamic package rules based on workspace structure
  packageRules: [
    {
      patterns: ['react*'],
      target: 'minor',
      requireConfirmation: process.env.CI !== 'true',
    },
  ],
  // Environment-specific configuration
  ...(process.env.NODE_ENV === 'development' && {
    ui: {
      theme: 'modern',
      progressBarStyle: 'fancy',
    },
  }),
};

Package.json Configuration

For simpler projects, configuration can be embedded within package.json:

{
  "name": "my-project",
  "pcu": {
    "defaults": {
      "target": "minor",
      "createBackup": true
    },
    "packageRules": [
      {
        "patterns": ["@types/*"],
        "target": "latest",
        "autoUpdate": true
      }
    ]
  }
}

Configuration Validation

PCU automatically validates configuration files and provides detailed error messages for common issues:

Validation Features

JSON Schema Validation: Ensures all configuration properties are valid
Pattern Validation: Validates glob patterns and package name formats
Type Checking: Verifies correct data types for all configuration values
Conflict Detection: Identifies conflicting rules and configuration options
Suggestion System: Provides helpful suggestions for fixing configuration errors

Validation Examples

# Validate current configuration
pcu workspace --validate

# Common validation errors with suggestions:
# ❌ Invalid target "lastest" in packageRules[0]
#    💡 Did you mean "latest"?
#
# ❌ Pattern "react+" is invalid glob syntax
#    💡 Use "react*" for matching packages starting with "react"
#
# ⚠️  Conflicting rules for package "react"
#    📝 Rule at index 0 and 2 both match this package

.pcurc.json 配置文件完整参考

PCU 使用多种配置文件格式，主要使用项目根目录下的 .pcurc.json 文件进行配置。可以手动创建，或使用 pcu init 生成默认配置。

完整配置文件结构

{
  "defaults": {
    "target": "latest",
    "timeout": 30000,
    "createBackup": false,
    "interactive": false,
    "dryRun": false,
    "force": false,
    "prerelease": false
  },
  "workspace": {
    "autoDiscover": true,
    "catalogMode": "strict",
    "path": "./",
    "packages": ["packages/*", "apps/*"]
  },
  "output": {
    "format": "table",
    "color": true,
    "verbose": false
  },
  "ui": {
    "theme": "default",
    "progressBars": true,
    "progressBarStyle": "default",
    "animations": true,
    "colorScheme": "auto"
  },
  "update": {
    "interactive": false,
    "dryRunFirst": false,
    "skipPrereleases": true,
    "confirmMajorUpdates": true,
    "batchSize": 10
  },
  "security": {
    "autoFixVulnerabilities": false,
    "allowMajorForSecurity": false,
    "notifyOnSecurityUpdate": true,
    "severityThreshold": "moderate"
  },
  "advanced": {
    "concurrency": 5,
    "timeout": 30000,
    "retries": 3,
    "cacheValidityMinutes": 60,
    "checkForUpdates": true,
    "batchSize": 50
  },
  "cache": {
    "enabled": true,
    "ttl": 3600000,
    "maxSize": 52428800,
    "maxEntries": 10000,
    "persistToDisk": true,
    "cacheDir": "~/.pcu/cache"
  },
  "registry": {
    "default": "https://registry.npmjs.org/",
    "timeout": 30000,
    "retries": 3
  },
  "include": ["*"],
  "exclude": [],
  "packageRules": [
    {
      "patterns": ["react*"],
      "target": "minor",
      "requireConfirmation": true
    }
  ],
  "notification": {
    "enabled": true,
    "updateAvailable": true,
    "securityAlerts": true
  },
  "logging": {
    "level": "info",
    "file": "./pcu.log",
    "maxFiles": 5,
    "maxSize": "10MB"
  }
}

配置选项详细说明

defaults 默认设置

Name
target
Type
enum
Description
默认更新目标: latest | greatest | minor | patch | newest
Name
timeout
Type
number
Description
网络请求超时时间（毫秒）
Name
createBackup
Type
boolean
Description
更新前是否创建备份文件
Name
interactive
Type
boolean
Description
是否默认启用交互模式
Name
dryRun
Type
boolean
Description
是否默认启用预览模式（不实际更新）
Name
force
Type
boolean
Description
是否强制更新（跳过警告）
Name
prerelease
Type
boolean
Description
是否包含预发布版本

workspace 工作空间设置

Name
autoDiscover
Type
boolean
Description
是否自动发现工作空间结构
Name
catalogMode
Type
enum
Description
目录模式: strict | loose | mixed
Name
path
Type
string
Description
工作空间根目录路径
Name
packages
Type
string[]
Description
包目录匹配模式数组（会覆盖 pnpm-workspace.yaml）

output 输出设置

Name
format
Type
enum
Description
输出格式: table | json | yaml | minimal
Name
color
Type
boolean
Description
是否启用彩色输出
Name
verbose
Type
boolean
Description
是否启用详细输出模式

ui 用户界面设置

Name
theme
Type
enum
Description
颜色主题: default | modern | minimal | neon
Name
progressBars
Type
boolean
Description
是否显示进度条
Name
progressBarStyle
Type
enum
Description
进度条样式: default | gradient | fancy | minimal | rainbow | neon
Name
animations
Type
boolean
Description
是否启用动画效果
Name
colorScheme
Type
enum
Description
颜色方案: auto | light | dark

update 更新行为设置

Name
interactive
Type
boolean
Description
更新时是否默认启用交互模式
Name
dryRunFirst
Type
boolean
Description
是否先执行预览，然后询问是否应用
Name
skipPrereleases
Type
boolean
Description
是否跳过预发布版本
Name
confirmMajorUpdates
Type
boolean
Description
主版本更新是否需要确认
Name
batchSize
Type
number
Description
批量处理的包数量

security 安全设置

Name
autoFixVulnerabilities
Type
boolean
Description
是否自动修复安全漏洞
Name
allowMajorForSecurity
Type
boolean
Description
为了安全修复是否允许主版本更新
Name
notifyOnSecurityUpdate
Type
boolean
Description
有安全更新时是否通知
Name
severityThreshold
Type
enum
Description
安全警告级别阈值: low | moderate | high | critical

advanced 高级设置

Name
concurrency
Type
number
Description
并发网络请求数量
Name
timeout
Type
number
Description
网络请求超时时间（毫秒）
Name
retries
Type
number
Description
失败重试次数
Name
cacheValidityMinutes
Type
number
Description
缓存有效期（分钟，0 表示禁用缓存）
Name
checkForUpdates
Type
boolean
Description
启动时是否检查 PCU 工具更新
Name
batchSize
Type
number
Description
批量处理的最大包数量

cache 缓存设置

Name
enabled
Type
boolean
Description
是否启用缓存系统
Name
ttl
Type
number
Description
缓存生存时间（毫秒）
Name
maxSize
Type
number
Description
最大缓存大小（字节，默认 50MB）
Name
maxEntries
Type
number
Description
最大缓存条目数
Name
persistToDisk
Type
boolean
Description
是否持久化缓存到磁盘
Name
cacheDir
Type
string
Description
缓存目录路径

registry 注册表设置

Name
default
Type
string
Description
默认 NPM 注册表 URL
Name
timeout
Type
number
Description
注册表请求超时时间（毫秒）
Name
retries
Type
number
Description
注册表请求重试次数

包过滤设置

Name
include
Type
string[]
Description
包含的包名匹配模式数组
Name
exclude
Type
string[]
Description
排除的包名匹配模式数组

notification 通知设置

Name
enabled
Type
boolean
Description
是否启用通知功能
Name
updateAvailable
Type
boolean
Description
有更新可用时是否通知
Name
securityAlerts
Type
boolean
Description
有安全警告时是否通知

logging 日志设置

Name
level
Type
enum
Description
日志级别: error | warn | info | debug | trace
Name
file
Type
string
Description
日志文件路径（可选）
Name
maxFiles
Type
number
Description
最大日志文件数量
Name
maxSize
Type
string
Description
单个日志文件最大大小

Package Filtering

Control which packages to update with include/exclude patterns and package-specific rules.

{
  "exclude": ["typescript", "@types/node", "react", "react-dom"],
  "include": ["lodash*", "chalk", "commander"]
}

Package Rule Properties

Name
patterns
Type
string[]
Description
Glob patterns to match package names
Name
target
Type
enum
Description
Update target: latest, greatest, minor, patch, newest
Name
requireConfirmation
Type
boolean
Description
Always ask before updating these packages
Name
autoUpdate
Type
boolean
Description
Update automatically without confirmation
Name
relatedPackages
Type
string[]
Description
Packages that follow the same update strategy
Name
groupUpdate
Type
boolean
Description
Update related packages together

Security Configuration

Configure security vulnerability scanning and automatic fixes.

{
  "security": {
    "autoFixVulnerabilities": true,
    "allowMajorForSecurity": true,
    "notifyOnSecurityUpdate": true
  }
}

Name
autoFixVulnerabilities
Type
boolean
Description
Automatically check and fix security vulnerabilities
Name
allowMajorForSecurity
Type
boolean
Description
Allow major version upgrades for security fixes
Name
notifyOnSecurityUpdate
Type
boolean
Description
Show notifications on security updates

Monorepo Configuration

Special settings for complex monorepo setups with multiple catalogs.

{
  "monorepo": {
    "syncVersions": ["react", "react-dom"],
    "catalogPriority": ["default", "latest", "react17"]
  }
}

Name
syncVersions
Type
string[]
Description
Packages that need version sync across multiple catalogs
Name
catalogPriority
Type
string[]
Description
Catalog priority order for conflict resolution

Advanced Settings

Fine-tune performance and behavior with advanced configuration options.

{
  "advanced": {
    "concurrency": 5,
    "timeout": 30000,
    "retries": 3,
    "cacheValidityMinutes": 60,
    "checkForUpdates": true
  }
}

Name
concurrency
Type
number
Description
Number of concurrent network requests
Name
timeout
Type
number
Description
Network request timeout in milliseconds
Name
retries
Type
number
Description
Number of retries on failure
Name
cacheValidityMinutes
Type
number
Description
Cache validity period (0 to disable caching)
Name
checkForUpdates
Type
boolean
Description
Automatically check for PCU tool updates on startup. Skipped in CI environments. Shows update notifications and installation instructions when newer versions are available.

UI Configuration

Customize the visual appearance and user interface settings.

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

Available Themes

default - Balanced colors for general use
modern - Vibrant colors for development environments
minimal - Clean and simple for production environments
neon - High contrast colors for presentations

Progress Bar Styles

PCU supports 6 different progress bar styles for enhanced visual feedback during operations:

default - Standard progress bar with basic styling
gradient - Gradient-colored progress bar for modern appearance
fancy - Enhanced progress bar with decorative elements
minimal - Clean and simple progress indicator
rainbow - Multi-colored progress bar for vibrant displays
neon - High-contrast progress bar matching neon theme

Configuration Example:

{
  "ui": {
    "theme": "modern",
    "progressBars": true,
    "progressBarStyle": "gradient"
  }
}

Command Line Usage:

pcu check --progress-style fancy
pcu update --progress-style rainbow
pcu security --progress-style neon

Configuration Priority

Configuration settings are applied in this priority order:

Command line flags (highest priority)
Package-specific rules in .pcurc.json
General settings in .pcurc.json
Default values (lowest priority)

Related packages automatically inherit settings from their parent package rules, ensuring version consistency across ecosystem packages.

Examples

React Ecosystem

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

TypeScript Project

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

Enterprise Setup

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

Environment Variables

All CLI options can be configured via environment variables for automation and CI/CD environments:

# Workspace settings
export PCU_WORKSPACE="/path/to/workspace"
export PCU_VERBOSE=true
export PCU_NO_COLOR=true

# Registry configuration
export PCU_REGISTRY="https://npm.company.com/"
export PCU_TIMEOUT=30000

# Configuration file
export PCU_CONFIG="/path/to/.pcurc.json"

Environment Variable Priority

Configuration sources are loaded in this order (later overrides earlier):

Built-in defaults (lowest priority)
Global configuration (~/.pcurc.json)
Project configuration (.pcurc.json)
Environment variables (PCU_*)
Command-line flags (highest priority)

Registry Configuration

PCU automatically reads NPM and PNPM configuration files for registry settings:

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

# Scoped registries
@mycompany:registry=https://npm.mycompany.com/
@types:registry=https://registry.npmjs.org/

# Authentication tokens
//npm.mycompany.com/:_authToken=${NPM_TOKEN}
//registry.npmjs.org/:_authToken=${NPM_PUBLIC_TOKEN}

# Legacy authentication (if needed)
//npm.mycompany.com/:username=myuser
//npm.mycompany.com/:_password=base64encodedpassword
//npm.mycompany.com/:email=user@company.com

# SSL and proxy settings
strict-ssl=true
ca=/path/to/ca.pem
proxy=http://proxy.company.com:8080
https-proxy=http://proxy.company.com:8080

Registry Priority

CLI --registry flag (highest priority)
PCU configuration (.pcurc.json registry section)
Project .npmrc/.pnpmrc
Global .npmrc/.pnpmrc
Default NPM registry (lowest priority)

Enhanced Caching Configuration

PCU includes an advanced caching system to improve performance:

{
  "cache": {
    "enabled": true,
    "ttl": 3600000,
    "maxSize": 52428800,
    "maxEntries": 10000,
    "persistToDisk": true,
    "cacheDir": "~/.pcu/cache",
    "strategy": "lru"
  }
}

Cache Settings

Name
enabled
Type
boolean
Description
Enable/disable caching system
Name
ttl
Type
number
Description
Time to live in milliseconds (1 hour default)
Name
maxSize
Type
number
Description
Maximum cache size in bytes (50MB default)
Name
maxEntries
Type
number
Description
Maximum number of cache entries
Name
persistToDisk
Type
boolean
Description
Save cache to disk between runs
Name
cacheDir
Type
string
Description
Directory for persistent cache storage
Name
strategy
Type
enum
Description
Cache eviction strategy: lru, fifo, lfu

Validation Configuration

PCU includes comprehensive validation with helpful suggestions:

{
  "validation": {
    "strict": true,
    "warnOnRiskyUpdates": true,
    "requireConfirmationFor": ["major"],
    "suggestions": {
      "enabled": true,
      "includePerformanceTips": true,
      "includeBestPractices": true
    }
  }
}

Validation Options

Name
strict
Type
boolean
Description
Enable strict validation mode with additional checks
Name
warnOnRiskyUpdates
Type
boolean
Description
Show warnings for potentially risky updates
Name
requireConfirmationFor
Type
array
Description
Update types requiring confirmation: major, minor, patch
Name
suggestions.enabled
Type
boolean
Description
Enable helpful suggestions and tips
Name
suggestions.includePerformanceTips
Type
boolean
Description
Include performance optimization suggestions
Name
suggestions.includeBestPractices
Type
boolean
Description
Include best practice recommendations

Interactive Mode Configuration

Configure interactive prompts and user experience:

{
  "interactive": {
    "enabled": true,
    "pageSize": 15,
    "showPackageDescriptions": true,
    "showReleaseNotes": false,
    "autoComplete": {
      "enabled": true,
      "fuzzyMatching": true,
      "maxSuggestions": 10
    },
    "confirmations": {
      "majorUpdates": true,
      "forceUpdates": true,
      "multiplePackages": false
    }
  }
}

Interactive Settings

Name
enabled
Type
boolean
Description
Enable interactive mode capabilities
Name
pageSize
Type
number
Description
Number of items shown per page in lists
Name
showPackageDescriptions
Type
boolean
Description
Show package descriptions in selection lists
Name
showReleaseNotes
Type
boolean
Description
Show release notes for updates (requires network)
Name
autoComplete.enabled
Type
boolean
Description
Enable auto-completion for package names
Name
autoComplete.fuzzyMatching
Type
boolean
Description
Enable fuzzy matching for auto-completion
Name
confirmations.majorUpdates
Type
boolean
Description
Require confirmation for major version updates

Monorepo Configuration

PCU provides advanced features specifically designed for large monorepos and complex workspace management.

Version Synchronization

Keep related packages synchronized across your monorepo:

{
  "monorepo": {
    "syncVersions": {
      "enabled": true,
      "groups": [
        {
          "name": "react-ecosystem",
          "packages": ["react", "react-dom", "@types/react", "@types/react-dom"],
          "strategy": "exact" // or "compatible", "latest"
        },
        {
          "name": "testing-libraries",
          "packages": ["jest", "@testing-library/*", "@types/jest"],
          "strategy": "compatible"
        }
      ]
    },
    "catalogPriority": ["default", "react17", "node18"],
    "crossWorkspaceDependencies": {
      "analyze": true,
      "enforce": "warn" // "error", "warn", "off"
    }
  }
}

Advanced Workspace Management

Catalog Priority System

Define which catalogs take precedence when conflicts arise:

{
  "catalogPriority": ["production", "default", "experimental"],
  "catalogConflictResolution": "priority" // or "interactive", "error"
}

Cross-Workspace Dependencies

Analyze and manage dependencies between workspace packages:

Name
analyze
Type
boolean
Description
Analyze cross-workspace dependencies
Name
enforce
Type
enum
Description
How to handle version mismatches: error, warn, off
Name
reportUnused
Type
boolean
Description
Report packages in catalogs not used by any workspace package
Name
validateVersions
Type
boolean
Description
Validate that all workspace packages use catalog versions

Monorepo-Specific Package Rules

Create sophisticated rules for different areas of your monorepo:

{
  "packageRules": [
    {
      "name": "Frontend packages",
      "patterns": ["react*", "@types/react*", "next*"],
      "workspacePackages": ["apps/web", "apps/admin"],
      "target": "minor",
      "groupUpdate": true,
      "requireConfirmation": true
    },
    {
      "name": "Backend dependencies",
      "patterns": ["express*", "@types/express*", "fastify*"],
      "workspacePackages": ["apps/api", "services/*"],
      "target": "patch",
      "autoUpdate": false
    },
    {
      "name": "Development tools",
      "patterns": ["eslint*", "prettier", "typescript"],
      "workspacePackages": ["*"], // All packages
      "target": "latest",
      "autoUpdate": true,
      "excludeFromProduction": true
    }
  ]
}

Workspace-Specific Configuration

Different configuration for different parts of your monorepo:

{
  "workspaceRules": {
    "apps/web": {
      "defaults": {
        "target": "minor",
        "createBackup": true
      },
      "packageRules": [
        {
          "patterns": ["react*"],
          "target": "patch"
        }
      ]
    },
    "packages/*": {
      "defaults": {
        "target": "latest",
        "requireConfirmation": false
      }
    },
    "tools/*": {
      "defaults": {
        "target": "latest",
        "autoUpdate": true
      }
    }
  }
}

Performance Optimization for Large Monorepos

Batch Processing Configuration

Name
batchSize
Type
number
Description
Number of packages to process in each batch
Name
concurrency
Type
number
Description
Maximum number of concurrent operations
Name
cacheWorkspaceStructure
Type
boolean
Description
Cache workspace package discovery between runs
Name
parallelCatalogProcessing
Type
boolean
Description
Process multiple catalogs in parallel

Memory Management

{
  "monorepo": {
    "memoryOptimization": {
      "streamingMode": true, // Process packages without loading all into memory
      "maxMemoryUsage": "2GB", // Memory limit for large workspaces
      "temporaryFileCleanup": "immediate" // "immediate", "session-end", "manual"
    }
  }
}

Monorepo Validation

Comprehensive validation for complex workspace setups:

Validation Rules

Name
enforceWorkspaceProtocol
Type
boolean
Description
Ensure workspace: protocol is used for internal dependencies
Name
validateCatalogCoverage
Type
boolean
Description
Ensure all dependencies are covered by catalogs
Name
requireConsistentVersions
Type
boolean
Description
Require all workspace packages to use the same version of shared dependencies
Name
detectCircularDependencies
Type
boolean
Description
Detect circular dependencies between workspace packages

Usage Examples for Monorepos

Large Enterprise Monorepo Setup

{
  "monorepo": {
    "syncVersions": {
      "enabled": true,
      "groups": [
        {
          "name": "core-frontend",
          "packages": ["react", "react-dom", "react-router", "@types/react*"],
          "strategy": "exact"
        },
        {
          "name": "ui-libraries",
          "packages": ["@company/design-system", "@company/components"],
          "strategy": "workspace"
        }
      ]
    },
    "performance": {
      "batchSize": 100,
      "concurrency": 20,
      "streamingMode": true
    },
    "workspaceRules": {
      "apps/*": { "target": "minor", "requireConfirmation": true },
      "packages/*": { "target": "latest", "autoUpdate": true },
      "tools/*": { "target": "latest", "autoUpdate": true }
    }
  }
}

CI/CD Optimized Configuration

{
  "monorepo": {
    "ci": {
      "parallelCatalogProcessing": true,
      "skipInteractivePrompts": true,
      "generateReport": true,
      "reportFormat": "json",
      "exitOnError": true
    },
    "validation": {
      "enforceWorkspaceProtocol": true,
      "validateCatalogCoverage": true,
      "failOnInconsistentVersions": true
    }
  }
}