Cloudinary is a cloud service that offers a solution to a web application's entire image management pipeline. For client-side image management Cloudinary provides the
cloudinary-core library for conveniently compiling transform options to asset URLs. The problem is that it's a massive library often used to simply convert an object of properties to a string.
Reviewing the Webpack bundle analyzer plugin output shows that if the
cloudinary-core library is unwittingly included with the default
import cloudinary from 'cloudinary-core'it includes a bundled copy of
lodash as well for a combined parsed size of 114 KB and 38 KB gzipped. The proposed solution is to import
cloudinary-core/cloudinary-core-shrinkwrapwhich does not bundle the entire
lodash library, but it is still 62 KB and 20 KB gzipped.
@gilbarbara/cloudinary provides the same commonly used media transformation features
at a fraction of the size and without any dependencies: only 3.62 KB and 1.5 KB gzipped.
That is a 92.5% reduction in size from the shrink-wrapped version.
npm install @gilbarbara/cloudinary
The default import is a factory function taking
of which the only required parameter is the
;const cl = ;const imageUrl = ;;
All image transforms documented in the Image transformation reference are supported except for the last three: arithmetic operators, conditionals and variables.
Most video transforms documented in the video_manipulation_and_delivery are supported except for the concatenation and video overlays
The factory function supports these configuration options and defaults:
const cl =
secure option specifies generating
https URLs instead of
http; this is on by
default since most sites use
https these days; disable globally by passing
or case by case by passing
secure: false on the transform options.
cname option to specify a different CNAME for use with an advanced plan with
a private CDN distribution and custom CNAME.
cdnSubdomain specifies whether to automatically build URLs with multiple CDN sub-domains.
See this blog post
for more details. The caveat is that public IDs must consistently be hashed to random numbers
between 1 and 5 to assign different sub-domains.
cloudinary-core uses this
CRC32 implementation which is 7KB all on its own. For this reason it is not included in this library and if you wish to enable this feature instead of passing
cdnSubdomain you pass your own CRC-type function
(string) => number. The modulus 5 of the output will be used to assign a subdomain.
Specifying default transform options
defaults property provides a convenient way to include certain transform options
in all image transforms. For example, specifying auto fetch format, quality and width for
all images can be achieved by passing:
const cl =;const imageUrl = ;;
Override any default value by passing a replacement value or removed it from the URL by
const cl =;const imageUrl = ;;
If primarily raw resource URLs will be generated or if most images would be, for example,
fetched from Facebook the default
type property defaults can also be
overridden for convenience:
const clRaw =
To create a resource URL call the function returned by the factory function with a public ID and optional transform options:
const basicUrl = ;;const resizedUrl = ;;
Other options that can be provided alongside transform options are:
const url =;;
To perform multiple transformations an array of transform objects can be passed; the
array can be passed directly as the second parameter or on the
transform property if other
options are to be provided.
This will generate the URL of the first example in the Image transformation reference:
const url =;// Or with other optionsconst url =;
Transformation parameter validation
The library attempts to be helpful in catching invalid parameter values by providing insightful errors, for example:
;// Throws:// Cloudinary Image :: radius should be a number, 'max' or have the form x[:y[:z[:u]]], received: 'round'
The exception is the
effect transform which already has numerous options with more added regularly.
The most important configuration and image transformation features of Cloudinary should be supported, but if anything is missing please point it out with an issue or contribute the feature.
PRs are welcome.
Free to use under the MIT license.
This is a fork from Marnus Weststrate's cloudinary-tiny-js package. Thanks! ❤️