or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

build.md code-quality.md documentation.md index.md monorepo.md release.md testing.md utilities.md

tile.json

Monorepo Tools

Aegir provides comprehensive monorepo management tools for executing commands across packages, aligning dependencies, and coordinating releases in multi-package repositories.

Capabilities

Execute Commands Across Packages

Run arbitrary commands across all packages in a monorepo with parallel execution and error handling.

aegir exec <command> [options]

Options:
  --bail            Stop execution on first error (default: true)
  --prefix          Prefix output with package name (default: false)  
  --concurrency     Maximum parallel executions (default: 1)

Arguments:
  command           Command to execute in each package directory

Execute Configuration

Command execution can be configured via .aegir.js or package.json:

interface ExecOptions {
  /** Stop execution on first package error */
  bail?: boolean;
  /** Prefix output with package name for identification */
  prefix?: boolean;
  /** Maximum number of parallel command executions */
  concurrency?: number;
}

Usage Examples:

# Build all packages
aegir exec "npm run build"

# Install dependencies in all packages
aegir exec "npm install"

# Run custom script with error tolerance
aegir exec "npm run custom-script" --no-bail

# Parallel execution with output prefixes
aegir exec "npm test" --concurrency 4 --prefix

# Complex commands with quotes
aegir exec "npm run build && npm run validate"

Configuration:

// .aegir.js
module.exports = {
  exec: {
    bail: false,           // Continue on errors
    prefix: true,          // Show package names
    concurrency: 2         // Run 2 packages in parallel
  }
};

Run npm Scripts Across Packages

Execute npm scripts across all monorepo packages with script detection and execution control.

aegir run <script> [options]

Options:
  --bail            Stop execution on first error (default: true)
  --prefix          Prefix output with package name (default: false)
  --concurrency     Maximum parallel executions (default: 1)

Arguments:
  script            npm script name to run in each package

Run Script Configuration

interface RunOptions {
  /** Stop execution on first package error */
  bail?: boolean;
  /** Prefix output with package name for identification */
  prefix?: boolean;
  /** Maximum number of parallel script executions */
  concurrency?: number;
}

Usage Examples:

# Run tests in all packages
aegir run test

# Build with parallel execution
aegir run build --concurrency 3

# Lint with error tolerance and prefixes
aegir run lint --no-bail --prefix

# Run custom scripts
aegir run prepare
aegir run "custom:script"

Script Detection:

# Script execution logic:
# 1. Discovers all packages with package.json files
# 2. Checks if specified script exists in each package
# 3. Skips packages without the target script
# 4. Executes script only in packages that define it
# 5. Aggregates results and reports summary

Dependency Version Alignment

Align dependency versions across all packages in a monorepo for consistency and compatibility.

aegir align-versions [options]

Options:
  --siblingDepUpdateMessage, -m    The commit message to use when updating sibling dependencies (string)
  --siblingDepUpdateName          The user name to use when updating sibling dependencies (string)  
  --siblingDepUpdateEmail         The email to use when updating sibling dependencies (string)

# Alignment features:
# - Scans all package.json files in monorepo
# - Identifies version mismatches for shared dependencies
# - Updates all packages to use consistent versions
# - Supports both dependencies and devDependencies
# - Preserves version range prefixes (^, ~, >=, etc.)
# - Creates alignment report with changes made
# - Commits changes with customizable git configuration

Alignment Process:

# Version alignment steps:
# 1. Discover all packages in monorepo
# 2. Extract dependency lists from each package.json
# 3. Identify shared dependencies with version conflicts
# 4. Determine target version (usually highest semantic version)
# 5. Update all package.json files with aligned versions
# 6. Report changes and potential issues

Align Versions Configuration

Configure version alignment behavior and git commit settings:

interface AlignVersionsOptions {
  /** The commit message to use when updating sibling dependencies */
  siblingDepUpdateMessage?: string;
  /** The user name to use when updating sibling dependencies */
  siblingDepUpdateName?: string;
  /** The email to use when updating sibling dependencies */
  siblingDepUpdateEmail?: string;
}

Usage Examples:

# Align all dependency versions with defaults
aegir align-versions

# Align with custom commit message and author
aegir align-versions \
  --siblingDepUpdateMessage "chore: align dependency versions" \
  --siblingDepUpdateName "Release Bot" \
  --siblingDepUpdateEmail "bot@example.com"

# Use short flag for commit message
aegir align-versions -m "chore: update dependencies"

Example Output:

Aligning dependency versions across packages...

Found version mismatches:
- lodash: ^4.17.15 (package-a) vs ^4.17.21 (package-b) -> ^4.17.21
- typescript: ~4.8.0 (package-a) vs ~4.9.0 (package-b) -> ~4.9.0

Updated 2 packages:
✓ packages/package-a/package.json
✓ packages/package-b/package.json

Alignment complete!

Test Dependent Packages

Run tests for packages that depend on changed packages, optimizing CI/CD workflows.

aegir test-dependant [repo] [options]

Options:
  --repo          The dependant module's repo URL (string)
  --branch        A branch to use from the dependant repo (string)
  --moduleName    Module name for dependency resolution (string)
  --deps          Other dependencies to override, e.g. --deps=foo@1.5.0,bar@2.4.1 (string)
  --scriptName    The script name to run (default: "test")

# Dependency testing features:
# - Tests dependent packages with updated dependencies
# - Allows overriding specific dependency versions
# - Supports custom branch selection
# - Validates compatibility across dependency changes

Test Dependant Configuration

Test dependant packages with custom configurations and dependency overrides:

interface TestDependantOptions {
  /** The dependant module's repo URL */
  repo?: string;
  /** Branch to use from the dependant repo */
  branch?: string;
  /** Module name for dependency resolution */
  moduleName?: string;
  /** Dependencies to override (format: name@version,name2@version2) */
  deps?: Record<string, string>;
  /** Script name to run in the dependent package */
  scriptName?: string;
}

Usage Examples:

# Test with default settings
aegir test-dependant

# Test specific dependent repository
aegir test-dependant https://github.com/user/dependent-package.git

# Test with custom branch and dependencies
aegir test-dependant --repo https://github.com/user/dependent-package.git \
  --branch feature-branch \
  --deps lodash@4.17.21,axios@0.24.0

# Test with custom script
aegir test-dependant --scriptName "test:integration"

# Override multiple dependencies
aegir test-dependant --deps "@types/node@18.0.0,typescript@4.9.0"

Monorepo Package Discovery

Automatic package discovery across monorepo structures:

# Package discovery logic:
# 1. Searches for package.json files in subdirectories
# 2. Excludes node_modules and common ignore patterns
# 3. Supports nested package structures
# 4. Handles workspace configurations (npm, yarn, pnpm)
# 5. Respects .gitignore and .aegirignore patterns

Supported Monorepo Structures:

# Flat structure
packages/
├── package-a/package.json
├── package-b/package.json
└── package-c/package.json

# Nested structure  
apps/
├── web-app/package.json
└── mobile-app/package.json
libs/
├── core/package.json
└── utils/package.json

# Mixed structure
packages/
├── @scope/package-a/package.json
├── independent-package/package.json
└── tools/
    ├── build-tool/package.json
    └── dev-tool/package.json

Workspace Integration

Integration with package manager workspace features:

// package.json (root)
{
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

// npm workspace integration
// yarn workspace integration  
// pnpm workspace integration

Parallel Execution Control

Sophisticated parallel execution with resource management:

// Concurrency features:
// - Configurable parallel execution limits
// - Resource-aware scheduling
// - Error propagation and handling
// - Progress reporting
// - Output synchronization and prefixing

Execution Patterns:

# Sequential execution (safe, slow)
aegir exec "npm test" --concurrency 1

# Moderate parallelism (balanced)
aegir exec "npm build" --concurrency 2

# High parallelism (fast, resource-intensive)
aegir exec "npm run lint" --concurrency 4

# Unlimited parallelism (use with caution)
aegir exec "npm install" --concurrency 0

Error Handling Strategies

Multiple error handling approaches for different scenarios:

# Fail-fast strategy (--bail, default)
# - Stops execution on first package error
# - Provides quick feedback for critical issues
# - Suitable for CI/CD pipelines

# Error-tolerant strategy (--no-bail) 
# - Continues execution despite package errors
# - Collects all errors for comprehensive reporting
# - Suitable for maintenance tasks and bulk operations

Output Management

Comprehensive output handling for monorepo operations:

# Output features:
# - Package name prefixing (--prefix)
# - Color-coded output by package
# - Progress indicators for long-running operations
# - Summary reporting with success/failure counts
# - Error aggregation and detailed reporting

Output Examples:

# Without prefixes
Running npm test...
✓ All tests passed
✓ Coverage: 95%

# With prefixes  
[package-a] Running npm test...
[package-a] ✓ All tests passed
[package-b] Running npm test...  
[package-b] ✓ All tests passed

Summary: 2/2 packages succeeded

Integration with Release Management

Monorepo tools integrate with aegir's release management:

# Release integration:
# - Coordinate version bumps across packages
# - Update cross-package dependencies
# - Manage release ordering based on dependency graph
# - Support selective package releases
# - Handle workspace publishing workflows

Best Practices for Monorepos

Recommended patterns for monorepo management:

# Dependency alignment
aegir align-versions

# Pre-commit quality checks
aegir exec "npm run lint"
aegir exec "npm run test"

# Build coordination
aegir run build --concurrency 2

# Release preparation
aegir exec "npm run build"
aegir run test
aegir align-versions

# Selective testing based on changes
aegir test-dependant

Version

Tile

Files

monorepo.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Monorepo Tools

Capabilities

Execute Commands Across Packages

Execute Configuration

Run npm Scripts Across Packages

Run Script Configuration

Dependency Version Alignment

Align Versions Configuration

Test Dependent Packages

Test Dependant Configuration

Monorepo Package Discovery

Workspace Integration

Parallel Execution Control

Error Handling Strategies

Output Management

Integration with Release Management

Best Practices for Monorepos

monorepo.mddocs/