JavaScript migration guide

Introduction

Cloudinary's JavaScript SDK v2 (Beta) is designed to provide a simpler and more enhanced developer experience. This guide explains how to migrate your JavaScript code from the cloudinary-core library (JavaScript SDK v1) to the js-url-gen library (JavaScript SDK v2).

Key improvements in the JavaScript SDK v2:

  • A new action-based syntax, designed to make building delivery URLs and transformations more logical and discoverable.
    • When compiled to the final delivery URL, each action (including any action qualifiers) represents a different component (separated by a '/'), for example: /c_scale,w_400/f_auto/q_auto/, rather than /c_scale,f_auto,q_auto,w_400/.
  • Newly added autocomplete to list options and parameters and ensure only those that are supported can be used together.
  • A smaller bundle size - you only need to import what you want to use.

Things to know before migrating to the JavaScript SDK v2

The action-based syntax used in the JavaScript SDK v2 may cause URLs to be formed differently from those generated by the JavaScript SDK v1.

For example:

  • URL generated with SDK v1:
    https://res.cloudinary.com/demo/image/upload/c_scale,f_auto,q_auto,w_400/sample.jpg
  • URL generated with SDK v2:
    https://res.cloudinary.com/demo/image/upload/c_scale,w_400/f_auto/q_auto/sample.jpg


Even if the delivered media file looks and behaves identically, changes to URLs can have the following implications:

  • You may see a one-time increase in transformation counts
  • You may see a one-time increase in storage usage for the new derived assets
  • You may see a one-time increase in add-on usage when add-on transformation parameters are used in the URL
  • CDN caches may need to be warmed with the new derived assets
  • If strict transformations are enabled on your account, you need to allow the new transformations
  • If you require transformations to be generated eagerly, for example long videos, you need to regenerate these via the latest SDK, using the eager parameter of the explicit method.

To reduce the impact of all of the above, we recommend using the createCloudinaryLegacyURL method for your existing transformation URLs, especially if your existing app delivers a large number of transformed assets. This maintains the formations of the transformations, so the URLs remain the same.

The createCloudinaryLegacyURL function supports only transformation and configuration parameters. It does not help to migrate HTML tags, responsive, placeholder, transparent video or jQuery functionality.

For all new transformation URLs that you add to your application, we recommend using the new action-based SDK syntax offered by the latest version of the SDK.

For full documentation on the JavaScript SDK v2, see the JavaScript SDK v2 guide.

Key considerations

The cloudinary-core library is very different from the @cloudinary/url-gen library in its architecture and usage, so migration paths depend on your current usage of the cloudinary-core library.

You can use both the cloudinary-core and @cloudinary/url-gen packages in your application concurrently, so although not recommended for the long term due to the increased bundle size, you could start by integrating @cloudinary/url-gen into your application and slowly migrate your functionality piece by piece, until you are able to remove all cloudinary-core functionality.

The instructions in this guide assume you are using JavaScript within a modular environment.

Installation

Install the @cloudinary/url-gen package using:

Copy to clipboard
npm i @cloudinary/url-gen --save

Migrating Cloudinary instance configuration

Using the JavaScript SDK v1, you may be configuring your cloud name and other configuration parameters in a Cloudinary instance. There is an equivalent Cloudinary object in @cloudinary/url-gen.

For example, this cloudinary-core code:

Copy to clipboard
// SDK v1
import {Cloudinary} from "cloudinary-core";

var cl = new Cloudinary({cloud_name: "demo", secure: true});

is similar to this @cloudinary/url-gen code:

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

var cl = new Cloudinary({cloud: {cloudName: "demo"}, url: {secure: true}});

Migrating asset instance configuration

You can also set configuration parameters in the imageTag or url methods in the JavaScript SDK v1. This is similar to setting the parameters on a per asset instance in @cloudinary/url-gen.

For example, setting cloud_name in a URL:

Copy to clipboard
// SDK v1
import {Cloudinary} from cloudinary-core;

