React migration guide
Last updated: Sep-02-2024
Introduction
Cloudinary's React SDK is designed to provide a simpler and more enhanced developer experience. This guide explains how to migrate your React code from the cloudinary-react library (legacy SDK) to the latest React SDK, which includes @cloudinary/react
from the frontend-frameworks library together with @cloudinary/url-gen
from the 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) 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/
.
- When compiled to the final delivery URL, each action (including any action qualifiers) represents a different component (separated by a '/'), for example:
- 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.
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
- 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 for your 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, 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 using the @cloudinary/react
+ @cloudinary/url-gen
packages in your React app, see the React SDK guide.
Key considerations
Cloudinary's React package (@cloudinary/react
from the frontend-frameworks
library) must be used in conjunction with the Cloudinary JavaScript SDK (@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:
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:
is similar to setting cloudName
and secure
in a Cloudinary
instance:
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:
is similar to setting cloudName
in a CloudinaryImage
:
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:
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:
-
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: -
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 ascloud_name
, should be included in the function call as this is simply a helper function to build the delivery URL: -
Use this URL as the source for a regular image tag.
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, 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:
The resulting URL is:
Migrating advanced image components and responsive functionality
The advanced image components (lazy loading, image placeholders and image accessibility) and responsive image settings offered by the legacy React SDK, are offered as 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:
- Take a look at the full React SDK guide.
- See examples of powerful image and video transformations using
@cloudinary/url-gen
. - See our image transformations and video transformations guides.
- Stay tuned for updates with the Programmable Media Release Notes and the Cloudinary Blog.