JavaScript SDK v2 (Beta)

Important
The JavaScript SDK v2 is currently in BETA. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.

Roadmap:

  • This is the first release of the JavaScript Base, Angular and React packages.
  • Future releases will include other frameworks such as Vue.js.

Key benefits:

Compared to JavaScript SDK v1, JavaScript SDK v2 provides:

  • A new action-based syntax, designed to make building delivery URLs and transformations more logical and discoverable.
  • A smaller bundle size - you only need to import what you want to use.

Quick start

If you're ready to get coding, jump straight to our Quickstart guide. Otherwise, keep reading to get a more in-depth understanding of the JavaScript SDK v2.

Overview

Cloudinary's JavaScript SDK v2 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.

Related topics
This guide relates to the latest release of the Cloudinary JavaScript SDK v2 libraries:

For details on all new features and fixes from previous versions, see the cloudinary-js-base CHANGELOG and the frontend-frameworks CHANGELOG.

Notes

  • The following instructions describe Cloudinary's JavaScript client-side library. For the server side Node.js library, which also covers upload and admin functionality, see the Node.js documentation.
  • 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.

Architecture

The cloudinary-js-base library contains all the functionality needed to transform, optimize and deliver images and videos from your Cloudinary account. The frontend-frameworks libraries work together with the cloudinary-js-base library, leveraging the functionality provided by cloudinary-js-base, while allowing you to work in your framework of choice.

Javascript Architecture

Two GitHub repositories provide all the functionality:

  • cloudinary-js-base 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 cloudinary-js-base functionality is installed through @cloudinary/base.
  • 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/angular.

Full example

This example shows a transformation URL being created using the cloudinary-js-base library. The different framework tabs show how to render the URL using those frameworks. It demonstrates the use of tree shaking to reduce the bundle size, which explains why there are so many import statements.

JS:
Copy to clipboard
import {Cloudinary} from "@cloudinary/base";
import {Transformation} from "@cloudinary/base";

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

// Import required qualifiers.
import {face} from "@cloudinary/base/qualifiers/focusOn";
import {focusOn} from "@cloudinary/base/qualifiers/gravity";
import {image} from "@cloudinary/base/qualifiers/source";
import {Position} from "@cloudinary/base/qualifiers/position";
import {southEast} from "@cloudinary/base/qualifiers/compass";
import {compass} from "@cloudinary/base/qualifiers/gravity";
import {png} from "@cloudinary/base/qualifiers/format";


// 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.
myImage
.resize(thumbnail().width(150).height(150).gravity(focusOn(face())))  // Crop the image.
.roundCorners(byRadius(20))    // Round the corners.
.effect(sepia())  // Apply a sepia effect.
.overlay(   // Overlay the Cloudinary logo.
  source(
    image('cloudinary_icon_blue')
      .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(southEast())).offsetX(5).offsetY(5))   // Position the logo.
)
.rotate(byAngle(10))  // Rotate the result.
.delivery(format(png()));   // Deliver as PNG. */

// Render the image in an 'img' element.
const imgElement = document.createElement('img');
imgElement.src = myImage.toURL();
React:
Copy to clipboard
import React, {Component} from 'react'
import {AdvancedImage} from '@cloudinary/react';
import {Cloudinary} from "@cloudinary/base";
import {Transformation} from "@cloudinary/base";

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

// Import required qualifiers.
import {face} from "@cloudinary/base/qualifiers/focusOn";
import {focusOn} from "@cloudinary/base/qualifiers/gravity";
import {image} from "@cloudinary/base/qualifiers/source";
import {Position} from "@cloudinary/base/qualifiers/position";
import {southEast} from "@cloudinary/base/qualifiers/compass";
import {compass} from "@cloudinary/base/qualifiers/gravity";
import {png} from "@cloudinary/base/qualifiers/format";

const App = () => {

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

  // Use the image with public ID, 'front_face'.
  const myImage = cld.image('front_face');

  // Apply the transformation.
  myImage
  .resize(thumbnail().width(150).height(150).gravity(focusOn(face())))  // Crop the image.
  .roundCorners(byRadius(20))    // Round the corners.
  .effect(sepia())  // Apply a sepia effect.
  .overlay(   // Overlay the Cloudinary logo.
    source(
      image('cloudinary_icon_blue')
        .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(southEast())).offsetX(5).offsetY(5))   // Position the logo.
  )
  .rotate(byAngle(10))  // Rotate the result.
  .delivery(format(png()));   // Deliver as PNG. */

  // Render the transformed image in a React component.
  return (
    <div>
      <AdvancedImage cldImg={myImage} />
    </div>
  )
};
Angular:
Copy to clipboard
// In your app.module.ts inject the library:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule,
],
...

// In your component.ts use `@cloudinary/base` to generate your transformations.

import {Cloudinary, CloudinaryImage} from "@cloudinary/base";
import {Transformation} from "@cloudinary/base";

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

// Import required qualifiers.
import {face} from "@cloudinary/base/qualifiers/focusOn";
import {focusOn} from "@cloudinary/base/qualifiers/gravity";
import {image} from "@cloudinary/base/qualifiers/source";
import {Position} from "@cloudinary/base/qualifiers/position";
import {southEast} from "@cloudinary/base/qualifiers/compass";
import {compass} from "@cloudinary/base/qualifiers/gravity";
import {png} from "@cloudinary/base/qualifiers/format";

export class AppComponent {
  img: CloudinaryImage

  ngOnInit() {

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

    // Use the image with public ID, 'front_face'.
    this.img = cld.image('front_face');

    // Apply the transformation.
    this.img
    .resize(thumbnail().width(150).height(150).gravity(focusOn(face())))  // Crop the image.
    .roundCorners(byRadius(20))    // Round the corners.
    .effect(sepia())  // Apply a sepia effect.
    .overlay(   // Overlay the Cloudinary logo.
      source(
        image('cloudinary_icon_blue')
          .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(southEast())).offsetX(5).offsetY(5))   // Position the logo.
    )
    .rotate(byAngle(10))  // Rotate the result.
    .delivery(format(png()));   // Deliver as PNG. */
  }
}

// In your view add the advanced-image component and pass your Cloudinary image.
<advanced-image [cldImg]="img"></advanced-image>

sample transformation

This code creates 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 is generated from the above code:

Getting started with cloudinary-js-base

If you're using a frontend framework, jump straight to the relevant get started.

If you're using JavaScript without a framework, follow the instructions in the next sections for installation and setup.

Installation

Install the cloudinary/base package using the NPM package manager:

Copy to clipboard
npm install --save @cloudinary/base

Configuration

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

Note
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/base";

// 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: https://res.cloudinary.com/demo/image/upload/sample
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: 'www.example.com', 
    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/base/config/URLConfig";
import CloudConfig from "@cloudinary/base/config/CloudConfig";
import {CloudinaryImage} from '@cloudinary/base/assets/CloudinaryImage';

// 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('sample', cloudConfig, urlConfig);

// This returns: https://res.cloudinary.com/demo/image/upload/sample
const myURL = myImage.toURL();

Sample projects

View these sample projects for complete code examples:

✔️ Feedback sent!

Rate this page: