cloudinary

The cloudinary package is Cloudinary’s official Node.js SDK, used from server-side code to upload media, generate transformation and delivery URLs, and manage assets on the Cloudinary platform. It wraps Cloudinary’s REST API with a signed-request layer built on Node’s native http/https modules, so calling code doesn’t have to hand-build multipart uploads or query-string signatures.

The SDK exposes two coexisting surfaces: a flat require('cloudinary') module preserved since the package’s 2012 origins, and a namespaced require('cloudinary').v2 that layers uploader, api, search, and search_folders on top without breaking existing v1 callers. In practice, most new code uses v2 for uploads (cloudinary.v2.uploader.upload(...)), asset search, and moderation, and the shared cloudinary.url() helper for building responsive, format- and quality-optimized delivery URLs.

What You Get

• A single upload() entry point that accepts a local file path, a remote URL, or a readable stream and dispatches the correct multipart/remote-fetch request automatically
• A cloudinary.url() builder for generating signed, transformation-aware delivery URLs (crop, resize, format/quality auto-negotiation, responsive breakpoints)
• Asset search and management via the search and api namespaces (list, tag, moderate, and delete uploaded resources)
• Helpers for signing browser-originated uploads server-side, so upload credentials never reach the client
• Structured metadata support for attaching and querying custom fields on uploaded assets
• A pluggable cache layer (lib/cache) for storing derived-URL lookups

Common Use Cases

• Accepting user-uploaded images or videos in a Node.js backend and storing them on Cloudinary instead of local disk or a bare object store
• Generating on-the-fly responsive image URLs (auto format, auto quality, fixed aspect crop) for a web frontend without maintaining separate image-resizing infrastructure
• Signing upload parameters server-side so a browser can upload directly to Cloudinary without exposing the API secret
• Searching and moderating a large media library programmatically (e.g. a CMS or admin dashboard listing and tagging assets)
• Migrating large or long-running video uploads via the SDK’s large-file upload helpers instead of hand-rolled chunked HTTP requests

Under The Hood

Architecture The entry point cloudinary.js re-exports lib/cloudinary.js, which aggregates the original v1 surface (config, uploader, api, utils, cache, auth_token, preloaded_file). lib/v2/index.js spreads that v1 object and overlays api.js, uploader.js, search.js, and search_folders.js to form the modern namespaced API without breaking v1 callers. Every operation funnels through lib/api_client (call_api.js, call_account_api.js, call_analysis_api.js, execute_request.js), which builds and signs HTTP requests using Node’s built-in http/https modules rather than an external client library; lib/config.js centralizes resolution of cloud_name/api_key/api_secret from either a CLOUDINARY_URL environment variable or explicit config objects, using nested-key assignment helpers shared across the codebase. Upload-specific dispatch lives in upload_stream.js and utils/handleFileParameter.js, which inspect whether the file argument is a remote URL, a local path, or a stream and route accordingly. The module structure is flat and organized by concern (upload vs. api vs. search vs. utils) rather than by architectural layer, so the call_api signing/request path is a single choke point that every SDK operation passes through.

Tech Stack Plain JavaScript at runtime (Node.js >=9, with CI exercising versions 9 through 26) with hand-maintained TypeScript definitions shipped separately under types/. The only runtime dependency is lodash (^4.17.23), used throughout for object merging and collection helpers in config and param building; there is no external HTTP client dependency, relying instead on Node’s native http/https/url/stream modules. Dev tooling includes Mocha with expect.js and Sinon for tests, nyc for coverage, ESLint (airbnb-base config) for linting, jsdoc for generated docs, dtslint for validating the bundled .d.ts file, and webpack-cli for bundling; orchestration runs through shell scripts under tools/scripts/ rather than a JS task runner.

Code Quality The repo has 26 unit test files and 19 integration test files under test/unit and test/integration, using Mocha/expect.js/Sinon (with jsdom for the browser-signing helpers) — an exercised suite, not just smoke tests. CI runs the full suite via npm run test-with-temp-cloud across ten Node versions (9 through 26), which is a strong maintenance-consistency signal even without deep coverage numbers reported. There is no compiler-enforced type safety in the implementation itself (it’s plain JS), though the separately maintained types/index.d.ts is lint-checked with dtslint. ESLint’s airbnb-base config enforces consistent naming and style, and explicit guard helpers (ensureOption, ensurePresenceOf) surface missing-config errors rather than failing silently.

API Design The standout design choice is the dual API surface: the original flat require('cloudinary') module has been preserved unbroken since 2012, while require('cloudinary').v2 layers uploader/api/search on top — a long-lived backward-compatibility strategy that’s unusual for an SDK this old. The dependency footprint is minimal (only lodash), avoiding version churn from an HTTP client dependency. The upload path collapses what could be three separate methods (upload-from-path, upload-from-URL, upload-from-stream) into a single upload() call that inspects its file argument, reducing caller boilerplate. Documentation is unusually agent-aware for a package this age — a dedicated docs/ folder with topic guides, a context7.json, and both AGENTS.md and CLAUDE.md files specifically written to onboard coding agents using the installed package.