[DOCS] rebuild command needs new description

[rotu]

Is there an existing issue for this?

• I have searched the existing issues

This is a CLI Docs Problem, not another kind of Docs Problem.

• This is a CLI Docs Problem.

Description of Problem

The docs for npm rebuild command don't explain what it does, but describe it in terms of the defunct npm build command.

This command runs the npm build command on the matched folders. This is useful when you install a new version of node, and must recompile all your C++ addons with the new binary. It is also useful when installing with --ignore-scripts and --no-bin-links, to explicitly choose which packages to build and/or link bins.

If one or more package specs are provided, then only packages with a name and version matching one of the specifiers will be rebuilt.

Potential Solution

Rewrite the docs for npm rebuild to explain what it does (i.e. conditionally run node-gyp, runs certain lifecycle hooks, maybe other things?).

Affected URL

https://docs.npmjs.com/cli/v9/commands/npm-rebuild

[siemhesda]

Hi @rotu, how does this look like?

This command is used to conditionally run the node gyp build tool. This is
useful when you install a new version of node, and must recompile all your
C++ addons with the new binary. It is also useful when installing with
--ignore-scripts and --no-bin-links, to explicitly choose which
packages to build and/or link bins.

If one or more package specs are provided, then only packages with a
name and version matching one of the specifiers will be rebuilt.

[siemhesda]

Hi @rotu, how does this look like?

This command is used to conditionally run the node gyp build tool. This is
useful when you install a new version of node, and must recompile all your
C++ addons with the new binary. It is also useful when installing with
--ignore-scripts and --no-bin-links, to explicitly choose which
packages to build and/or link bins.

If one or more package specs are provided, then only packages with a
name and version matching one of the specifiers will be rebuilt.

@wraithgar could you also help me cross check this?

[rotu]

Thank you for doing this!

My best guess based on reading https://github.com/npm/cli/blob/ed8c553b0f059ca2a1e288b48dff675d6703208f/workspaces/arborist/lib/arborist/rebuild.js

1. Runs node-gyp rebuild to create a binding.gyp file. This is only done if:
   • There is a binding.gyp file in the package root
   • There is neither a preinstall nor install hook (which would suggest that you have a custom command to build your package)
   • Your package.json does not contain the undocumented "gypfile": false
2. Creates links in node_modules/.bin for files specified in package.json#bin so that they can be found with npm exec/npx or called from package scripts.

I believe that rebuild is also done by npm install by default, which is why you don't need to npm rebuild unless you've suppressed the build or bin link with the mentioned arguments.

[siemhesda]

I went through the file once more and @rotu , your description is accurate. However, I am trying to draw a line between explaining what the code does and providing a user friendly description of what happens under the hood. So I combined your description and my observations and ...

This command is used to do the following:

• Conditionally run the node gyp build tool.
• Execute lifecycle scripts (preinstall, install, postinstall, prepare)
• Links bins depending on whether bin links are enabled

This command is particularly useful in scenarios including but not limited to:

• Installing a new version of Node.js, where you need to recompile all your C++ add-ons with the updated binary.
• Installing with --ignore-scripts and --no-bin-links, to explicitly choose which packages to build and/or link bins.

If one or more package specs are provided, then only packages with a
name and version matching one of the specifiers will be rebuilt.

How does this look?

[rotu]

Yes, I didn't mean for my comment to be used verbatim!

Here are my critiques:

1. The word "conditionally" is doing a lot of heavy lifting. (conditional on what?)
2. "Particularly useful" does inform the user "when should I use this command"

I'd change it to something like:

This command does two things:

1. Installs executables via package.json#bin so they may be called with npm exec or from package scripts.
2. Compiles native code.

If one or more package specs are provided, then only packages with a name and version matching one of the specifiers will be rebuilt. Usually, you should not need to run npm rebuild - it is already done for you as part of npm install (unless you suppressed these steps with --ignore-scripts or --no-bin-links).

If there is a binding.gyp file in the root of your package, then npm will use a default install hook: "scripts": {"install": "node-gyp rebuild"}. This default behavior is suppressed if the package.json has its own install or preinstall scripts. It is also suppressed if the package specifies `"gypfile": false",

BTW, I also submitted #6898 to report the missing docs about the package.json file.