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

[npetruzzelli]

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

• use rushx <script-name> as a replacement for:
  • npm run-script <script-name> (aliased: npm run)
  • yarn <script-name> (Yarn Classic) CWD is in the workspace
  • yarn <script-name>
• pnpm: ???
  • use rush-pnpm run <script-name> or rushx <script-name>? as a replacement for pnpm run <script-name>

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

• don't do this in a Rush monorepo?
• replaces:
  • npm run --workspace=<workspace-name> <command-name> (see also: --workspaces and --include-workspace-root)
  • yarn workspace <workspace-name> <command-name> (Yarn Classic)
  • yarn workspace <workspace-name> <command-name>
  • pnpm filtering

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?

• npx <command-name>
• npm exec <command-name>
  • npx vs npm exec
• yarn <command-name> (Yarn classic: Locally installed CLIs)
• yarn dlx <command-name> (Yarn Berry)
• yarn exec <command-name> (Yarn Berry)
• pnpm dlx <command-name>
  • pnpx is an alias for pnpm dlx
• pnpm exec <command-name>
  • pnpm <command-name>

    The exec part is actually optional when the command is not in conflict with a builtin pnpm command