Angular migration guide

Introduction

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

Key improvements in the Angular SDK v2:

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

Things to know before migrating to @cloudinary/angular + @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_angular library.

For example:

  • URL generated with the cloudinary_angular 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 on your account, 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/angular + @cloudinary/url-gen packages in your Angular app, see the Angular SDK v2 (Beta) guide.

Key considerations

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

You can use the cloudinary-core, cloudinary/angular-5.x (or other version), @cloudinary/angular 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/angular and @cloudinary/url-gen into your application and slowly migrate your functionality piece by piece, until you are able to remove all cloudinary_angular functionality.

Installation

Install the required packages using the NPM package manager:

Copy to clipboard
npm i @cloudinary/url-gen @cloudinary/angular --save

Migrating Cloudinary instance configuration

In the Angular SDK v1, you configure your cloud name and other configuration parameters in a CloudinaryModule. 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 CloudinaryModule element:

Copy to clipboard
// SDK v1
import { CloudinaryModule } from '@cloudinary/angular-5.x';
import * as Cloudinary from 'cloudinary-core';

imports: [
   ...,
    CloudinaryModule.forRoot(Cloudinary, { cloud_name: 'demo', secure: true })
  ],

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

Copy to clipboard
// SDK v2 - app.module.ts:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule
],
Copy to clipboard
// SDK v2 - component.ts: 
import {Cloudinary} from '@cloudinary/url-gen';

var cl = new Cloudinary({cloud: {cloudName: 'demo'}, url: {secure: true}});

Note
Using @cloudinary/url-gen you can also set configuration parameters on a per asset instance:

Copy to clipboard
// SDK v2
import {CloudinaryImage} from '@cloudinary/url-gen';

myImage: CloudinaryImage

this.myImage = new CloudinaryImage('sample', {cloudName: 'demo'});

However, if you use the Cloudinary instance configuration, you don't need to add configuration parameters to your asset instances:

Copy to clipboard
this.myImage = cl.image('sample');

Migrating delivery URLs

The cl-image component in the Angular SDK v1 has been replaced by the advanced-image component in @cloudinary/angular.

Whereas in the Angular SDK v1 you specify transformation parameters in the cl-image component, in the SDK v2 they are specified in @cloudinary/url-gen in a CloudinaryImage object that you then pass to the advanced-image component.

Here is an example of a cl-image component with transformation parameters included:

Copy to clipboard
<!-- SDK v1 -->
<cl-image public-id='actor.jpg' >
  <cl-transformation effect='cartoonify'>
  </cl-transformation>
  <cl-transformation radius='max'>
  </cl-transformation>
  <cl-transformation effect='outline:100' color='lightblue'>
  </cl-transformation>
  <cl-transformation background='lightblue'>
  </cl-transformation>
  <cl-transformation height='300' crop='scale'>
  </cl-transformation>
</cl-image>

There is no easy migration path from a cl-image component to an advanced-image 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 cl-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:

    Copy to clipboard
    {
        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:

    Copy to clipboard
    // SDK v2
    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.

    Copy to clipboard
    // SDK v2
    const imgElement = document.createElement('img');
    imgElement.src = migrateUrl;
    // Append the image element to the DOM, for example:
    document.getElementById('div1').appendChild(imgElement);
    Copy to clipboard
    <!--Where div1 is the ID of a div element in your HTML file-->
    <div id="div1"></div>

Caution
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 Angular SDK v2, for the implications of these changes to transformation URLs.

For all new Cloudinary delivery URLs, you should start to use @cloudinary/url-gen to create a CloudinaryImage that you can use in the advanced-image Angular component:

Copy to clipboard
// SDK v2
// In your app.module.ts inject the library:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule
],
...
Copy to clipboard
// In your component.ts use `@cloudinary/url-gen` to generate your transformations.

import {Component, OnInit} from '@angular/core';
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';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})

export class AppComponent implements OnInit{
  myImage: CloudinaryImage

  ngOnInit() {

    // Use the image with public ID, 'actor'.
    this.myImage = new CloudinaryImage('actor', {cloudName: 'demo'});

    // Apply the transformation.
    this.myImage
    .effect(cartoonify())
    .roundCorners(max())
    .effect(outline().mode(outer()).width(100).color('lightblue'))
    .backgroundColor('lightblue')
    .resize(scale().height(300));
  }
}
Copy to clipboard
<!-- In your view add the advanced-image component and pass your Cloudinary image. -->
<advanced-image [cldImg]="myImage"></advanced-image>

The resulting URL is:

Transformed actor

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 Angular SDK v1, are offered as plugins in the Angular SDK v2.

When you have migrated your delivery URLs to use the advanced-image component, you can use any of 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.

Copy to clipboard
// SDK v2
// In your app.module.ts inject the library:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule
],
...

// In your component.ts use `@cloudinary/url-gen` to generate your transformations.
import {Component, OnInit} from '@angular/core';
import {CloudinaryImage} from '@cloudinary/url-gen';

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

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})

export class AppComponent implements OnInit{
  myImage: CloudinaryImage;

   // Use all the plugins.
  plugins = [lazyload(), responsive(), accessibility(), placeholder()]

  ngOnInit() {

    this.myImage = new CloudinaryImage('sample', {cloudName: 'demo'});

  }
}

// In your view add the advanced-image component and pass your Cloudinary image and plugins.
<advanced-image [cldImg]="myImage" [plugins]="plugins"></advanced-image>

Related topics

✔️ Feedback sent!

Rate this page: