> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript migration guide


## Introduction

Cloudinary's [latest JavaScript SDK](javascript_integration) 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](https://github.com/cloudinary/cloudinary_js#cloudinary-core) library (legacy JavaScript SDK) to the [js-url-gen](https://github.com/cloudinary/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](image_transformations#parameter_types)) 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.

> **INFO**:
>
> :title=Things to know before migrating to the js-url-gen library
> The action-based syntax used in the `js-url-gen` library may cause URLs to be formed differently from those generated by the `cloudinary-core` (legacy) library. 
> For example: 

> * **URL generated with the cloudinary-core (legacy) library:**`https://res.cloudinary.com/demo/image/upload/c_scale,f_auto,q_auto,w_400/sample.jpg`

> * **URL generated with the js-url-gen library:** `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](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](control_access_to_media#strict_transformations) are enabled for your product environment (in the Security page of your Console Settings), you need to allow the new transformations

> * If you require transformations to be generated [eagerly](eager_and_incoming_transformations#eager_transformations), for example long videos, you need to regenerate these via the latest SDK, using the `eager` parameter of the [explicit](image_upload_api_reference#explicit_method) method.
> To reduce the impact of all of the above, we recommend using the [createCloudinaryLegacyURL](#migrating_delivery_urls) 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 using the `js-url-gen` library, see the [JavaScript SDK guide](javascript_integration).

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

```
npm i @cloudinary/url-gen
```

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

```js
// Legacy SDK
import {Cloudinary} from "cloudinary-core";

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

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

```js
// Latest SDK
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:

```js
// Legacy SDK
import {Cloudinary} from "cloudinary-core";

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

is similar to setting `cloudName` in a `CloudinaryImage`:

```js
// Latest SDK
import {CloudinaryImage} from "@cloudinary/url-gen";

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

> **NOTE**: If you use the [Cloudinary instance configuration](#migrating_cloudinary_instance_configuration), you don't need to add configuration parameters to your asset instances:

```js
const myImage = cl.image("sample"); 
```

## Migrating delivery URLs

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

```js
// Legacy SDK
cl.imageTag("actor", {
  cloud_name: "demo",
  transformation: [
  {effect: "cartoonify"},
  {radius: "max"},
  {effect: "outline:100", color: "lightblue"},
  {background: "lightblue"},
  {height: 300, crop: "scale"},
  {overlay: new TextLayer().fontFamily("Arial").fontSize(60).text("Hello"), effect: "colorize", color: "#f00"},
  {angle: 15, flags: "layer_apply", x: -20, y: 80}
  ]}).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.

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

```js
// Latest SDK
import {createCloudinaryLegacyURL} from "@cloudinary/url-gen";
import TextLayer from "@cloudinary/url-gen/backwards/legacyLayer/textlayer";

const migrateUrl = createCloudinaryLegacyURL("actor", {
    cloud_name: "demo",
    transformation: [
    {effect: "cartoonify"},
    {radius: "max"},
    {effect: "outline:100", color: "lightblue"},
    {background: "lightblue"},
    {height: 300, crop: "scale"},
    {overlay: new TextLayer().fontFamily("Arial").fontSize(60).text("Hello"), effect: "colorize", color: "#f00"},
    {angle: 15, flags: "layer_apply", x: -20, y: 80}
    ]
});

const imgElement = document.createElement('img');
imgElement.src = migrateUrl;
// Append the image element to the DOM, for example:
document.getElementById('div1').appendChild(imgElement);
```

```html
<!--Where div1 is the ID of a div element in your HTML file-->
<div id="div1"></div>
```

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 js-url-gen library](#sdk_migration_considerations), 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, which, for the above example, is:

```js
// Latest SDK
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 {source} from "@cloudinary/url-gen/actions/overlay";
import {byAngle} from "@cloudinary/url-gen/actions/rotate"
import {Position} from "@cloudinary/url-gen/qualifiers/position";
import {center} from "@cloudinary/url-gen/qualifiers/compass";
import {compass} from "@cloudinary/url-gen/qualifiers/gravity";
import {outer} from "@cloudinary/url-gen/qualifiers/outlineMode";
import {text} from "@cloudinary/url-gen/qualifiers/source";
import {TextStyle} from "@cloudinary/url-gen/qualifiers/textStyle";
import {Transformation} from "@cloudinary/url-gen";

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))
  .overlay(
    source(
      text('Hello', new TextStyle('Arial',60))
        .textColor('#f00')
        .transformation(new Transformation()
        .rotate(byAngle(15)))
    )
    .position(new Position().gravity(compass(center())).offsetX(-20).offsetY(80)) 
  );

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

The resulting URL is:

![Transformed actor](https://res.cloudinary.com/demo/image/upload/e_cartoonify/r_max/co_lightblue,e_outline:outer:100/b_lightblue/c_scale,h_300/co_rgb:f00,l_text:Arial_60:Hello/a_15/fl_layer_apply,g_center,x_-20,y_80/actor "with_code: false")

## Migrating responsive functionality

If you are using the [responsive functionality](javascript1_image_manipulation#responsive_image_settings) 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](https://github.com/cloudinary/frontend-frameworks):

```
npm i @cloudinary/html
```

Then, use the [responsive](https://cloudinary.com/documentation/sdks/js/frontend-frameworks/responsive.html) plugin in an `HTMLImageLayer`:

```js
// Latest SDK
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()]);
```

> **READING**:
>
> * Take a look at the full [latest JavaScript SDK guide](javascript_integration).    

> * See examples of powerful [image](javascript_image_transformations) and [video](javascript_video_transformations) transformations using `@cloudinary/url-gen`. 

> * See our [image transformations](image_transformations) and [video transformations](video_manipulation_and_delivery) guides and the [Transformation URL API Reference](transformation_reference).

> * Stay tuned for updates by following the [Release Notes](programmable_media_release_notes) and the [Cloudinary Blog](https://cloudinary.com/blog).