JavaScript SDK

Last updated: Nov-14-2022

This page provides an in-depth introduction to the JavaScript SDK.

If you're ready to get coding, jump straight to our quick start.


Cloudinary's JavaScript SDK provides simple, yet comprehensive image and video transformation, optimization, and delivery capabilities that you can implement using code that integrates seamlessly with your existing JavaScript or JS-based framework application.

In this guide you'll learn how to get started with the JavaScript SDK, but if you are not familiar with Cloudinary, we advise starting with the Developer get started guide for a high-level overview of integrating Cloudinary into your code, and an introduction to the main concepts.

You may also find our Glossary helpful to understand Cloudinary-specific terminology.

Related topics
This guide relates to the latest release of the js-url-gen v1.x library:

  • For details on all new features and fixes from previous minor versions, see the js-url-gen CHANGELOG.
  • For details on migrating to this SDK from the legacy JavaScript SDK, see the JavaScript migration guide.
  • By default, URLs generated with this SDK include an appended SDK-usage query parameter. Cloudinary tracks aggregated data from this parameter to improve future SDK versions and no individual data is collected. If needed, you can disable the url=>analytics configuration option. Learn more.

This guide describes Cloudinary's js-url-gen frontend library. For the backend Node.js library, which also covers upload and admin functionality, see the Node.js documentation.


The JavaScript SDK can be used independently or together with a frontend framework, such as Angular or React. It contains all the functionality needed to transform, optimize and deliver images and videos from Cloudinary. The frontend framework libraries work together with this SDK, leveraging the functionality that it provides, while allowing you to work in your framework of choice.

Two GitHub repositories provide all the functionality:

  • js-url-gen contains all the functionality required to create delivery URLs for your Cloudinary assets based on the configuration and transformation actions that you specify. All the js-url-gen functionality is installed through the @cloudinary/url-gen package.
  • frontend-frameworks contains the framework libraries and plugins that can be used to render images and videos on your site. There are different installation packages for each framework, so for example, React is installed through @cloudinary/react, and Angular is installed through @cloudinary/ng.

The js-url-gen library installs an additional transformation-builder-sdk library as a dependency, which handles the transformation generation part of the URL.

You can use the Transformation Builder reference to find all available transformations, syntax and examples.


We recommend importing transformation actions and qualifiers from @cloudinary/url-gen, for example:

Copy to clipboard
import {scale} from '@cloudinary/url-gen/actions/resize';

However, it's also possible to import them directly from the transformation-builder-sdk library, by installing that library too, for example:

Copy to clipboard
npm install @cloudinary/transformation-builder-sdk
Copy to clipboard
import {scale} from '@cloudinary/transformation-builder-sdk/actions/resize';

Full example

This example shows a transformation URL being created using the @cloudinary/url-gen package. It demonstrates the use of tree shaking to reduce the bundle size, which explains why there are so many import statements.

Copy to clipboard
import {Cloudinary} from "@cloudinary/url-gen";
import {Transformation} from "@cloudinary/url-gen";

// Import required actions.
import {thumbnail, scale} from "@cloudinary/url-gen/actions/resize";
import {byRadius} from "@cloudinary/url-gen/actions/roundCorners";
import {sepia} from "@cloudinary/url-gen/actions/effect";
import {source} from "@cloudinary/url-gen/actions/overlay";
import {opacity,brightness} from "@cloudinary/url-gen/actions/adjust";
import {byAngle} from "@cloudinary/url-gen/actions/rotate";

// Import required qualifiers.
import {image} from "@cloudinary/url-gen/qualifiers/source";
import {Position} from "@cloudinary/url-gen/qualifiers/position";
import {compass} from "@cloudinary/url-gen/qualifiers/gravity";
import {focusOn} from "@cloudinary/url-gen/qualifiers/gravity";
import {FocusOn} from "@cloudinary/url-gen/qualifiers/focusOn";

// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'

// Instantiate a CloudinaryImage object for the image with public ID, 'front_face'.
const myImage = cld.image('front_face');

