node-pre-gyp
A Node.js tool for publishing and installing C++ addons from pre-built binaries.
What is node-pre-gyp?
@mapbox/node-pre-gyp is a Node.js tool that facilitates the distribution and installation of pre-compiled binary packages for native C++ addons. It solves the problem of requiring end-users to compile native modules from source by allowing developers to publish platform-specific binaries that can be downloaded directly during npm install. This significantly reduces installation time and avoids compilation errors on user machines.
Node.js module authors who create or maintain native C++ addons and want to provide a seamless installation experience for their users across different operating systems and Node versions.
Developers choose node-pre-gyp because it automates the complex process of binary deployment, integrates easily with npm workflows, and supports both traditional builds and the newer ABI-stable Node-API. Its ability to fall back to source compilation ensures reliability, while its deep integration with CI services like Travis and Appveyor streamlines automated publishing.
Overview
Node.js tool for easy binary deployment of C++ addons
Use Cases
Best For
- Distributing native Node.js modules without requiring users to have compilers installed
- Automating binary builds and publications via CI/CD pipelines
- Supporting multiple Node.js versions and platforms (Windows, macOS, Linux) with pre-built binaries
- Creating Node-API (N-API) modules that need ABI-stable binary distribution
- Hosting private or public binary packages on Amazon S3 or custom HTTPS endpoints
- Simplifying the installation process for modules with complex C++ dependencies
Not Ideal For
- Projects consisting solely of JavaScript/TypeScript code with no native C++ bindings
- Teams with security policies that mandate compiling all dependencies from source to avoid external binaries
- Modules targeting a single, controlled environment where cross-platform binary distribution adds unnecessary overhead
- Developers who prefer using node-gyp directly for finer-grained control over the compilation process without binary hosting
Pros & Cons
Pros
Provides built-in commands like 'package', 'publish', and 'info' that automate the packaging and uploading of pre-built binaries to services like S3, reducing manual steps for module authors.
Handles binaries for multiple operating systems and architectures, and integrates with Node-API for ABI-stable builds across Node.js versions, ensuring wide compatibility as detailed in the configuration sections.
Automatically falls back to compiling from source using node-gyp if a compatible binary isn't available, preventing installation failures and ensuring robustness.
Includes comprehensive guides for automating builds and publications with Travis CI and Appveyor, including secure environment variable setup, streamlining continuous deployment.
Cons
Requires extensive setup in package.json and binding.gyp, such as adding binary objects and custom build targets, which can be error-prone and daunting for new users.
Key features like 'publish' and 'info' commands are optimized for Amazon S3, limiting functionality with alternative hosting options and forcing a dependency on AWS for full utility.
The deprecation of unscoped versions in favor of @mapbox/node-pre-gyp requires manual updates to dependencies and configurations, as noted in the 'Special note on previous package'.
Requires @aws-sdk/client-s3 as a devDependency for publishing, adding significant bundle size that may be overhead for projects not using S3 or with size constraints.
Frequently Asked Questions
Related Projects
huskyGit hooks made easy 🐶 woof!
jsdomA JavaScript implementation of various web standards, for use with Node.js
dotenvLoads environment variables from .env for nodejs projects.
patch-packageFix broken node modules instantly 🏃🏽♀️💨
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.