JavaScript migration guide

Introduction

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

Key improvements in the js-url-gen library:

• 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.

For full documentation on using the js-url-gen library, see the JavaScript SDK 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:

Migrating Cloudinary instance configuration

Using the legacy JavaScript SDK, 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:

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

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:

is similar to setting cloudName in a CloudinaryImage:

Migrating delivery URLs

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

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.

For objects, such as Layer(), TextLayer(), FetchLayer() and Transformation(), you need to import the relevant classes from @cloudinary/url-gen/backwards.

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

The resulting URL is:

Migrating responsive functionality

If you are using the responsive functionality offered in cloudinary-core, you will have to replace this code entirely when using the latest JavaScript SDK.

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

Then, use the responsive plugin in an HTMLImageLayer: