npm-rebuild

Rebuild a specific package

$ npm [[rb|rebuild]] [package]

$ npm [[rb|rebuild]]

$ npm [[rb|rebuild]] --verbose

$ npm [[rb|rebuild]] --prefix [path/to/dir] [package]

$ npm [[rb|rebuild]] --no-cache

$ npm [[rb|rebuild]] [[-g|--global]]

npm rebuild [[<@scope>]/<pkg>...]
npm rebuild [--prefix <path>]

[<@scope>]/<pkg>...
    Optional. One or more package names to rebuild. If no package names are provided, all packages in the node_modules tree will be rebuilt.

--prefix <path>
    Operate on the package in the given path rather than the current working directory. This allows rebuilding dependencies of a project located elsewhere.

--production
    Rebuild only dependencies and not devDependencies. This is useful for production environments to minimize build time and footprint.

--dry-run
    Run the command without actually performing any actions. This shows what would happen, which can be useful for debugging or previewing changes.

--unsafe-perm
    Set to true to run scripts as root. It is often necessary for native module compilation, especially when installing global packages or when compilers require elevated permissions.

The npm rebuild command is used to recompile and rebuild native Node.js add-ons for one or more packages, or for all packages in the node_modules directory. Native add-ons are modules written in languages like C or C++ that are compiled against a specific Node.js version and system architecture.

This command is essential when the Node.js version changes, when a project's node_modules directory is moved between different operating systems or architectures, or when a native dependency fails to build correctly during an npm install. It effectively traverses the dependency tree, identifies packages with native components (typically indicated by a binding.gyp file), and attempts to recompile them using node-gyp. This ensures that the native modules are compatible with the current environment, resolving potential runtime errors due to ABI mismatches.

Build Tools Required: Rebuilding native add-ons requires a proper development environment, including C/C++ compilers (e.g., GCC, Clang, MSVC), Python (usually 2.x or 3.x), and make (on Unix-like systems). On Debian/Ubuntu, this often means installing the build-essential package; on macOS, Xcode Command Line Tools; and on Windows, Visual Studio.

Time Consuming: Depending on the number and complexity of native modules, the rebuild process can take a significant amount of time and consume considerable CPU resources.

Permission Issues: Native module compilation can sometimes encounter permission errors, especially if global packages are being rebuilt or if the build process attempts to write to restricted directories. Using --unsafe-perm or running with sudo might be necessary (use with caution).

Compilation Errors: Even with correct tools, compilation can fail due to specific module requirements, incompatible compiler versions, or missing system libraries. Reviewing the detailed error output is crucial for troubleshooting.

npm rebuild internally leverages node-gyp, a cross-platform command-line tool written in Node.js, to compile the native add-on modules. node-gyp reads a binding.gyp file (a project configuration file) within each native package to determine how to build the module, fetch Node.js headers, and invoke the system's C/C++ compiler. Understanding node-gyp can be beneficial for advanced troubleshooting of compilation issues.

You should consider using npm rebuild in situations such as:
1. After upgrading or downgrading your Node.js version.
2. When transferring a node_modules directory from one machine to another with a different operating system or CPU architecture.
3. If you encounter errors like 'Module did not self-register' or 'The specified module could not be found' for native modules after an npm install.
4. When development environments (e.g., compilers) on your system change significantly.

npm rebuild has been a fundamental utility within the npm ecosystem since its early days, addressing the persistent challenge of managing native Node.js add-ons. Its development paralleled the growth of Node.js and the increasing adoption of native modules for performance-critical tasks or system-level interactions. The command's core functionality, which relies heavily on node-gyp, has remained consistent: to provide a reliable way for developers to ensure their native dependencies are correctly compiled and compatible with the current Node.js runtime and host environment. It has been instrumental in enabling smoother transitions between Node.js versions and facilitating cross-platform development.

npm install(1), npm update(1), node-gyp(1)