rushstack Documentation

1. Project Overview & Quickstart (microsoft/rushstack)

File: apps/trace-import/README.md

@rushstack/trace-import

🚨 EARLY PREVIEW RELEASE 🚨

Not all features are implemented yet. To provide suggestions, please
create a GitHub issue.
If you have questions, see the Rush Stack Help page
for support resources.

The trace-import command line tool helps you:

Analyze import/require() statements to understand why they aren't resolving correctly
Understand the relationships between package folders in your node_modules tree
Ensure that package.json files correctly export their .js and .d.ts entry points

Usage

It's recommended to install this package globally:

text

# Install the NPM package
npm install -g @rushstack/trace-import

# View the command-line help
trace-import --help

Command line

text

usage: trace-import [-h] [-d] -p IMPORT_PATH [-b FOLDER_PATH] [-t {cjs,es,ts}]

This tool analyzes import module paths, to determine the resolved target
folder. For example, if the "semver" NPM package is installed, "trace-import
--path semver/index" will print output equivalent to the Node.js require.
resolve() API. If "@types/semver" is installed, then "trace-import
--resolution-type ts --path semver/index" will print the .d.ts file path that
would be resolved by a TypeScript import statement.

Optional arguments:
  -h, --help            Show this help message and exit.
  -d, --debug           Show the full call stack if an error occurs while
                        executing the tool
  -p IMPORT_PATH, --path IMPORT_PATH
                        The import module path to be analyzed. For example,
                        "example" in expressions such as: require("example");
                        require.resolve("example"); import { Thing } from
                        "example";
  -b FOLDER_PATH, --base-folder FOLDER_PATH
                        The "--path" string will be resolved as if the import
                        statement appeared in a script located in this folder.
                         If omitted, the current working directory is used.
  -t {cjs,es,ts}, --resolution-type {cjs,es,ts}
                        The type of module resolution to perform: "cjs" for
                        CommonJS, "es" for ES modules, or "ts" for TypeScript
                        typings. The default value is "cjs".

Sample outputs

These commands were invoked in the C:\Git\rushstack\apps\trace-import folder
where trace-import is developed.

Resolving a CommonJS main index

text

trace-import --path semver

Sample output:

text

Base folder:             C:\Git\rushstack\apps\trace-import
Package name:            semver
Package subpath:         (not specified)

Resolving...

Package folder:          C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\semver
package.json:            semver (7.3.8)
Main index:              "main": "index.js"

Target path:             C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\semver\index.js

Resolving a CommonJS package subpath

text

trace-import --path typescript/bin/tsc

Sample output:

text

Base folder:             C:\Git\rushstack\apps\trace-import
Package name:            typescript
Package subpath:         bin/tsc

Resolving...

Package folder:          C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\typescript
package.json:            typescript (4.8.4)

Target path:             C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\typescript\bin\tsc

Resolving a TypeScript declaration

text

trace-import --resolution-type ts --path semver

Sample output:

text

Base folder:             C:\Git\rushstack\apps\trace-import
Package name:            semver
Package subpath:         (not specified)

Resolving...

Package folder:          C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\semver
package.json:            semver (7.3.8)
@types folder:           C:\Git\rushstack\common\temp\node_modules\.pnpm\@[email protected]\node_modules\@types\semver
@types package.json:     @types/semver (7.3.5)
@types main index:       "types": "index.d.ts"

Target path:             C:\Git\rushstack\common\temp\node_modules\.pnpm\@[email protected]\node_modules\@types\semver\index.d.ts

Resolving a relative path

text

trace-import --path ./config/rig.json

Sample output:

text

Base folder:             C:\Git\rushstack\apps\trace-import
Import path:             ./config/rig.json

The import path does not appear to reference an NPM package.
Resolving...

Target path:             C:\Git\rushstack\apps\trace-import\config\rig.json

File: apps/rush-mcp-server/README.md

@rushstack/mcp-server

With the rapid advancement of LLMs, AI applications like Trae, Cursor, Cline, Windsurf, and others have been thriving. However, due to the large scale of monorepos and the context limitations of LLMs, it’s difficult for these models to fully understand your monorepo. This is where @rushstack/mcp-server comes in - by providing a suite of MCP tools, it enables LLMs to better comprehend your monorepo and assist you more effectively with daily development tasks in a Rush-based monorepo environment.

Usage

To get the best results, copy the .cursor directory into the root of your project.
Configure @rushstack/mcp-server in your AI application

text

{
  "mcpServers": {
    "rush": {
      "command": "npx",
      "args": ["-y", "@rushstack/mcp-server", "your-project-path"]
    }
  }
}

Congratulations 🎉 You’ve completed the setup - Rush MCP is now ready to use!

Available Tools

rush_docs: Retrieves relevant documentation sections based on your queries
rush_workspace_details: Retrieve detailed workspace information
rush_project_details: Get detailed information about a specific project
rush_command_validator: Validate whether commands are compliant and follow best practices
rush_migrate_project: Migrate a project from one directory to another or into a different subspace
rush_pnpm_lock_file_conflict_resolver: Resolve pnpm-lock.yaml conflicts

File: apps/rush/README.md

@microsoft/rush

https://rushjs.io

Rush makes life easier for JavaScript developers who build and publish many NPM packages at once. If you're looking to consolidate all your projects into a single repo, you came to the right place! Rush is a fast, professional solution for managing this scenario. It gives you:

