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

# Vue.js migration guide


## Introduction

Cloudinary's [Vue.js SDK](vue_integration) 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](https://github.com/cloudinary/cloudinary-vue) library (legacy SDK) to the latest Vue.js SDK, which includes `@cloudinary/vue` from the [frontend-frameworks](https://github.com/cloudinary/frontend-frameworks/tree/master/packages/vue) library together with `@cloudinary/url-gen` from the [js-url-gen](https://github.com/cloudinary/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](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/vue + @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-vue` library. 
> For example: 

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

## Key considerations

Cloudinary's Vue.js package (`@cloudinary/vue` 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 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:

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

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

```vue
// Legacy SDK
import { CldContext } from "cloudinary-vue";

<cld-context cloudName="demo" secure=true>
  <div>
    ...
  </div>
</cld-context>
```

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

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

```vue
// Legacy SDK
import { CldImage } from "cloudinary-vue";

<cld-image cloudName="demo" publicId="sample"/>
</cld-image>
```

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

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

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

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

```vue
// Legacy SDK
<cld-image publicId="actor.jpg" cloudName="demo" >
  <cld-transformation effect="cartoonify" />
  <cld-transformation radius="max" />
  <cld-transformation effect="outline:100" color="lightblue" />
  <cld-transformation background="lightblue" />
  <cld-transformation height="300" crop="scale" />
</cld-image>
```

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: 

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

    ```vue
    // 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. 

    ```vue
    // 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/vue + @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` Vue.js component:

```vue
// Latest SDK
<script>
import { AdvancedImage } from '@cloudinary/vue';
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 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));

export default {
  components: {
    AdvancedImage,
  },
  data() {
    return {
        myImage,
    };
  },
};
</script>

<template>
  <div>
    <AdvancedImage :cldImg="myImage" />
  </div>
</template>


```

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](vue1_image_manipulation#lazy_loading), [image placeholders](vue1_image_manipulation#image_placeholders) and [image accessibility](vue1_image_manipulation#image_accessibility)) and [responsive image settings](vue1_image_manipulation#responsive_image_settings) offered by the legacy Vue.js SDK, are offered as [plugins](vue_image_transformations#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:

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

```vue
// Latest SDK

<script>
import {CloudinaryImage} from "@cloudinary/url-gen";

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

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

export default {
  components: {
    AdvancedImage,
  },
  data() {
    return {
      plugins: [lazyload(), responsive(), accessibility(), placeholder()],
      myImage,
    };
  },
};
</script>

<template>
  <div>
    <AdvancedImage :cldImg="myImage" :plugins="plugins"/>
  </div>
</template>

```

> **READING**:
>
> * Take a look at the full [Vue.js SDK guide](vue_integration).    

> * See examples of powerful [image](vue_image_transformations) and [video](vue_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).