Cloudinary Tiny JS
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.
cloudinary-tiny-js
provides the same commonly used image transformation features at a fraction of the size and without
any dependencies.
Video transformations are not currently supported nor are some advanced configuration options. It
may also fall short on some advanced image transformations. If you need this functionality, please
submit PRs with references to the relevant Cloudinary documentation.
Usage
Basic configuration
The default export is a configuration function returning another function for building Cloudinary
URLs. Configuration option names follow the documentation on
Transforming media assets using dynamic URLs
and Private CDNs and CNAMEs
. Only the cloudName
is required. Defaults are shown below.
import cloudinary from 'cloudinary-tiny-js'
const cl = cloudinary({
cloudName: 'demo',
assetType: 'image',
deliveryType: 'upload',
secure: true,
cdnSubdomain: 'res',
cname: 'res.cloudinary.com',
imageTransformDefaults: { quality: 'auto' },
})
const imageUrl = cl('sample.png', { width: 150 })
expect(imageUrl).toBe('https://res.cloudinary.com/demo/image/upload/q_auto,w_150/sample.png')
Image transformations
All image transformations documented in the
Transformation URL API reference
are supported except for arithmetic operators, conditionals and variables.
To create a resource URL, call the function returned by the configuration function with a public ID and optional image
transformation options:
const basicUrl = cl('sample.png')
expect(basicUrl).toBe('https://res.cloudinary.com/demo/image/upload/v1/sample.png')
const resizedUrl = cl('sample.png', { width: 150, height: 100 })
expect(resizedUrl).toBe('https://res.cloudinary.com/demo/image/upload/w_150,h_100/v1/sample.png')
Other options that can be provided alongside transform options are:
const url = cl('http://example.com/sample.dat', {
transformations: undefined,
assetType: 'raw',
deliveryType: 'fetch',
version: 742,
})
expect(url).toBe('http://res.cloudinary.com/demo/raw/fetch/v742/http://example.com/sample.dat')
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 transformations
property along with other options.
This will generate the URL of the first example in the
Image transformation reference:
const transformations = [
{ width: 220, height: 140, crop: 'fill' },
{ overlay: 'brown_sheep', width: 220, height: 140, x: 220, crop: 'fill' },
{ overlay: 'horses', width: 220, height: 140, x: -110, y: 140, crop: 'fill' },
{ overlay: 'white_chicken', width: 220, height: 140, x: 110, y: 70, crop: 'fill' },
{ overlay: 'butterfly.png', height: 200, x: -10, angle: 10 },
{ width: 400, height: 260, radius: 20, crop: 'crop' },
{ overlay: 'text:Parisienne_35_bold:Memories%20from%20our%20trip', color: '#990C47', y: 155 },
{ effect: 'shadow' },
]
const url = cl('yellow_tulip.jpg', transformations)
const url = cl('yellow_tulip.jpg', {
version: 423,
transformations,
})
Specifying default image transformations
The imageTransformDefaults
property provides a convenient way to include certain transform options in all image
transforms. For example, specifying auto format, quality and width for all images can be achieved by passing:
const cl = cloudinary({
cloudName: 'demo',
imageTransformDefaults: {
format: 'auto',
quality: 'auto',
width: 'auto',
},
})
const imageUrl = cl('sample.png', { aspectRatio: '16:9' })
expect(imageUrl).toBe('https://res.cloudina.../f_auto,q_auto,w_auto,ar_16:9/v1/sample.png')
Override any default value by passing a replacement value or remove it from the URL by passing undefined
:
const cl = cloudinary({
cloudName: 'demo',
imageTransformDefaults: {
format: 'auto',
quality: 'auto',
width: 'auto',
},
})
const imageUrl = cl('sample.png', { aspectRatio: '16:9', width: 150, quality: undefined })
expect(imageUrl).toBe('https://res.cloudina.../f_auto,ar_16:9,w_150/v1/sample.png')
Transformation parameter validation
Typings should help to provide valid parameter values in most cases, but errors will also be thrown on invalid parameter
values in development, for example:
cl('sample.jpg', { radius: 'round' })
Some exceptions are the effect
, overlay
and underlay
values which are not validated.
Building for production
When building for production ensure process.env.NODE_ENV === 'production'
so the validation logic can be removed from
the bundle during minification.
Contributing
The most important configuration and image transformation features of Cloudinary should be supported, but if anything is
missing please submit issues or PRs with references to the relevant Cloudinary documentation.
License
MIT