A single NPM install: In one step, Rush installs all the dependencies for all your projects into a common folder. This is not just a "package.json" file at the root of your repo (which might set you up to accidentally require() a sibling's dependencies). Instead, Rush uses symlinks to reconstruct an accurate "node_modules" folder for each project, without any of the limitations or glitches that seem to plague other approaches.

⏵ This algorithm supports the PNPM, NPM, and Yarn package managers.
Automatic local linking: Inside a Rush repo, all your projects are automatically symlinked to each other. When you make a change, you can see the downstream effects without publishing anything, and without any npm link headaches. If you don't want certain projects to get linked, that's supported, too.
Fast builds: Rush detects your dependency graph and builds your projects in the right order. If two packages don't directly depend on each other, Rush parallelizes their build as separate Node.js processes (and shows live console output in a readable order). In practice this multi-process approach can yield more significant speedups than all those async functions in your single-threaded Gulpfile.
Subset and incremental builds: If you only plan to work with a few projects from your repo, rush rebuild --to does a clean build of just your upstream dependencies. After you make changes, rush rebuild --from does a clean build of only the affected downstream projects. And if your toolchain is package-deps-hash enabled, rush build delivers a powerful cross-project incremental build (that also supports subset builds).
Cyclic dependencies: If you have hammers that build hammer-factory-factories, Rush has you covered! When a package indirectly depends on an older version of itself, projects in the cycle use the last published version, whereas other projects still get the latest bits.
Bulk publishing: When it's time to do a release, Rush can detect which packages have changes, automatically bump all the appropriate version numbers, and run npm publish in each folder. If you like, configure your server to automatically run rush publish every hour.
Changelog tracking: Whenever a PR is created, you can require developers to provide a major/minor/patch log entry for the affected projects. During publishing, these changes will be automatically aggregated into a nicely formatted CHANGELOG.md file.
Enterprise policies: Want to review new libraries before developers add them to package.json, but avoid hassling people about already approved cases? Want to enforce that all your projects depend on the same library version numbers? Are unprofessional personal e-mail addresses accidentally showing up in your company's Git history? Rush can help maintain a consistent ecosystem when you've got many developers and many projects in the mix.
Lots more! Rush was created by the platform team for Microsoft SharePoint. We build hundreds of production NPM packages every day, from internal and public Git repositories, for third party SDKs and live services with millions of users. If there's an important package management problem that needs solvin', it's likely to end up as a feature for Rush.

3 Minute Demo

See Rush in action! From your shell, install the tool like this:

text

$ npm install -g @microsoft/rush

For command-line help, do this:

text

$ rush -h

To see Rush build some real projects, try running these commands: :-)

text

$ git clone https://github.com/microsoft/rushstack
$ cd rushstack
$ rush install
$ rush install  # <-- instantaneous!
$ rush rebuild
$ rush build    # <-- instantaneous!

