node-libcurl is a TypeScript-based Node.js binding for libcurl, the widely-used C library for URL transfers. The package provides native bindings that expose libcurl's functionality to JavaScript developers, enabling high-performance HTTP and protocol operations within Node.js applications. The library is written in TypeScript and compiled to native code using node-gyp, making it a compiled addon rather than a pure JavaScript module.
The package supports an extensive range of protocols and features inherited from libcurl itself, including HTTP, HTTPS, FTP, FTPS, SFTP, and numerous others. It handles advanced HTTP features such as HTTP/2 and HTTP/3 support, along with authentication methods including Basic, Digest, NTLM, Negotiate, and Kerberos. The library supports SSL certificates, cookies, proxies, file uploads, multipart form data, and HTTP form submissions. Binary data handling is supported through custom write functions and specific flags to prevent automatic UTF-8 decoding.
The package provides two primary APIs for making requests. The simpler curly API offers async/await support for straightforward use cases, though it is marked as experimental and subject to change without a major version bump. The more comprehensive Curl class provides granular control over request options and behavior. Both APIs support setting custom HTTP headers, form submissions, multipart uploads, and binary data transfers. The library exposes nearly all libcurl options through either their full names or lowerPamelCase format equivalents, throwing errors when unsupported options are passed.
Installation is simplified through prebuilt binaries available via node-pre-gyp for the latest two active LTS Node.js versions plus the current version, as well as the latest two major versions of Electron. These binaries are available for Linux 64-bit, ARM64, Alpine, macOS Intel and ARM64, and Windows 64-bit. The prebuilt binaries are statically linked with brotli, libidn2, libssh2, OpenLDAP, OpenSSL, nghttp2, zstd, and zlib. For systems without prebuilt binaries or when custom builds are needed, the package requires Python 3.x and a C++17-capable compiler, or C++20 for Electron versions 32 and above.
The library requires libcurl version 7.81.0 or later, released in January 2022 and shipped with Ubuntu 22.04. This version requirement ensures access to thousands of bug fixes accumulated since then. The package includes comprehensive documentation available through Netlify for both stable and development branches, along with TypeScript type definitions for full IDE support. An examples folder provides usage demonstrations for various scenarios including SSL configuration, binary data handling, and form submissions.
The repository is maintained with enterprise support available through Tidelift Subscription, offering commercial maintenance and support options. The package is published on npm and includes a common issues documentation file for troubleshooting. Special considerations are documented for the READFUNCTION option regarding buffer handling and the implications of using allocUnsafe buffers. The project supports contributions and includes donation options through Buy Me A Coffee and Patreon, with a Discord server available for community support.
