rushstack-best-practices

by microsoft

Provides best practices and guidance for working with Rush monorepos. Use when the user is working in a Rush-based repository, asks about Rush commands… npx skills add https://github.com/microsoft/rushstack --skill rushstack-best-practices Download ZIPGitHub6.5k

Rushstack Best Practices

This skill provides essential best practices for working with Rush monorepos. Following these guidelines ensures efficient dependency management, optimal build performance, and proper command usage.

Important Guidelines

When encountering unclear issues or questions:

• Never make assumptions - If unsure about Rush behavior, configuration, or commands

• Search official resources first - Check documentation and existing issues before guessing

• Provide accurate information - Base responses on verified sources, not assumptions

• Ask for clarification - When the problem description is ambiguous or incomplete

Core Principles

• Always use Rush commands - Avoid npm/pnpm/yarn directly in a Rush monorepo

• Use rushx for single projects - Like npm run, but Rush-aware

• rush install vs update - install for CI, update after changes

• rush build vs rebuild - build for incremental, rebuild for clean

• Projects at 2 levels - Standard: apps/, libraries/, tools/

• Selection flags reduce scope - Use --to, --from, --impacted-by

• Build cache is automatic - Configure output folders to enable

• Subspace for large repos - Isolate dependencies when needed

Project Selection Best Practices

When running commands like install, update, build, rebuild, etc., by default all projects under the entire repository are processed. Use these selection flags to improve efficiency:

--to

Select specified project and all its dependencies.

• Build specific project and its dependencies

• Ensure complete dependency chain build

rush build --to @my-company/my-project
rush build --to my-project # If project name is unique
rush build --to . # Use current directory's project

--to-except

Select all dependencies of specified project, but not the project itself.

• Update project dependencies without processing project itself

• Pre-build dependencies

rush build --to-except @my-company/my-project

--from

Select specified project and all its downstream dependencies.

• Validate changes' impact on downstream projects

• Build all projects affected by specific project

rush build --from @my-company/my-library

--impacted-by

Select projects that might be affected by specified project changes, excluding dependencies.

• Quick test of project change impacts

• Use when dependency status is already correct

rush build --impacted-by @my-company/my-library

--impacted-by-except

Similar to --impacted-by, but excludes specified project itself.

• Project itself has been manually built

• Only need to test downstream impacts

rush build --impacted-by-except @my-company/my-library

--only

Only select specified project, completely ignore dependency relationships.

• Dependency status is known to be correct

• Combine with other selection parameters

rush build --only @my-company/my-project
rush build --impacted-by projectA --only projectB

Dependency Management

Package Manager Selection

Choose in rush.json:

{
 "pnpmVersion": "8.x.x" // Preferred - efficient, strict
 // "npmVersion": "8.x.x" // Alternative
 // "yarnVersion": "1.x.x" // Alternative
}

Version Constraints

Configure in common/config/subspaces/<subspace>/common-versions.json:

{
 "preferredVersions": {
 "react": "17.0.2",
 "typescript": "~4.5.0"
 },
 "implicitlyPreferredVersions": true,
 "allowedAlternativeVersions": {
 "typescript": ["~4.5.0", "~4.6.0"]
 }
}

Adding/Removing Dependencies

Always use Rush commands, not npm/pnpm directly:

rush add -p lodash --dev # Add dev dependency
rush add -p react --exact # Add exact version
rush remove -p lodash # Remove dependency

Subspace for Large Monorepos

What is Subspace:

• Allows multiple PNPM lock files in one Rush monorepo

• Enables independent dependency management per team/project group

• Reduces risk from dependency updates

• Improves install/update performance

When to Use:

• Large monorepos (50+ projects)

• Multiple teams with different dependency needs

• Conflicting version requirements

• Need for faster dependency operations

Official Resources

Documentation & References

Official Websites:

• RushStack.io - Main documentation site

• Rush.js.io - Rush build orchestrator documentation

• Heft.rushstack.io - Heft build tool documentation

• API Extractor - API documentation and rollups

Search Existing Issues:

• Before creating new issues, search rush-stack-builds issues

When to Search vs. Ask

Search these resources first when:

• Encountering error messages

• Unsure about configuration options

• Looking for examples or tutorials

• Need to understand Rush behavior

Ask the user for clarification when:

• The specific use case is unclear

• Multiple approaches are possible

• Context is missing to provide accurate guidance

• The issue might be environment-specific

Detailed References

For expanded information on specific domains, see:

• references/core-commands.md - Detailed command reference

• references/project-configuration.md - Configuration file specifications

• references/dependency-management.md - Advanced dependency patterns

• references/build-system.md - Build optimization and caching

• references/subspace.md - Subspace setup and usage