(If you don't have a GitHub account set up, you can use rush install --bypass-policy.)

Getting Started

For more details and support resources, please visit: https://rushjs.io

The repository also includes an
experimental Rush reporter opt-in and demo guide. Rush 5 retains legacy
terminal output unless a reporter is explicitly enabled.

File: apps/rundown/README.md

@rushstack/rundown

Slow startup times for Node.js commands or services? Rundown can invoke a Node.js process and:

View imported files: Intercept all require() calls and show which paths were loaded.
Find culprits: Show the chain for require() calls for each import, explaining why it was imported.
Detect regressions over time: Generate a concise "snapshot" report that can be committed to Git. Changes
to this file may indicate potential performance regressions.

Installation

You can install this tool globally:

shell

$ npm install --global @rushstack/rundown

# View command line help
$ rundown --help

If you will generate rundown snapshots during your build, it is recommended to install via devDependencies:

shell

$ cd my-tool
$ npm install @rushstack/rundown --save-dev

Viewing imported files

Suppose you maintain a small NPM project that is invoked as follows:

shell

# The folder where your tool is developed
$ cd my-tool

# When you invoke "my-tool --my-option 123 --verbose" from the shell, let's suppose that it invokes
# this Node.js command:
$ node lib/start.js --my-option 123 --verbose

And suppose that your tool's startup time is rather slow, because the code calls require() to load many different
NPM packages. We can create a report to see all the imports:

shell

# We use "--args" to pass the command-line arguments for "my-tool"
$ rundown inspect --script lib/start.js --args="--my-option 123 --verbose"

The report may look like this:

rundown-inspect.log

text

/path/to/my-tool/lib/start.js
/path/to/my-tool/node_modules/at-least-node/index.js
/path/to/my-tool/node_modules/fs-extra/lib/copy-sync/copy-sync.js
/path/to/my-tool/node_modules/fs-extra/lib/copy-sync/index.js
/path/to/my-tool/node_modules/fs-extra/lib/copy/copy.js
/path/to/my-tool/node_modules/fs-extra/lib/copy/index.js
/path/to/my-tool/node_modules/fs-extra/lib/empty/index.js
/path/to/my-tool/node_modules/fs-extra/lib/ensure/file.js
/path/to/my-tool/node_modules/fs-extra/lib/ensure/index.js
/path/to/my-tool/node_modules/fs-extra/lib/ensure/link.js
/path/to/my-tool/node_modules/fs-extra/lib/ensure/symlink-paths.js
/path/to/my-tool/node_modules/fs-extra/lib/ensure/symlink-type.js
/path/to/my-tool/node_modules/fs-extra/lib/ensure/symlink.js
/path/to/my-tool/node_modules/fs-extra/lib/fs/index.js
/path/to/my-tool/node_modules/fs-extra/lib/index.js
/path/to/my-tool/node_modules/fs-extra/lib/json/jsonfile.js
/path/to/my-tool/node_modules/fs-extra/lib/json/output-json-sync.js
/path/to/my-tool/node_modules/fs-extra/lib/json/output-json.js
/path/to/my-tool/node_modules/fs-extra/lib/mkdirs/index.js
/path/to/my-tool/node_modules/fs-extra/lib/mkdirs/make-dir.js
/path/to/my-tool/node_modules/fs-extra/lib/move-sync/index.js
/path/to/my-tool/node_modules/fs-extra/lib/move-sync/move-sync.js
/path/to/my-tool/node_modules/fs-extra/lib/move/index.js
/path/to/my-tool/node_modules/fs-extra/lib/move/move.js
/path/to/my-tool/node_modules/fs-extra/lib/output/index.js
/path/to/my-tool/node_modules/fs-extra/lib/path-exists/index.js
/path/to/my-tool/node_modules/fs-extra/lib/remove/index.js
/path/to/my-tool/node_modules/fs-extra/lib/remove/rimraf.js
/path/to/my-tool/node_modules/fs-extra/lib/util/stat.js
/path/to/my-tool/node_modules/fs-extra/lib/util/utimes.js
/path/to/my-tool/node_modules/graceful-fs/clone.js
/path/to/my-tool/node_modules/graceful-fs/graceful-fs.js
/path/to/my-tool/node_modules/graceful-fs/legacy-streams.js
/path/to/my-tool/node_modules/graceful-fs/polyfills.js
/path/to/my-tool/node_modules/jsonfile/index.js
/path/to/my-tool/node_modules/jsonfile/utils.js
/path/to/my-tool/node_modules/universalify/index.js

Finding callers

To see how each file is imported, you can add the --trace-imports switch.

shell

# We use "--args" to pass the command-line arguments for "my-tool"
$ rundown inspect --script lib/start.js --args="--my-option 123 --verbose" --trace-imports

The report now shows more detail:

rundown-inspect.log

text

. . .
/path/to/my-tool/node_modules/graceful-fs/legacy-streams.js
  imported by /path/to/my-tool/node_modules/graceful-fs/graceful-fs.js
  imported by /path/to/my-tool/node_modules/fs-extra/lib/fs/index.js
  imported by /path/to/my-tool/node_modules/fs-extra/lib/index.js
  imported by /path/to/my-tool/lib/start.js
  imported by /rundown/lib/launcher.js

/path/to/my-tool/node_modules/graceful-fs/polyfills.js
  imported by /path/to/my-tool/node_modules/graceful-fs/graceful-fs.js
  imported by /path/to/my-tool/node_modules/fs-extra/lib/fs/index.js
  imported by /path/to/my-tool/node_modules/fs-extra/lib/index.js
  imported by /path/to/my-tool/lib/start.js
  imported by rundown/lib/launcher.js
. . .

Fixing problems

It may be the case that many of these imports are not actually used. You can avoid preloading them
by converting them to lazy imports using the Import.lazy() from
@rushstack/node-core-library
or import-lazy.

Generating a snapshot

To detect future regressions, use the rundown snapshot command to write a snapshot file:

shell

# We use "--args" to pass the command-line arguments for "my-tool"
$ rundown snapshot --script lib/start.js --args="--my-option 123 --verbose"

# This file can be committed to Git to track regressions
$ git add rundown-snapshot.log

The snapshot file format eliminates spurious diffs, by showing only the names of the imported packages.
For local projects in a monorepo, it will show relative paths. Example output:

rundown-snapshot.log

text

../path/to/monorepo-sibling
at-least-node
fs-extra
graceful-fs
jsonfile
universalify

Command-line reference

text

usage: rundown [-h] <command> ...

Detect load time regressions by running an app, tracing require() calls, and
generating a deterministic report

Positional arguments:
  <command>
    snapshot  Invoke a Node.js script and generate a test snapshot
    inspect   Invoke a Node.js script and generate detailed diagnostic output

Optional arguments:
  -h, --help  Show this help message and exit.

For detailed help about a specific command, use: rundown <command> -h

text

usage: rundown snapshot [-h] -s PATH [-a STRING] [-q] [-i]

Invoke a Node.js script and generate a test snapshot. This command creates a
concise report that can be added to Git, so that its diff can be used to
detect performance regressions

Optional arguments:
  -h, --help            Show this help message and exit.
  -s PATH, --script PATH
                        The path to a .js file that will be the entry point
                        for the target Node.js process
  -a STRING, --args STRING
                        Specifies command-line arguments to be passed to the
                        target Node.js process. The value should be a single
                        text string delimited by spaces. Example: rundown
                        inspect --scripts ./example.js --args="--flag
                        --option=123"
  -q, --quiet           Suppress STDOUT/STDERR for the target Node.js process
  -i, --ignore-exit-code
                        Do not report an error if the target Node.js process
                        returns a nonzero exit code

text

usage: rundown inspect [-h] -s PATH [-a STRING] [-q] [-i] [-t]

Invoke a Node.js script and generate detailed diagnostic output. This command
is used to inspect performance regressions.

Optional arguments:
  -h, --help            Show this help message and exit.
  -s PATH, --script PATH
                        The path to a .js file that will be the entry point
                        for the target Node.js process
  -a STRING, --args STRING
                        Specifies command-line arguments to be passed to the
                        target Node.js process. The value should be a single
                        text string delimited by spaces. Example: rundown
                        inspect --scripts ./example.js --args="--flag
                        --option=123"
  -q, --quiet           Suppress STDOUT/STDERR for the target Node.js process
  -i, --ignore-exit-code
                        Do not report an error if the target Node.js process
                        returns a nonzero exit code
  -t, --trace-imports   Reports the call chain for each module path, showing
                        how it was imported

File: apps/lockfile-explorer-web/README.md

@rushstack/lockfile-explorer-web

This is the React web application component of Rush Lockfile Explorer project.

This package is not published; the output bundle is copied and published with the @rushstack/lockfile-explorer package.

File: apps/lockfile-explorer/README.md

@rushstack/lockfile-explorer

Rush Lockfile Explorer helps you investigate and solve version conflicts when working in a monorepo
that uses the PNPM package manager. It's designed for the Rush
build orchestrator, but you can also use it to analyze a standalone PNPM workspace without Rush.

Lockfile Explorer helps with problems such as:

Understanding why multiple versions of an NPM package are appearing in your node_modules folder
Tracing dependencies to determine which project caused an NPM package to be installed
Finding and eliminating "doppelgangers" (multiple installations of the same version
of the same package)
Troubleshooting problems involving peer dependencies

This project is a new idea whose design is still evolving.
Please provide feedback by
creating a GitHub issue
or posting in the Rush Stack
Zulip chat room. Thank you!

Usage

Here's how to invoke the Rush Lockfile Explorer tool:

bash

# Install the NPM package globally.
#
# (You could substitute "pnpm" or "yarn" instead of "npm" here.  To avoid confusing
# duplicate installs, always use the same tool for global installations!)
npm install -g @rushstack/lockfile-explorer

# Go to your monorepo folder
cd my-rush-repo

# Run "rush install" to ensure common/temp/node_modules is up to date.
# (If your monorepo is using PNPM without Rush, substitute "pnpm install" for this step.)
rush install

# Launch the Lockfile Explorer command line interface (CLI).
# It expects to find a Rush/PNPM workspace in your shell's current working directory.
# As a shorthand, the "lfx" alias can be used here instead of "lockfile-explorer".
lockfile-explorer

The CLI will start a Node.js service on http://localhost/ and launch your default web browser:

Lockfile Explorer main window

How it works

The web app will expect to find a Rush/PNPM workspace in the current working directory where
the lockfile-explorer command was invoked. It will read files such as:

common/config/rush/pnpm-lock.yaml - the PNPM lockfile for your monorepo
common/config/rush/.pnpmfile.cjs - which transforms package.json files during installation
The package.json files for your local workspace projects
The package.json files for external packages installed in the node_modules folders.

File: apps/heft/src/schemas/README-ModifyingSchemas.md

Important

If you change the Heft schemas, be sure to update the example files under schemas/templates.
The templates are used as a reference when updating the website documentation.

File: apps/heft/README.md

@rushstack/heft

Heft is a config-driven toolchain that invokes other popular tools such as TypeScript, ESLint, Jest, Webpack,
and API Extractor. You can use it to build web applications, Node.js services, command-line tools, libraries,
and more. Heft builds all your JavaScript projects the same way: A way that works.

Heft is typically launched by package.json commands such as "npm run build" or "npm run test". It's designed
for use in a monorepo with potentially hundreds of projects, where the Rush orchestrator invokes
these commands separately in each project folder. In this situation, everything must execute as fast as possible.
Special purpose scripts become a headache to maintain, so it's better to replace them with a reusable engine that's
driven by config files. In a large repo, you'll want to minimize duplication of these config files across projects.
Ultimately, you'll want to define a small set of stereotypical project types
("rigs") to officially support, then discourage projects from
overriding the rig configuration. Being consistent ensures that any person can easily contribute to any project.
Heft is a ready-made implementation of all these concepts.

You don't need a monorepo to use Heft, however. It also works well for small standalone projects. Compared to other
similar systems, Heft has some unique design goals:

Scalable: Heft interfaces with the Rush Stack family of tools, which are tailored
for large monorepos with many people and projects. Heft doesn't require Rush, though.
Optimized: Heft tracks fine-grained performance metrics at each step. The TypeScript plugin implements
sophisticated optimizations such as: filesystem caching, incremental compilation, simultaneous multi-target emit,
and a unified compiler pass for Jest/Webpack/ESLint. JSON config files and plugin manifests enable fast
querying of metadata without evaluating potentially inefficient script code.
Complete: Rush Stack aspires to establish a fully worked out solution for building typical TypeScript
projects. Unopinionated task abstractions often work against this goal: It is expensive to optimize and support
(and document!) every possible cocktail of tech choices. The best optimizations and integrations
make deep assumptions about how tasks will interact. Although the Heft engine itself is very flexible,
our philosophy is to agree on a standard approach that covers a broad range of scenarios, then invest in
making the best possible experience for that approach.
Extensible: Most projects require at least a few specialized tasks such as preprocessors, postprocessors,
or loaders. Heft is organized around plugins using the tapable
hook system (familiar from Webpack). Strongly typed APIs make it easy to write your own plugins. Compared to
loose architectures such as Grunt or Gulp, Heft's plugin-system is organized around explicit easy-to-read
config files. Customizations generally will extend a standard rig rather than starting from scratch.
Familiar: Like Rush, Heft is a regular Node.js application -- developers don't need to install native
prerequisites such as Python, MSYS2, or the .NET Framework. Heft's source code is easy to understand and debug
because it's 100% TypeScript, the same programming language as your web projects. Developing for native targets
is still possible, of course.
Professional: The Rush Stack projects are developed by and for engineers who ship large scale commercial
apps. Each feature is designed, discussed in the open, and thoughtfully code reviewed. Breaking changes
require us to migrate thousands of our own projects, so upgrades are relatively painless compared to typical
Node.js tooling.

Heft has not yet reached its 1.0 milestone, however the following tasks are already available:

Compiler: TypeScript with incremental compilation, with "watch" mode
Linter: TypeScript-ESLint, plus legacy support
for projects that still use TSLint
Test runner: Jest
Bundler: Webpack, includingwebpack-dev-server with watch mode
.d.ts bundler: API Extractor
Asset management: Heft also includes a copy-static-assets helper supporting arbitrary globs, with "watch" mode

For more detailed documentation, please see the Heft topic on
the Rush Stack website.

File: apps/cpu-profile-summarizer/README.md

@rushstack/cpu-profile-summarizer

🚨 EARLY PREVIEW RELEASE 🚨

Not all features are implemented yet. To provide suggestions, please
create a GitHub issue.
If you have questions, see the Rush Stack Help page
for support resources.

The cpu-profile-summarizer command line tool helps you:

Collate self/total CPU usage statistics for an entire monorepo worth of V8 .cpuprofile files

Usage

It's recommended to install this package globally:

text

# Install the NPM package
npm install -g @rushstack/cpu-profile-summarizer

# Process a folder of cpuprofile files into a summary tsv file
cpu-profile-summarizer --input FOLDER --output FILE.tsv

The output file is in the tab-separated values (tsv) format.

File: apps/api-extractor/README.md

@microsoft/api-extractor

https://api-extractor.com/

API Extractor helps you build better TypeScript library packages. Suppose for example that your company has published an NPM package called "awesome-widgets" that exports many classes and interfaces. As developers start to depend on your library, you may encounter issues such as...

Accidental breaks: People keep reporting that their code won't compile after a supposedly "minor" update. To address this, you boldly propose that every awesome-widgets pull request must be approved by an experienced developer from your team. But that proves unrealistic -- nobody has time to look at every single PR! What you really need is a way to detect PRs that change API contracts, and flag them for review. That would focus attention in the right place... but how to do that?
Missing exports: Suppose the awesome-widgets package exports an API function AwesomeButton.draw() that requires a parameter of type DrawStyle, but you forgot to export this enum. Things seem fine at first, but when a developer tries to call that function, they discover that there's no way to specify the DrawStyle. How to avoid these oversights?
Accidental exports: You meant for your DrawHelper class to be kept internal, but one day you realize it's being exported. When you try to remove it, consumers complain that they're using it. How do we avoid this in the future?
Alpha/Beta graduation: You want to release previews of new APIs that are not ready for prime time yet. But if you did a major SemVer bump every time these definitions evolve, the villagers would be after you with torches and pitchforks! A better approach is to designate certain classes/members as alpha quality, then promote them to beta and finally to public as they mature. But how to indicate this to your consumers? (And how to detect scoping mistakes? A public function should never return a beta result.)
*.d.ts rollup: You webpacked your library into a nice *.js bundle file -- so why ship your typings as a messy tree of lib/*.d.ts files full of private definitions? Can't we consolidate them into a tidy *.d.ts rollup file? And if you publish internal/beta/public releases, each release type should get its own *.d.ts file with appropriate trimming. Developers building a production project don't want to see a bunch of internal and beta members in their VS Code IntelliSense!
Online documentation: You have faithfully annotated each TypeScript member with nice TSDoc descriptions. Now that your library has shipped, it's time to set up a nicely formatted API reference. What tool to use?

API Extractor provides an integrated, professional-quality solution for all these problems. It is invoked at build time by your toolchain and leverages the TypeScript compiler engine to:

Detect a project's exported API surface
Capture the contracts in a concise report designed to facilitate review
Warn about common mistakes (e.g. missing exports, inconsistent visibility, etc.)
Generate *.d.ts rollups with trimming according to release type
Output API documentation in a portable format that's easy to integrate with your content pipeline

Best of all, API Extractor is free and open source. Join the community and create a pull request!

Getting Started

For more details and support resources, please visit: https://api-extractor.com/

File: apps/api-documenter/README.md

@microsoft/api-documenter

This tool can be used to generate an online API reference manual for your TypeScript library.
It reads the *.api.json data files produced by API Extractor,
and then generates files in Markdown or
DocFX format.

For usage information, see the
Generating Docs article from the API Extractor
documentation.

File: build-tests/rush-redis-cobuild-plugin-integration-test/README.md

About

This package enables integration testing of the RedisCobuildLockProvider by connecting to an actual Redis created using an redis docker image.

Prerequisites

Docker and docker compose must be installed

Start the Redis

In this folder run docker-compose up -d

Stop the Redis

In this folder run docker-compose down

Install and build the integration test code

rush update
rush build -t rush-redis-cobuild-plugin-integration-test

Run the test for lock provider

# start the docker container: docker-compose up -d
# build the code: rushx build
rushx test-lock-provider

Integration test in sandbox repo

Sandbox repo folder: build-tests/rush-redis-cobuild-plugin-integration-test/sandbox/repo

cd sandbox/repo
node ../../lib/runRush.js update

You can also test sharded operations with cobuilds using the build-tests/rush-redis-cobuild-plugin-integration-test/sandbox/sharded-repo

cd sandbox/sharded-repo
node ../../lib/runRush.js update

You should expect to see multiple shards for operations a (15 shards), b (75) and h (50) and e (75).

Case 1: Normal build, Cobuild is disabled because of missing RUSH_COBUILD_CONTEXT_ID

Write to build cache

rm -rf common/temp/build-cache && node ../../lib/runRush.js --debug cobuild

Read from build cache

node ../../lib/runRush.js --debug cobuild

Expected behavior: Cobuild feature is disabled. Build cache is saved/restored as normal.

Case 2: Cobuild enabled by specifying RUSH_COBUILD_CONTEXT_ID and Redis authentication

Clear redis server

(cd ../.. && docker compose down && docker compose up -d)

Run cobuilds

rm -rf common/temp/build-cache && RUSH_COBUILD_CONTEXT_ID=foo REDIS_PASS=redis123 RUSH_COBUILD_RUNNER_ID=runner1 node ../../lib/runRush.js --debug cobuild

Expected behavior: Cobuild feature is enabled. Run command successfully.
You can also see cobuild related logs in the terminal.

Running cobuild (runner foo/runner1)
Analyzing repo state... DONE (0.11 seconds)

Executing a maximum of 10 simultaneous processes...

==[ b (build) ]====================================================[ 1 of 9 ]==
Get completed_state(cobuild:completed:foo:2e477baf39a85b28fc40e63b417692fe8afcc023)_package(b)_phase(_phase:build): SUCCESS;2e477baf39a85b28fc40e63b417692fe8afcc023
Get completed_state(cobuild:completed:foo:cfc620db4e74a6f0db41b1a86d0b5402966b97f3)_package(a)_phase(_phase:build): SUCCESS;cfc620db4e74a6f0db41b1a86d0b5402966b97f3
Successfully acquired lock(cobuild:lock:foo:4c36160884a7a502f9894e8f0adae05c45c8cc4b)_package(b)_phase(_phase:build) to runner(runner1) and it expires in 30s

Case 3: Cobuild enabled, run two cobuild commands in parallel

Note: This test requires Visual Studio Code to be installed.

Open predefined .vscode/redis-cobuild.code-workspace in Visual Studio Code.
Clear redis server

# Under rushstack/build-tests/rush-redis-cobuild-plugin-integration-test
docker compose down && docker compose up -d

Clear build cache

# Under rushstack/build-tests/rush-redis-cobuild-plugin-integration-test/sandbox/repo
rm -rf common/temp/build-cache

Open command palette (Ctrl+Shift+P or Command+Shift+P) and select Tasks: Run Task and select cobuild.

In this step, two dedicated terminal windows will open. Running rush cobuild command under sandbox repo respectively.

Expected behavior: Cobuild feature is enabled, cobuild related logs out in both terminals.

Case 4: Cobuild enabled, run two cobuild commands in parallel, one of them failed

Note: This test requires Visual Studio Code to be installed.

Open predefined .vscode/redis-cobuild.code-workspace in Visual Studio Code.
Making the cobuild command of project "A" fails

sandbox/repo/projects/a/package.json

diff

"scripts": {
-   "_phase:build": "node ../build.js a",
+   "_phase:build": "exit 1",
  }

Clear redis server

# Under rushstack/build-tests/rush-redis-cobuild-plugin-integration-test
docker compose down && docker compose up -d

Clear build cache

# Under rushstack/build-tests/rush-redis-cobuild-plugin-integration-test/sandbox/repo
rm -rf common/temp/build-cache

Open command palette (Ctrl+Shift+P or Command+Shift+P) and select Tasks: Run Task and select cobuild.

Expected behavior: Cobuild feature is enabled, cobuild related logs out in both terminals. These two cobuild commands fail because of the failing build of project "A". And, one of them restored the failing build cache created by the other one.

Case 5: Sharded cobuilds

Enable the allowCobuildWithoutCache experiment in experiments.json.

Navigate to the sandbox for sharded cobuilds,

cd sandbox/sharded-repo

Next, start up your Redis instance,

docker compose down && docker compose up -d

Then, open 2 terminals and run this in each (changing the RUSH_COBUILD_RUNNER_ID across the 2 terminals),

rm -rf common/temp/build-cache && RUSH_COBUILD_CONTEXT_ID=foo REDIS_PASS=redis123 RUSH_COBUILD_RUNNER_ID=runner1 node ../../lib/runRush.js cobuild -p 10 --timeline

If all goes well, you should see a bunch of operation with - shard xx/yy. Operations h (build) and e (build) are both sharded heavily and should be cobuild compatible. To validate changes you're making, ensure that the timeline view for all of the shards of those 2 operations are cobuilt across both terminals. If they're not, something is wrong with your update.

2. Official Technical Reference & Guides (microsoft/microsoft.github.io)

File: README.md

[microsoft.github.io](https://microsoft.github.io)

Many open source projects released by Microsoft products, services and teams also have
deployments powered by GitHub Pages on this domain.

To discover Microsoft-released open source projects, learn about Microsoft's open source
approach and other information, check us out online at opensource.microsoft.com.

If we can help answer questions about the open source program at Microsoft, you can
contact opensource at microsoft com - although we are not able to provide support
for projects through this mechanism.

Microsoft GitHub resources

Default repo templates including SECURITY.MD and code of conduct files: microsoft/repo-templates
Code of Conduct (FAQ)

Microsoft open source resources

Resources for Microsoft employees

How to identify an official Microsoft organization on GitHub

Official Microsoft GitHub orgs have a professional avatar and include a web address at Microsoft.com or an associated official domain
Official Microsoft orgs are Verified on GitHub - look for the domain verification indicator on GitHub

File: SECURITY.MD

IMPORTANT: THIS IS NOT THE SOURCE OF TRUTH FOR THIS FILE

The SECURITY.MD file used by default in new Microsoft GitHub repos can be found
in the repo microsoft/repo-templates at https://github.com/microsoft/repo-templates.

Please contribute any fixes there.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include Microsoft, Azure, DotNet, AspNet, Xamarin, and our GitHub organizations.

If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's definition of a security vulnerability, please report it to us as described below.

Reporting Security Issues

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them to the Microsoft Security Response Center (MSRC) at https://msrc.microsoft.com/create-report.

If you prefer to submit without logging in, send email to [email protected]. If possible, encrypt your message with our PGP key; please download it from the Microsoft Security Response Center PGP Key page.

You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at microsoft.com/msrc.

Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:

Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
Full paths of source file(s) related to the manifestation of the issue
The location of the affected source code (tag/branch/commit or direct URL)
Any special configuration required to reproduce the issue
Step-by-step instructions to reproduce the issue
Proof-of-concept or exploit code (if possible)
Impact of the issue, including how an attacker might exploit the issue

This information will help us triage your report more quickly.

If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our Microsoft Bug Bounty Program page for more details about our active programs.

Preferred Languages

We prefer all communications to be in English.

Policy

Microsoft follows the principle of Coordinated Vulnerability Disclosure.

File: codeofconduct/index.md

Microsoft Open Source Code of Conduct

This code of conduct outlines expectations for participation in Microsoft-managed open source communities, as well as steps for reporting unacceptable behavior. We are committed to providing a welcoming and inspiring community for all. People violating this code of conduct may be banned from the community.

Our open source communities strive to:

Be friendly and patient: Remember you might not be communicating in someone else's primary spoken or programming language, and others may not have your level of understanding.
Be welcoming: Our communities welcome and support people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
Be respectful: We are a world-wide community of professionals, and we conduct ourselves professionally. Disagreement is no excuse for poor behavior and poor manners. Disrespectful and unacceptable behavior includes, but is not limited to:
- Violent threats or language.
- Discriminatory or derogatory jokes and language.
- Posting sexually explicit or violent material.
- Posting, or threatening to post, people's personally identifying information ("doxing").
- Insults, especially those using discriminatory terms or slurs.
- Behavior that could be perceived as sexual attention.
- Advocating for or encouraging any of the above behaviors.
Understand disagreements: Disagreements, both social and technical, are useful learning opportunities. Seek to understand the other viewpoints and resolve differences constructively.
This code is not exhaustive or complete. It serves to capture our common understanding of a productive, collaborative environment. We expect the code to be followed in spirit as much as in the letter.

Scope

This code of conduct applies to all repos and communities for Microsoft-managed open source projects regardless of whether or not the repo explicitly calls out its use of this code. The code also applies in public spaces when an individual is representing a project or its community. Examples include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Note: Some Microsoft-managed communities have codes of conduct that pre-date this document and issue resolution process. While communities are not required to change their code, they are expected to use the resolution process outlined here. The review team will coordinate with the communities involved to address your concerns.

Reporting Code of Conduct Issues

We encourage all communities to resolve issues on their own whenever possible. This builds a broader and deeper understanding and ultimately a healthier interaction. In the event that an issue cannot be resolved locally, please feel free to report your concerns by contacting [email protected]. Your report will be handled in accordance with the issue resolution process described in the Code of Conduct FAQ.

In your report please include:

Your contact information.
Names (real, usernames or pseudonyms) of any individuals involved. If there are additional witnesses, please include them as well.
Your account of what occurred, and if you believe the incident is ongoing. If there is a publicly available record (e.g. a mailing list archive or a public chat log), please include a link or attachment.
Any additional information that may be helpful.

All reports will be reviewed by a multi-person team and will result in a response that is deemed necessary and appropriate to the circumstances. Where additional perspectives are needed, the team may seek insight from others with relevant expertise or experience. The confidentiality of the person reporting the incident will be kept at all times. Involved parties are never part of the review team.

Anyone asked to stop unacceptable behavior is expected to comply immediately. If an individual engages in unacceptable behavior, the review team may take any action they deem appropriate, including a permanent ban from the community.

This code of conduct is based on the template established by the TODO Group and used by numerous other large communities (e.g., Facebook, Twitter, GitHub and the Scope section from the Contributor Covenant version 1.4.

File: codeofconduct/faq/index.md

Microsoft Open Source Code of Conduct FAQ

Why have a Code of Conduct?
Why this Code of Conduct?
Why do this across all repos?
How does a project adopt the code and process?
What if my Microsoft project already has a Code of Conduct?
How do I raise a concern?
What is the process for addressing issues that arise?
How does the resolution team work?
Can I use this Code of Conduct in my projects?

Why have a Code of Conduct?

People and communities are the foundation of open source. Communities thrive through diversity of thought and the safety of its members. Microsoft has a deep-seated commitment to diversity and inclusion. All Microsoft employees enjoy a safe work environment and a culture of mutual respect and responsibility. Our team members and open source partners should enjoy the same environment when collaborating on open source projects.

While conduct issues seldom arise, when they do, they are often very public and very passionate. It is best for the community to be prepared with:

A clear and accessible Code of Conduct stating the norms under which projects operate
An Issue Resolution Process for addressing cases where these norms are not being maintained

Why this Code of Conduct?

The Microsoft Open Source Code of Conduct is an instantiation of the TODO Group Code of Conduct template, that captures the Microsoft culture of equality, respect and inclusion. This same template is used by industry colleagues such as Facebook, Twitter, GitHub, Yahoo and others in their open source projects.

Why do this across all repos?

Having one code and process is both efficient and consistent — community members can participate in any Microsoft-driven project and be confident that they know the norms and that they are supported by a robust process.

How does a project adopt the code and process?

All Microsoft projects are automatically covered by the Code of Conduct and the Issue Resolution Process. However, it is critical that everyone in the communities be aware of the code and process. For that reason, all projects must link to the Code of Conduct in their README and/or CONTRIBUTING files using the following markdown.

text

This project has adopted the [Microsoft Open Source Code of
Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct
FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [[email protected]](mailto:[email protected])
with any additional questions or comments.

What if my Microsoft project already has a Code of Conduct?

Thanks for being proactive in this important area. You are welcome to continue using your existing Code of Conduct, or you may change to the Microsoft Open Source Code of Conduct. Either way, all Microsoft projects must use the same issue resolution process. Please ensure that your documentation and guidance is updated to point people at the process outlined in this FAQ (see below).

Projects in the .NET Foundation are already covered by the .NET Foundation Contributors Code of Conduct. As such, there is no need for .NET Foundation projects to make any changes.

How do I raise a concern?

If you have witnessed or been subjected to a violation of the Code of Conduct, please send an email to [email protected]. Your message will be handled in a secure and confidential manner. This email address is monitored by people who are not active in open source projects or communities — so you can be sure that you are not communicating with a person involved in the issue you are reporting. You will receive a response within one business day acknowledging receipt of your email and describing the process for its resolution. (See below for more details.)

What is the process for addressing issues that arise?

Emails sent to [email protected] kick off the following process:

Your message will be acknowledged within one business day.
Within the following business day, a small, 2-3, person team will be assembled from a pool of Microsoft employee volunteers to review your concern. This team will be as diverse as possible given its size and will pull in additional people as needed to gain further insight and provide guidance. The team will not include anyone directly involved in the issue that has been raised.
From there team will work with you and the others involved to come to a conclusion. While issue complexity varies, the goal is to resolve issues within five working days.
All communication will be confidential with very limited circulation.

How does the resolution team work?

Beyond the norms and values set out in the Code of Conduct, issue review teams operate under the following principles:

Less is more — As much as possible, let the community work it out. It is much better to have communities self-correct than to have outsiders come in and “fix” problems.
Equality — Contribution value or status in the community are not relevant to the review. Key people do not have more rights (either to abuse or be protected from abuse) than others in the community.
Independence — Reviewers must act and be seen to act with independence from the project(s) in question and from Microsoft.

Can I use this Code of Conduct in my projects?

Yes. The document is licenced under CC BY 4.0. You will of course need to update the document to suit the specifics of your projects, but by all means use this however you can to drive great communities.

Docker & Self-Hosted Deployment Verified OCI

1. Project Overview & Quickstart (microsoft/rushstack) Copy Chapter

File: apps/trace-import/README.md Copy Chapter

@rushstack/trace-import

Usage Copy Chapter

Command line Copy Chapter

Sample outputs Copy Chapter

Resolving a CommonJS main index Copy Section

Resolving a CommonJS package subpath Copy Section

Resolving a TypeScript declaration Copy Section

Resolving a relative path Copy Section

Links Copy Chapter

File: apps/rush-mcp-server/README.md Copy Chapter

@rushstack/mcp-server

Usage Copy Chapter

Available Tools Copy Chapter

Links Copy Chapter

File: apps/rush/README.md Copy Chapter

@microsoft/rush

3 Minute Demo

Getting Started Copy Chapter

Links Copy Chapter

File: apps/rundown/README.md Copy Chapter

@rushstack/rundown

Installation Copy Chapter

Viewing imported files Copy Chapter

Finding callers Copy Chapter

Fixing problems Copy Chapter

Generating a snapshot Copy Chapter

Command-line reference Copy Chapter

Links Copy Chapter

File: apps/lockfile-explorer-web/README.md Copy Chapter

@rushstack/lockfile-explorer-web

File: apps/lockfile-explorer/README.md Copy Chapter

@rushstack/lockfile-explorer

Usage Copy Chapter

How it works Copy Chapter

Links Copy Chapter

File: apps/heft/src/schemas/README-ModifyingSchemas.md Copy Chapter

Important Copy Chapter

File: apps/heft/README.md Copy Chapter

@rushstack/heft

Links Copy Chapter

File: apps/cpu-profile-summarizer/README.md Copy Chapter

@rushstack/cpu-profile-summarizer

Usage Copy Chapter

File: apps/api-extractor/README.md Copy Chapter

@microsoft/api-extractor

Getting Started Copy Chapter

Links Copy Chapter

File: apps/api-documenter/README.md Copy Chapter

@microsoft/api-documenter

Links Copy Chapter

File: build-tests/rush-redis-cobuild-plugin-integration-test/README.md Copy Chapter

About

Prerequisites

Start the Redis

Stop the Redis

Install and build the integration test code

Run the test for lock provider

Integration test in sandbox repo

Case 1: Normal build, Cobuild is disabled because of missing RUSH_COBUILD_CONTEXT_ID

Case 2: Cobuild enabled by specifying RUSH_COBUILD_CONTEXT_ID and Redis authentication

Case 3: Cobuild enabled, run two cobuild commands in parallel

Case 4: Cobuild enabled, run two cobuild commands in parallel, one of them failed

Case 5: Sharded cobuilds

2. Official Technical Reference & Guides (microsoft/microsoft.github.io) Copy Chapter

File: README.md Copy Chapter

[microsoft.github.io](https://microsoft.github.io)

Microsoft GitHub resources Copy Chapter

Microsoft open source resources Copy Chapter

Resources for Microsoft employees Copy Chapter

How to identify an official Microsoft organization on GitHub Copy Chapter

File: SECURITY.MD Copy Chapter

IMPORTANT: THIS IS NOT THE SOURCE OF TRUTH FOR THIS FILE

Security Copy Chapter

Reporting Security Issues Copy Chapter

Preferred Languages Copy Chapter

Policy Copy Chapter

File: codeofconduct/index.md Copy Chapter

1. Project Overview & Quickstart (microsoft/rushstack)

File: apps/trace-import/README.md

Usage

Command line

Sample outputs

Resolving a CommonJS main index

Resolving a CommonJS package subpath

Resolving a TypeScript declaration

Resolving a relative path

Links

File: apps/rush-mcp-server/README.md

Usage

Available Tools

Links

File: apps/rush/README.md

Getting Started

Links

File: apps/rundown/README.md

Installation

Viewing imported files

Finding callers

Fixing problems

Generating a snapshot

Command-line reference

Links

File: apps/lockfile-explorer-web/README.md

File: apps/lockfile-explorer/README.md

Usage

How it works

Links

File: apps/heft/src/schemas/README-ModifyingSchemas.md

Important

File: apps/heft/README.md

Links

File: apps/cpu-profile-summarizer/README.md

Usage

File: apps/api-extractor/README.md

Getting Started

Links

File: apps/api-documenter/README.md

Links

File: build-tests/rush-redis-cobuild-plugin-integration-test/README.md

2. Official Technical Reference & Guides (microsoft/microsoft.github.io)

File: README.md

Microsoft GitHub resources

Microsoft open source resources

Resources for Microsoft employees

How to identify an official Microsoft organization on GitHub

File: SECURITY.MD

Security

Reporting Security Issues

Preferred Languages

Policy

File: codeofconduct/index.md

Scope

Reporting Code of Conduct Issues

File: codeofconduct/faq/index.md

Contents

Why have a Code of Conduct?

Why this Code of Conduct?

Why do this across all repos?

How does a project adopt the code and process?

What if my Microsoft project already has a Code of Conduct?

How do I raise a concern?

What is the process for addressing issues that arise?

How does the resolution team work?

Can I use this Code of Conduct in my projects?