cl.url("sample", {cloud_name: "demo"});

is similar to setting cloudName in a CloudinaryImage:

Copy to clipboard
// SDK v2
import {CloudinaryImage} from "@cloudinary/url-gen";

const myImage = new CloudinaryImage("sample", {cloudName: "demo"});

Note
If you use the Cloudinary instance configuration, you don't need to add configuration parameters to your asset instances:

Copy to clipboard
const myImage = cl.image("sample");

Migrating delivery URLs

Using cloudinary-core, configuration and transformation parameters are specified in JSON syntax, for example:

Copy to clipboard
// SDK v1
cl.imageTag("actor", {
  cloud_name: "demo",
  transformation: [
  {effect: "cartoonify"},
  {radius: "max"},
  {effect: "outline:100", color: "lightblue"},
  {background: "lightblue"},
  {height: 300, crop: "scale"}
  ]}).toHtml();

Using @cloudinary/url-gen, you can use the createCloudinaryLegacyURL function to pass in the same JSON and return the same URL, which you can then use as the source for your image tag. Configuration parameters, such as cloud_name, should be included in the function call as this is simply a helper function to build the delivery URL.

Copy to clipboard
// SDK v2
import {createCloudinaryLegacyURL} from "@cloudinary/url-gen";

const migrateUrl = createCloudinaryLegacyURL("actor", {
    cloud_name: "demo",
    transformation: [
    {effect: "cartoonify"},
    {radius: "max"},
    {effect: "outline:100", color: "lightblue"},
    {background: "lightblue"},
    {height: 300, crop: "scale"}
    ]
});

const imgElement = document.createElement('img');
imgElement.src = migrateUrl;
// Append the image element to the DOM, for example:
document.getElementById('div1').appendChild(imgElement);
Copy to clipboard
<!--Where div1 is the ID of a div element in your HTML file-->
<div id="div1"></div>

Caution
If you have a large number of assets, we recommend you migrate using the createCloudinaryLegacyURL method. If you replace your existing transformations using the new SDK transformation syntax, you may find your URLs are generated in a slightly different way. See Things to know before migrating to the JavaScript SDK v2, for the implications of these changes to transformation URLs.

For all new Cloudinary delivery URLs, you should start to use the @cloudinary/url-gen syntax:

Copy to clipboard
// SDK v2
import {CloudinaryImage} from '@cloudinary/url-gen';
import {scale} from "@cloudinary/url-gen/actions/resize";
import {outline, cartoonify} from "@cloudinary/url-gen/actions/effect";
import {max} from "@cloudinary/url-gen/actions/roundCorners";
import {outer} from "@cloudinary/url-gen/qualifiers/outlineMode";

const myImage = new CloudinaryImage('actor', {cloudName: 'demo'});

// Apply the transformation.
myImage
  .effect(cartoonify())
  .roundCorners(max())
  .effect(outline().mode(outer()).width(100).color("lightblue"))
  .backgroundColor("lightblue")
  .resize(scale().height(300));

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

The resulting URL is:

Transformed actor

Migrating responsive functionality

If you are using the responsive functionality offered by cloudinary-core, then you will have to replace this code entirely for the JavaScript SDK v2.

For this, you need to install the @cloudinary/html package from frontend-frameworks:

Copy to clipboard
npm i @cloudinary/html --save

Then, use the responsive plugin in an HTMLImageLayer:

Copy to clipboard
// SDK v2
import {responsive, HtmlImageLayer} from "@cloudinary/html";
import {CloudinaryImage} from "@cloudinary/url-gen";

// Create a new HTML image element and inject it to the page
const imgTag = document.createElement('img');
document.body.appendChild(imgTag);

// Create your image
const myImage = new CloudinaryImage('sample', {cloudName: 'demo'});

// Wire up Cloudinary to work with that element and use the responsive plugin
new HtmlImageLayer(imgTag, myImage, [responsive()]);

Related topics

✔️ Feedback sent!

Rate this page: