Rush - Microsoft's Monorepo Build Tool

Currently viewing the human version

What is Rush?

Rush is Microsoft's answer to monorepo hell. If you've ever tried managing 200+ packages in one repo with npm workspaces, you know the pain - phantom dependencies, inconsistent installs, builds that work on your machine but break in CI. Microsoft built Rush because their massive repos were driving developers insane.

Rush monorepo concept diagram

Current version is solid with PNPM, though I ran into some nasty CI crashes with Rush 5.131.x that took me a week to debug - turned out to be a config file caching issue, not the code I thought was broken. Microsoft uses it for OneDrive, SharePoint, and other massive products with hundreds of packages, but they also have unlimited DevOps budgets.

Core Architecture

Rush fixes three massive monorepo headaches:

Dependency Hell: PNPM prevents the nightmare where packages accidentally import dependencies they didn't declare. No more "works on my machine" because someone forgot to add express to package.json but it was available through a transitive dependency. PNPM hard-links everything so each package only sees what it actually declares. Fair warning - this will break half your existing npm scripts that assume flat node_modules. I spent 2 days fixing our test runner because it couldn't find jest configs in the wrong directory structure.

PNPM Package Manager

Build Coordination: Rush doesn't replace your build tools - it runs them in the right order. It figures out which packages changed, builds dependencies first, and parallelizes everything that can run simultaneously. Our builds went from like 40-something minutes to maybe 10-15 minutes for typical changes, but full rebuilds still take forever and incremental builds can be flaky if you change shared utilities.

Policy Enforcement: Rush stops developers from breaking stuff accidentally. It enforces consistent dependency versions (no more "why does package A use React 17 but package B uses React 18?"), requires changelogs for releases, and validates your entire dependency graph.

Real-World Adoption

Microsoft eats its own dog food - they use Rush for their biggest products:

OneDrive: 300+ packages for web client and sync apps
SharePoint: Web framework with hundreds of interdependent packages
Office 365: Admin tools and web applications
Windows Store: Commerce platform spanning multiple teams

Though honestly, Microsoft can afford to have dedicated build engineers tweaking this stuff full-time.

These aren't toy examples - we're talking 100-500+ packages each with thousands of dependencies. The rushstack repo itself has over 200 packages and builds fine. If it works for Microsoft's largest properties, it'll probably work for your 50-package monorepo.

Monorepo Architecture Concept

Technical Foundation

You need Node.js LTS - stick to Node 18 LTS. I've had better luck with it than Node 20, which gave me some annoying symlink headaches, though that might just be our specific setup being picky. Installation takes 30 seconds:

npm install -g @microsoft/rush

Windows users: good luck, you'll hit PATH length limits with the deep node_modules nesting. Windows 10 has a 260-character limit that PNPM's symlinks will blow past. Enable long paths in group policy or prepare for "ENOENT" errors that make no sense.

The "integrates seamlessly" part is bullshit though. Expect to spend a weekend rewriting your CI scripts, package.json files, and build processes. Rush config lives in JSON files that you'll curse at for the first month until you understand the dependency graph syntax. Budget 3 days for initial setup, not the "few hours" they claim in the docs. I spent 6 hours just getting PNPM to not break our Jest configs.

Rush plays nice with old projects but you'll probably want to modernize your build setup anyway. The config files are declarative JSON that goes in version control - at least you can review changes to your build system instead of wondering why CI suddenly broke.

Anyway, here's how it stacks up against other monorepo tools.

Rush vs Other Monorepo Tools

Tool	Overview	Pros	Cons	Best Use Case
Turborepo	Just fucking use this if you want something that works. Setup takes 5 minutes, caching works out of the box, and you won't hate your life.	Setup takes 5 minutes, caching works out of the box, least painful option.	Vercel owns it so they might enshittify it later.	General use, quick setup, <50 packages.
Nx	Feature overload disguised as helpful tooling. Great if you love configuration hell and want to spend 3 days setting up code generators. The caching is solid once you fight through the workspace configuration maze.	Solid caching (once configured), all the bells and whistles, good for SPAs.	Feature overload, configuration hell, takes 3 days to set up code generators.	Building a SPA, needing all the bells and whistles, if you love configuration.
Rush	Microsoft's answer to their own internal monorepo hell. Complicated as shit but actually works reliably once you get it configured. PNPM integration prevents phantom dependencies which will save your ass in production.	Works reliably (once configured), PNPM integration prevents phantom dependencies, bulletproof build reproducibility.	Complicated as shit, overkill for most teams, long setup time, requires a dedicated build engineer, Microsoft-level build complexity.	100+ packages, phantom dependencies breaking production, team already uses Microsoft Kool-Aid (TypeScript, VSCode, Azure), PNPM's strict dependency isolation is worth rewriting half your npm scripts, need bulletproof build reproducibility, someone else is paying for your DevOps engineer's therapy sessions.
Lerna	Don't. Just don't. It's basically dead and was never great to begin with.		Basically dead, was never great to begin with.	Migrate to literally anything else.
Bazel	Google's build system that requires a PhD to configure.	Hermetic builds (technically impressive).	Requires a PhD to configure, spend 6 months just understanding the BUILD file syntax.	Only use this if you work at Google or want to feel like you do.

Key Features and Implementation

Phantom Dependency Elimination

Phantom dependencies are the bane of monorepo existence. You import something that works locally because it's a transitive dependency of something else, but then production explodes with "Cannot resolve module 'lodash'" because you never actually declared it. NPM doppelgangers are just as bad - multiple versions of the same package in different places.

Rush fixes this nightmare through PNPM hard-linking. Each package only sees what it explicitly declares in package.json. No more mystery imports, no more "why did CI pass but prod failed?" debugging sessions. I've seen this save teams from 3am production incidents where someone imported a transitive dependency that got removed in an upstream update.

The Lockfile Explorer is clutch for debugging when dependencies conflict. Instead of staring at yarn.lock and trying to figure out why package X version 1.2.3 got selected instead of 1.2.4, you get a visual graph. Still takes time to understand, but beats the alternative.

Build Performance and Caching

CI/CD Pipeline Architecture

Rush's build performance is actually decent once you get it working:

Incremental Builds: Rush figures out what changed and only rebuilds affected packages. Change one line in a leaf package? Only that package rebuilds. Change a shared utility? Everything that depends on it rebuilds, but in the right order. Saves you from the 45-minute "rebuild everything" dance.

Parallel Execution: Rush maxes out your CPU cores building independent packages simultaneously. It's smart about dependency order - package A builds before package B if B depends on A, but packages C and D build in parallel if they're independent. Your 8-core machine actually gets used.

Distributed Caching: This is where Rush shines when it works. Cache build outputs to Azure Storage, AWS S3, or whatever. Developer A builds package X, developer B pulls the cached result instead of rebuilding. Works great until someone forgets to configure cache keys properly and everyone gets stale builds. Fair warning - the cache invalidation is still black magic. We've had builds pass with cached results that were actually broken. The cache key generation is supposedly better now but I still don't trust it completely - burned too many times.

Distributed Build Cache Architecture

Repository Policies and Governance

Rush prevents your team from accidentally breaking everything:

Dependency Management: Rush enforces consistent versions across packages. No more "why does package A use React 17 while package B uses React 18?" The rush check command catches version conflicts before they hit production. Your bundle sizes stay sane because you're not shipping three versions of the same library.

Change Management: Rush forces you to write changelogs before publishing packages. Sounds annoying, but it saves your ass when a breaking change breaks production and you need to figure out what changed. No more "oops, I didn't know that was a breaking change" incidents.

Custom Commands: Define repository-wide commands like rush lint or rush test:unit that run consistently everywhere. Rush only runs them on packages that actually changed, so you're not waiting 20 minutes for eslint to run on unchanged code. Makes CI pipelines actually usable.

Integration with Development Workflows

Rush plays reasonably well with your existing workflow:

Git Integration: Rush analyzes git diffs to figure out what changed and only tests affected packages. Instead of running the entire test suite on every commit, you test just the packages that actually changed. Our CI went from about 35-40 minutes to maybe 12-15 minutes for most changes, but merge commits still trigger full rebuilds and can take over an hour.

IDE Support: The Rush Stack VSCode Extension adds some useful monorepo navigation. You can run commands on specific packages without memorizing CLI arguments. It's not revolutionary but saves clicking around.

CI/CD Integration: Rush makes CI pipelines actually sane. Deterministic builds mean the same inputs produce the same outputs every time. Change detection means you only deploy packages that actually changed. Still requires some CI configuration voodoo, but at least the foundation is solid.

CI/CD Pipeline with Rush

Anyway, you probably have questions about the shit that actually breaks when using Rush.

Frequently Asked Questions

Does this actually work or is it just Microsoft marketing?

It works, but setup is hell. Budget a weekend for configuration and another week fixing scripts that break with PNPM. Worth it if you have 100+ packages, overkill for smaller repos.

My builds keep failing with "cannot resolve module" errors. What's wrong?

Phantom dependencies. Your packages are importing stuff they don't declare in package.json. PNPM enforces strict isolation so imports that worked accidentally now fail. Add the missing dependencies or use npm ls to find what's actually available.

Should I use PNPM or stick with npm/yarn?

Use PNPM. That's the whole point of Rush. Using npm/yarn with Rush is like buying a sports car to drive in first gear

technically works but you're missing the benefit.

How long does migration actually take?

Depends on how fucked your current setup is. 3-5 days if you're lucky and already use TypeScript. 2+ weeks if you have weird npm scripts and custom build tools. The official docs claim "a few hours" which is complete bullshit

they're living in fantasy land.

Rush vs Lerna?

Lerna is dead, don't use it. Migration from Lerna to Rush takes a weekend and you'll rewrite your CI, but at least your builds will be deterministic instead of randomly breaking.

What Node version should I use?

Stick to Node 18 LTS. Node 20 works but I've seen some weird symlink behavior that took hours to debug

might just be our specific setup, but Node 18 is rock solid. Node 19 is cursed, obviously.

Can I use Rush with other languages besides JavaScript?

No. Rush is JavaScript/TypeScript only. Use Bazel if you hate yourself, or separate repos if you have any sense.

Why do my Windows builds keep breaking?

Windows PATH length limits. PNPM's deep symlinks hit the 260-character limit. Enable long paths in group policy: gpedit.msc → Computer Configuration → Administrative Templates → System → Filesystem → Enable Win32 long paths. Or just switch to WSL2 and save yourself the headache.

Does CI actually get faster?

Yes, but not as much as they claim. Our builds went from ~40 minutes to ~15 minutes for typical changes. Full rebuilds still suck.

What's Rush Stack?

Microsoft's full build ecosystem. You can use just Rush or go all-in with their webpack replacement, linting rules, etc. All-or-nothing approach.

How big can a Rush repo get?

Microsoft uses hundreds of packages but that doesn't mean you should. Sweet spot is 50-200 packages. Beyond that you need dedicated build engineers and unlimited CI budget.

Does build caching actually work?

Yes, when configured properly. Works with S3, Azure Storage, etc. Developer A builds, developer B gets cached results. But cache invalidation is hard and we've had production incidents from stale cached builds.

What breaks when migrating to Rush?

Everything. Budget a weekend minimum:

All your npm scripts (PNPM symlinks break assumptions)
CI pipeline (needs complete rewrite)
Build tools that assume flat node_modules
Developers' sanity (first month is rough)

What are Rush's biggest problems?

Setup complexity, PNPM lock-in, JavaScript-only, documentation written for Microsoft engineers. If you have <50 packages, just use Turborepo and save yourself the pain.