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

# React migration guide


## Introduction

Cloudinary's [React SDK](react_integration) is designed to provide a simpler and more enhanced developer experience. This guide explains how to migrate your React code from the [cloudinary-react](https://github.com/cloudinary/cloudinary-react) library (legacy SDK) to the latest React SDK, which includes `@cloudinary/react` from the [frontend-frameworks](https://github.com/cloudinary/frontend-frameworks/tree/master/packages/react) library together with `@cloudinary/url-gen` from the [js-url-gen](https://github.com/cloudinary/js-url-gen) library.

Key improvements in the React SDK:

* 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 @cloudinary/react + @cloudinary/url-gen
> The action-based syntax used in the `js-url-gen` library (`@cloudinary/url-gen`) may cause URLs to be formed differently from those generated by the `cloudinary-react` library. 
> For example: 

> * **URL generated with the cloudinary-react 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 `@cloudinary/react` + `@cloudinary/url-gen` packages in your React app, see the [React SDK guide](react_integration).

## Key considerations

Cloudinary's React package (`@cloudinary/react` from the `frontend-frameworks` library) must be used in conjunction with the [Cloudinary JavaScript SDK](javascript_integration) (`@cloudinary/url-gen`) to provide all of Cloudinary's transformation and optimization functionality. As such, the latest React SDK is very different from the `cloudinary-react` (legacy) library in its architecture and usage, so migration paths depend on your current usage of the React library.

You can use the `cloudinary-react`, `@cloudinary/react` 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/react` and `@cloudinary/url-gen` into your application and slowly migrate your functionality piece by piece, until you are able to remove all `cloudinary-react` functionality.

## Installation

Install the required packages using the NPM package manager:

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

## Migrating Cloudinary instance configuration

Using the legacy React SDK, you may be configuring your cloud name and other configuration parameters in a `CloudinaryContext`. This is similar to configuring these parameters in a `Cloudinary` instance, provided by the `@cloudinary/url-gen` library, in that the configuration is set once, rather than for each image or video.

For example, setting `cloudName` and `secure` in a `CloudinaryContext` element:

```react
// Legacy SDK
import {CloudinaryContext} from "cloudinary-react";

<CloudinaryContext cloudName="demo" secure="true">
  <div>
    ...
  </div>
</CloudinaryContext>
```

is similar to setting `cloudName` and `secure` in a `Cloudinary` instance:

```react
// 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 `Image` or `Video` elements in the legacy React SDK. This is similar to setting the parameters on a per asset instance.

For example, setting `cloudName` in an `Image` element:

```react
// Legacy SDK
import {Image} from 'cloudinary-react';

<Image cloudName="demo" publicId="sample"/>
```

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

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

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

## Migrating delivery URLs

The `Image` component in `cloudinary-react` has been replaced by the `AdvancedImage` component in `@cloudinary/react`.

Whereas in the legacy React SDK you specify transformation parameters in the `Image` component, in the latest SDK they are specified in `@cloudinary/url-gen` in a `CloudinaryImage` object that you then pass to the `AdvancedImage` component.

Here is an example of an `Image` component with configuration and transformation parameters included: 

```react
// Legacy SDK
<Image publicId="actor.jpg" cloudName="demo" >
  <Transformation effect="cartoonify" />
  <Transformation radius="max" />
  <Transformation effect="outline:100" color="lightblue" />
  <Transformation background="lightblue" />
  <Transformation height="300" crop="scale" />
</Image>
```

There is no easy migration path from an `Image` component to an `AdvancedImage` component, but you can use the following process as an intermediate step, to create a URL that you can use as the source for a regular image tag:

1. Convert the `Image` component to JSON. An XML to JSON converter can help with this transition, or you may want to use a script if you have a large number of URLs to convert. The previous example would become: 

    ```json
    {
        cloud_name: "demo",
        transformation: [
            {effect: "cartoonify"},
            {radius: "max"},
            {effect: "outline:100", color: "lightblue"},
            {background: "lightblue"},
            {height: 300, crop: "scale"}
        ]
    }
    ```
2. Pass this JSON to the `createCloudinaryLegacyURL` function, included in the `@cloudinary/url-gen` library, to return a delivery URL that includes the transformations. 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:

    ```react
    // Latest SDK
    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"}
        ]
    });
    ```
3. Use this URL as the source for a regular image tag. 

    ```react
    // Latest SDK
    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 @cloudinary/react + @cloudinary/url-gen](#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 to create a `CloudinaryImage` that you can use in the `AdvancedImage` React component:

```react
// Latest SDK
import React from "react"
import {AdvancedImage} from "@cloudinary/react";
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 App = () => {

    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 transformed image in a React component.
    return (
        <div>
        <AdvancedImage cldImg={myImage} />
        </div>
    )
};
```

The resulting URL is:

![Transformed actor](https://res.cloudinary.com/demo/image/upload/e_cartoonify/r_max/co_lightblue,e_outline:100/b_lightblue/c_scale,h_300/actor "with_code: false")

## Migrating advanced image components and responsive functionality

The advanced image components ([lazy loading](react1_image_manipulation#lazy_loading), [image placeholders](react1_image_manipulation#image_placeholders) and [image accessibility](react1_image_manipulation#image_accessibility)) and [responsive image settings](react1_image_manipulation#responsive_image_settings) offered by the legacy React SDK, are offered as [plugins](react_image_transformations#plugins) in the latest React SDK.

When you have migrated your delivery URLs to use the `AdvancedImage` component, you can use the plugins as follows:

> **NOTE**: This example shows all four plugins being used, but you can use only one, or any combination, by importing and specifying only those you need.

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

// Import the plugins.
import {AdvancedImage, lazyload, accessibility, responsive, placeholder} from "@cloudinary/react";

 const App = () => {

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

  // Use all the plugins.
  return (
    <div>
      <AdvancedImage cldImg={myImage} plugins={[lazyload(), responsive(), accessibility(), placeholder()]}/>
    </div>
  )
};
```

> **READING**:
>
> * Take a look at the full [React SDK guide](react_integration).    

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

> * See our [image transformations](image_transformations) and [video transformations](video_manipulation_and_delivery) guides. 

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