Vue.js migration guide

Introduction

Cloudinary's Vue.js SDK is designed to provide a simpler and more enhanced developer experience. This guide explains how to migrate your Vue.js code from the cloudinary-vue library (legacy SDK) to the latest Vue.js SDK, which includes @cloudinary/vue from the frontend-frameworks library together with @cloudinary/url-gen from the js-url-gen library.

Key improvements in the Vue.js 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/.
• 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 @cloudinary/vue + @cloudinary/url-gen packages in your Vue.js app, see the Vue.js SDK guide.

Key considerations

Cloudinary's Vue.js package (@cloudinary/vue 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 Vue.js SDK is very different from the cloudinary-vue (legacy) library in its architecture and usage, so migration paths depend on your current usage of the Vue.js library.

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

Installation

Install the required packages using the NPM package manager:

Migrating Cloudinary instance configuration

Using the legacy Vue.js SDK, you may be configuring your cloud name and other configuration parameters in a cld-context. 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 cld-context element:

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

Migrating asset instance configuration

You can also set configuration parameters in cld-image or cld-video elements in the legacy Vue.js SDK. This is similar to setting the parameters on a per asset instance.

For example, setting cloudName in a cld-image element:

is similar to setting cloudName in a CloudinaryImage:

Migrating delivery URLs

The cld-image component in cloudinary-vue has been replaced by the AdvancedImage component in @cloudinary/vue.

Whereas in the legacy Vue.js SDK you specify transformation parameters in the cld-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 a cld-image component with configuration and transformation parameters included:

There is no easy migration path from a cld-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 cld-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:

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:

3. Use this URL as the source for a regular image tag.

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 Vue.js 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 Vue.js SDK, are offered as plugins in the latest Vue.js SDK.

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