// Perform the transformation.
.resize(thumbnail().width(150).height(150).gravity(focusOn(FocusOn.face()))) // Crop the image.
.roundCorners(byRadius(20))    // Round the corners.
.effect(sepia())  // Apply a sepia effect.
.overlay(   // Overlay the Cloudinary logo.
      .transformation(new Transformation()
      .resize(scale(50)) // Resize the logo.
        .adjust(opacity(60))  // Adjust the opacity of the logo.
      .adjust(brightness(200)))  // Adjust the brightness of the logo.       
  .position(new Position().gravity(compass('south_east')).offsetX(5).offsetY(5))   // Position the logo.
.rotate(byAngle(10))  // Rotate the result.
.format('png');   // Deliver as PNG. */

// Render the image in an 'img' element.
const imgElement = document.createElement('img');
imgElement.src = myImage.toURL();

sample transformation

This code generates the URL required to deliver the front_face.jpg image with the following transformations applied:

  • Crop to a 150x150 thumbnail using face-detection gravity to automatically determine the location for the crop
  • Round the corners with a 20 pixel radius
  • Apply a sepia effect
  • Overlay the Cloudinary logo on the southeast corner of the image (with a slight offset). The logo is scaled down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%)
  • Rotate the resulting image (including the overlay) by 10 degrees
  • Convert and deliver the image in PNG format (the originally uploaded image was a JPG)

And here's the URL that's generated from the above code:

Learn more about transformations

Get started with the JavaScript SDK

If you're using a frontend framework, jump straight to the relevant Get started docs:

If you're using JavaScript without one of the above frameworks, follow the instructions in the next sections for installation and setup.


Install the @cloudinary/url-gen package using the NPM package manager:

Copy to clipboard
npm i @cloudinary/url-gen


You can specify the configuration parameters that are used to create the delivery URLs, either using a Cloudinary instance or per image/video instance.

Specify the configuration parameters in camelCase, for example cloudName.

Cloudinary instance configuration

If you want to use the same configuration to deliver all your media assets, it's best to set up the configuration through a Cloudinary instance, for example:

Copy to clipboard
// Import the Cloudinary class.
import {Cloudinary} from "@cloudinary/url-gen";

// Create a Cloudinary instance and set your cloud name.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'

// cld.image returns a CloudinaryImage with the configuration set.
const myImage = cld.image('sample'); // sample is the public ID of the image.

// This returns:
const myURL = myImage.toURL();

You can set other configuration parameters related to your cloud and URL as required, for example, if you have your own custom domain name, and want to generate a secure URL (HTTPS):

Copy to clipboard
// Create a Cloudinary instance, setting some Cloud and URL configuration parameters.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'
  url: {
    secureDistribution: '', 
    secure: true 

Asset instance configuration

If you need to specify different configurations to deliver your media assets, you can specify the configuration per image/video instance, for example:

Copy to clipboard
// Import the configuration classes.
import {URLConfig} from "@cloudinary/url-gen";
import {CloudConfig} from "@cloudinary/url-gen";
import {CloudinaryImage} from '@cloudinary/url-gen';

// Set the Cloud configuration and URL configuration
const cloudConfig = new CloudConfig({cloudName: 'demo'});
const urlConfig = new URLConfig({secure: true});

// Instantiate a new image passing the Cloud and URL configurations
const myImage = new CloudinaryImage('docs/shoes', cloudConfig, urlConfig);

// This returns:
const myURL = myImage.toURL();

Build environments

Some build environments require additional configuration:

  • Rollup + Vanilla JS: install and use @rollup/node-resolve.
  • Next.js + Vanilla JS: install and use moxystudio/next-compile-node-modules (or some other similar solution).
  • TypeScript + Webpack: set "moduleResolution": "node" in the TSConfig file.


The @cloudinary/url-gen package simplifies the generation of transformation URLs, and includes special components and directives for easy embedding of assets in your JavaScript application.

Image with several transformations applied

To find out more about transforming your assets using the @cloudinary/url-gen package, see:


The @cloudinary/html package from frontend-frameworks provides plugins to render the media on your site in the most optimal way and improve your user's experience by automating media tasks like lazy loading, responsive images and more.

Sample projects

Try out the examples in these code explorers:

✔️ Feedback sent!

Rate this page: