Rush Best Practices

---
description: A comprehensive guide for managing dependencies in Rush monorepo
globs:
alwaysApply: false
---
You are a Rush monorepo development and management expert. Your role is to assist with Rush-related tasks while following these key principles and best practices:

# 1. Core Principles

- Follow Monorepo best practices
- Adhere to Rush's project isolation principles
- Maintain clear dependency management
- Use standardized versioning and change management
- Implement efficient build processes

# 2. Project Structure and Organization

## 2.1 Standard Directory Structure

The standard directory structure for a Rush monorepo is as follows:

  ```
  /
  ├── common/ # Rush common files directory
  |   ├── autoinstallers # Autoinstaller tool configuration
  │   ├── config/ # Configuration files directory
  │   │   ├── rush/ # Rush core configuration
  │   │   │   ├── command-line.json # Command line configuration
  │   │   │   ├── build-cache.json # Build cache configuration
  │   │   │   └── subspaces.json # Subspace configuration
  │   │   └── subspaces/ # Subspace configuration
  │   │       └── <subspace-name> # Specific Subspace
  │   │           ├── pnpm-lock.yaml # Subspace dependency lock file
  │   │           ├── .pnpmfile.cjs # PNPM hook script
  │   │           ├── common-versions.json # Subspace version configuration
  │   │           ├── pnpm-config.json # PNPM configuration
  │   │           └── repo-state.json # subspace state hash value
  │   ├── scripts/ # Common scripts
  │   └── temp/ # Temporary files
  └── rush.json # Rush main configuration file
  ```

## 2.2 Important Configuration Files

1. `rush.json` (Root Directory)

   - Rush's main configuration file
   - Key configuration items:
     ```json
     {
       "rushVersion": "5.x.x",        // Rush version
       // Choose PNPM as package manager
       "pnpmVersion": "8.x.x",
       // Or use NPM
       // "npmVersion": "8.x.x",
       // Or use Yarn
       // "yarnVersion": "1.x.x",
       "projectFolderMinDepth": 1,    // Minimum project depth
       "projectFolderMaxDepth": 3,    // Maximum project depth
       "projects": [],                // Project list
       "nodeSupportedVersionRange": ">=14.15.0", // Node.js version requirement

       // Project configuration
       "projects": [
         {
           "packageName": "@scope/project-a", // Project package name
           "projectFolder": "packages/project-a", // Project path
           "shouldPublish": true, // Whether to publish
           "decoupledLocalDependencies": [], // Cyclic dependency projects
           "subspaceName": "subspaceA", // Which Subspace it belongs to
         }
       ],
     }
     ```

2. `common/config/rush/command-line.json`

   - Custom commands and parameter configuration
   - Command types:
     1. `bulk`: Batch commands, executed separately for each project
        ```json
        {
          "commandKind": "bulk",
          "name": "build",
          "summary": "Build projects",
          "enableParallelism": true,    // Whether to allow parallelism
          "ignoreMissingScript": false  // Whether to ignore missing scripts
        }
        ```
     2. `global`: Global commands, executed once for the entire repository
        ```json
        {
          "commandKind": "global",
          "name": "deploy",
          "summary": "Deploy application",
          "shellCommand": "node common/scripts/deploy.js"
        }
        ```

   - Parameter types:
     ```json
     "parameters": [
       {
         "parameterKind": "flag",      // Switch parameter --production
         "longName": "--production"
       },
       {
         "parameterKind": "string",    // String parameter --env dev
         "longName": "--env"
       },
       {
         "parameterKind": "stringList", // String list --tag a --tag b
         "longName": "--tag"
       },
       {
         "parameterKind": "choice",    // Choice parameter --locale en-us
         "longName": "--locale",
         "alternatives": ["en-us", "zh-cn"]
       },
       {
         "parameterKind": "integer",   // Integer parameter --timeout 30
         "longName": "--timeout"
       },
       {
         "parameterKind": "integerList" // Integer list --pr 1 --pr 2
         "longName": "--pr"
       }
     ]
     ```

3. `common/config/subspaces/<subspace-name>/common-versions.json`

   - Configure NPM dependency versions affecting all projects
   - Key configuration items:
     ```json
     {
       // Specify preferred versions for specific packages
       "preferredVersions": {
         "react": "17.0.2",        // Restrict react version
         "typescript": "~4.5.0"    // Restrict typescript version
       },

       // Whether to automatically add all dependencies to preferredVersions
       "implicitlyPreferredVersions": true,

       // Allow certain dependencies to use multiple different versions
       "allowedAlternativeVersions": {
         "typescript": ["~4.5.0", "~4.6.0"]
       }
     }
     ```

4. `common/config/rush/subspaces.json`
   - Purpose: Configure Rush Subspace functionality
   - Key configuration items:
     ```json
     {
       // Whether to enable Subspace functionality
       "subspacesEnabled": false,

       // Subspace name list
       "subspaceNames": ["team-a", "team-b"],
     }
     ```

# 3. Command Usage

## 3.1 Command Tool Selection

Choose the correct command tool based on different scenarios:

1. `rush` command
   - Purpose: Execute operations affecting the entire repository or multiple projects
   - Features:
     - Strict parameter validation and documentation
     - Support for global and batch commands
     - Suitable for standardized workflows
   - Use cases: Dependency installation, building, publishing, and other standard operations

2. `rushx` command
   - Purpose: Execute specific scripts for a single project
   - Features:
     - Similar to `npm run` or `pnpm run`
     - Uses Rush version selector to ensure toolchain consistency
     - Prepares shell environment based on Rush configuration
   - Use cases:
     - Running project-specific build scripts
     - Executing tests
     - Running development servers

3. `rush-pnpm` command
   - Purpose: Replace direct use of pnpm in Rush repository
   - Features:
     - Sets correct PNPM workspace context
     - Supports Rush-specific enhancements
     - Provides compatibility checks with Rush
   - Use cases: When direct PNPM commands are needed

## 3.2 Common Commands Explained

1. `rush update`
   - Function: Install and update dependencies
   - Important parameters:
     - `-p, --purge`: Clean before installation
     - `--bypass-policy`: Bypass gitPolicy rules
     - `--no-link`: Don't create project symlinks
     - `--network-concurrency COUNT`: Limit concurrent network requests
   - Use cases:
     - After first cloning repository
     - After pulling new Git changes
     - After modifying package.json
     - When dependencies need updating

2. `rush install`
   - Function: Install dependencies based on existing shrinkwrap file
   - Features:
     - Read-only operation, won't modify shrinkwrap file
     - Suitable for CI environment
   - Important parameters:
     - `-p, --purge`: Clean before installation
     - `--bypass-policy`: Bypass gitPolicy rules
     - `--no-link`: Don't create project symlinks
   - Use cases:
     - CI/CD pipeline
     - Ensuring dependency version consistency
     - Avoiding accidental shrinkwrap file updates

3. `rush build`
   - Function: Incremental project build
   - Features:
     - Only builds changed projects
     - Supports parallel building
   - Use cases:
     - Daily development builds
     - Quick change validation

4. `rush rebuild`
   - Function: Complete clean build
   - Features:
     - Builds all projects
     - Cleans previous build artifacts
   - Use cases:
     - When complete build cleaning is needed
     - When investigating build issues

5. `rush add`
   - Function: Add dependencies to project
   - Usage: `rush add -p <package> [--dev] [--exact]`
   - Important parameters:
     - `-p, --package`: Package name
     - `--dev`: Add as development dependency
     - `--exact`: Use exact version
   - Use cases: Adding new dependency packages
   - Note: Must be run in corresponding project directory

6. `rush remove`
   - Function: Remove project dependencies
   - Usage: `rush remove -p <package>`
   - Use cases: Clean up unnecessary dependencies

7. `rush purge`
   - Function: Clean temporary files and installation files
   - Use cases:
     - Clean build environment
     - Resolve dependency issues
     - Free up disk space

# 4. Dependency Management

## 4.1 Package Manager Selection

Specify in `rush.json`:
  ```json
  {
    // Choose PNPM as package manager
    "pnpmVersion": "8.x.x",
    // Or use NPM
    // "npmVersion": "8.x.x",
    // Or use Yarn
    // "yarnVersion": "1.x.x",
  }
  ```

## 4.2 Version Management

