Clarify when to use `rushx` over `rush-pnpm run`

Open
#280 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
typescript
Domain
documentation

Research direction

Start with the linked rushx and rush-pnpm command pages, then compare the referenced RushCommandSelector.ts, RushPnpmCommandLineParser.ts, and RushXCommandLine.ts entry points. Trace the documented differences between workspace scripts, local commands, and remote commands. Done means the documentation clearly explains when to choose each command and covers the listed pnpm use cases.

Written by the indexing model from the issue text.

Description

I've been looking through the website to find some information on the binaries and am wondering if I am missing something obvious.

When do I use rushx <script-name> over rush-pnpm run <script-name>? What do they do differently?

(toggle) Motivation/Why?

This came about as I am trying to figure out whether I need to open a discussion in Rush's chat room or if I need to open an issue with the npm-run-all2 package to figure out how to correctly use npm-run-all2 in a Rush monorepo, including special consideration for pnpm if needed.

  • use npm-run-all2 from a script in a workspace's package.json file
  • use npm-run-all2 from a command line when the CWD is in a workspace
    • globally installed
    • locally installed
  • use npm-run-all2 at the root level
    • custom command + auto installer?

While the need to use a specific package may be mine, I think the confusion about when to use which command with pnpm is not unique to me and could use clarity in the documentation.

Is there a part of the documentation that I am missing?

(toggle) I tried to follow the Rush source code, but got lost or burned out (probably both)
  1. All of the the binaries import start.js as a side effect
  2. Start callsRushCommandSelector.execute(launcherVersion, selectedRushLib, options)
    1. Calls RushCommandSelector._getCommandName()
    2. Which determines the command that is called
  3. if rush-pnpm
    1. launch the internal API using rush-lib, which then runs like any other API would
    2. Process and load the Rush configuration
      1. Determine that the package manager is pnpm using the config
      2. Set the path to a local copy of the package manager
    3. Determine the pnpm command arguments (this includes the which pnpm command is being called)
    4. Among other things, it produces warnings and errors for commands known to be incompatible or otherwise contradictory to Rush. run and exec are known to be safe
  4. if rushx
    1. launch the internal API using rush-lib, which then runs like any other API would
(toggle) What Rush Command or Practice Replaces What?

Workspace script

Arbitrary Command From A Package At The Root Level

  • don't do this in a Rush monorepo?
  • use custom commands / autoinstallers instead?
In A Workspace While At The Root Level

Arbitrary REMOTE Command From A Package At The Workspace Level

  • don't do this in a Rush monorepo?

rush-pnpm dlx <command-name> "works" (I think?), but I can't figure out why. dlx is not known to be a safe command according to Rush. It is always REMOTE and doesn't seem to use the command in the workspace's LOCAL node_modules directory.

Arbitrary LOCAL Command From A Package At The Workspace Level

What is the rush replacement for the following?

Dominant language
TypeScript
Stars
39
Forks
86
Avg merge
1d 14h
Merged PRs (30d)
2

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/rushstack-websites

All issues in microsoft/rushstack-websites

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.