Programmable Media

JavaScript SDK

Last updated: Aug-04-2024

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

Tip

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

On this page:

Overview
- Quick example
Get started with the JavaScript SDK
Transformations
Plugins
Sample projects

Rate this page:

Overview

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.

Note

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.

You might also want to know...

Interested in version information?

Want to learn about the architecture?

Quick example

This example shows a transformation URL being created using the @cloudinary/url-gen package.

import {Cloudinary} from "@cloudinary/url-gen";

// Import required actions.
import {sepia} from "@cloudinary/url-gen/actions/effect";

// 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
.effect(sepia());  // Apply a sepia effect.

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

This code creates the HTML required to deliver the front_face.jpg image with the sepia effect applied.

You can apply more than one transformation at a time (see chained transformations) to give more interesting results:

@cloudinary/url-gen 1.x

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 { byAngle } from "@cloudinary/url-gen/actions/rotate";
import { format } from "@cloudinary/url-gen/actions/delivery";
import { opacity, brightness } from "@cloudinary/url-gen/actions/adjust";
import { image } from "@cloudinary/url-gen/qualifiers/source";
import { Position } from "@cloudinary/url-gen/qualifiers/position";
import { png } from "@cloudinary/url-gen/qualifiers/format";
import { focusOn, compass } from "@cloudinary/url-gen/qualifiers/gravity";
import { face } from "@cloudinary/url-gen/qualifiers/focusOn";

new CloudinaryImage("front_face")
  .resize(
    thumbnail()
      .width(150)
      .height(150)
      .gravity(focusOn(face()))
  )
  .roundCorners(byRadius(20))
  .effect(sepia())
  .overlay(
    source(
      image("cloudinary_icon").transformation(
        new Transformation()
          .resize(scale().width(50))
          .adjust(opacity(60))
          .adjust(brightness().level(90))
      )
    ).position(
      new Position()
        .gravity(compass("south_east"))
        .offsetX(5)
        .offsetY(5)
    )
  )
  .rotate(byAngle(10))
  .delivery(format(png()));

Open In Transformation Builder

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)

Tip

There are alternative ways to apply transformations to your images, for example:

import { transformationStringFromObject } from "@cloudinary/url-gen";

const transformation = transformationStringFromObject([
  {gravity: "face", height: 150, width: 150, crop: "thumb"},
  {radius: 20},
  {effect: "sepia"},
  {overlay: "cloudinary_icon"},
  {width: 50, crop: "scale"},
  {opacity: 60},
  {effect: "brightness:90"},
  {flags: "layer_apply", gravity: "south_east", x: 5, y: 5},
  {angle: 10},
  {fetch_format: "png"}
  ]);
myImage.addTransformation(transformation);

Learn more about transformations

See all possible transformations in the Transformation URL API reference.
See all JavaScript transformation actions and qualifiers in the Transformation Builder reference.
See more examples of image and video transformations using the js-url-gen v1.x library.

Tip

Take a look at our JavaScript sample projects to help get you started.

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.

JavaScript SDK installation and configuration video tutorial

Watch this video tutorial to see how to install and configure the JavaScript SDK:

Installation

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

npm i @cloudinary/url-gen

Configuration

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

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:

// 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: 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 delivery hostname, and want to generate a secure URL (HTTPS):


// 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:

// 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: https://res.cloudinary.com/demo/image/upload/docs/shoes
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.

Transformations

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.

The @cloudinary/url-gen package 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.

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

Plugins

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