- Location: `common/config/subspaces/<subspace-name>/common-versions.json`
- Configuration example:
  ```json
  {
    // Specify preferred versions for packages
    "preferredVersions": {
      "react": "17.0.2",
      "typescript": "~4.5.0"
    },

    // Allow certain dependencies to use multiple versions
    "allowedAlternativeVersions": {
      "typescript": ["~4.5.0", "~4.6.0"]
    }
  }
  ```

## 4.3 Subspace

Using Subspace technology allows organizing related projects together, meaning multiple PNPM lock files can be used in a Rush Monorepo. Different project groups can have their own independent dependency version management without affecting each other, thus isolating projects, reducing risks from dependency updates, and significantly improving dependency installation and update speed.

Declare which Subspaces exist in `common/config/rush/subspaces.json`, and declare which Subspace each project belongs to in `rush.json`'s `subspaceName`.

# 5. Caching Capabilities

## 5.1 Cache Principles

Rush cache is a build caching system that accelerates the build process by caching project build outputs. Build results are cached in `common/temp/build-cache`, and when project source files, dependencies, environment variables, command line parameters, etc., haven't changed, the cache is directly extracted instead of rebuilding.

## 5.2 Core Configuration

Configuration file: `<project>/config/rush-project.json`

```json
{
  "operationSettings": [
    {
      "operationName": "build",   // Operation name
      "outputFolderNames": ["lib", "dist"], // Output directories
      "disableBuildCacheForOperation": false, // Whether to disable cache
      "dependsOnEnvVars": ["MY_ENVIRONMENT_VARIABLE"], // Dependent environment variables
    }
  ]
}
```

# 6. Best Practices

## 6.1 Selecting Specific Projects

When running commands like `install`, `update`, `build`, `rebuild`, etc., by default all projects under the entire repository are processed. To improve efficiency, Rush provides various project selection parameters that can be chosen based on different scenarios:

1. `--to <PROJECT>`
   - Function: Select specified project and all its dependencies
   - Use cases:
     - Build specific project and its dependencies
     - Ensure complete dependency chain build
   - Example:
     ```bash
     rush build --to @my-company/my-project
     rush build --to my-project  # If project name is unique, scope can be omitted
     rush build --to .  # Use current directory's project
     ```

2. `--to-except <PROJECT>`
   - Function: Select all dependencies of specified project, but not the project itself
   - Use cases:
     - Update project dependencies without processing project itself
     - Pre-build dependencies
   - Example:
     ```bash
     rush build --to-except @my-company/my-project
     ```

3. `--from <PROJECT>`
   - Function: Select specified project and all its downstream dependencies
   - Use cases:
     - Validate changes' impact on downstream projects
     - Build all projects affected by specific project
   - Example:
     ```bash
     rush build --from @my-company/my-project
     ```

4. `--impacted-by <PROJECT>`
   - Function: Select projects that might be affected by specified project changes, excluding dependencies
   - Use cases:
     - Quick test of project change impacts
     - Use when dependency status is already correct
   - Example:
     ```bash
     rush build --impacted-by @my-company/my-project
     ```

5. `--impacted-by-except <PROJECT>`
   - Function: Similar to `--impacted-by`, but excludes specified project itself
   - Use cases:
     - Project itself has been manually built
     - Only need to test downstream impacts
   - Example:
     ```bash
     rush build --impacted-by-except @my-company/my-project
     ```

6. `--only <PROJECT>`
   - Function: Only select specified project, completely ignore dependency relationships
   - Use cases:
     - Clearly know dependency status is correct
     - Combine with other selection parameters
   - Example:
     ```bash
     rush build --only @my-company/my-project
     rush build --impacted-by projectA --only projectB
     ```

## 6.2 Troubleshooting

1. Dependency Issue Handling
   - Avoid directly using `npm`, `pnpm`, `yarn` package managers
   - Use `rush purge` to clean all temporary files
   - Run `rush update --recheck` to force check all dependencies

2. Build Issue Handling
   - Use `rush rebuild` to skip cache and perform complete build
   - Check project's `rushx build` command output

3. Logging and Diagnostics
   - Use `--verbose` parameter for detailed logs
   - Verify command parameter correctness