RFC: Cloudinary JS SDK v3

[colbyfayock]

The Cloudinary SDK team is focused on delivering the best developer experience possible. Based on feedback around our JavaScript URL Gen SDK, we’re revisiting the work from v2 and planning improvements.

We’re considering three options, which we outline below with examples, and would like your feedback early in the process to ensure we’re solving the right problems for both enterprise customers and our self-serve/free-tier community.

Motivation

Version 2 of the JavaScript URL Gen SDK addressed key issues like performance and error handling, but introduced complexity and usability concerns.

Through this RFC and proposed solutions, we aim to reduce complexity while retaining the performance gains of v2, helping developers create media-rich apps in a developer-friendly environment.

Proposals

Current Version

Starting off, we'll see an example using the JavaScript URL Gen SDK v2 to resize an image, add an overlay, and optimize delivery.

import { crop } from "@cloudinary/url-gen/actions/resize";
import { source } from "@cloudinary/url-gen/actions/overlay";
import { text } from "@cloudinary/url-gen/qualifiers/source";
import { TextStyle } from "@cloudinary/url-gen/qualifiers/textStyle";
import { Position } from "@cloudinary/url-gen/qualifiers/position";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";
import { quality, format } from "@cloudinary/url-gen/actions/delivery";
import { auto as autoQuality } from "@cloudinary/url-gen/qualifiers/quality";
import { auto as autoFormat } from "@cloudinary/url-gen/qualifiers/format";

Image
  .resize(
    crop()
      .width(500)
      .height(500)
      .gravity(compass("south"))
  )
  .overlay(
    source(
      text(
        "My Text",
        new TextStyle("Verdana", 75)
          .fontWeight("bold")
          .textDecoration("underline")
          .letterSpacing(14)
      )
    )
    .position(
      new Position()
        .gravity(compass("north_west"))
        .offsetX(520)
        .offsetY(50)
    )
  )
  .delivery(quality(autoQuality()))
  .delivery(format(autoFormat()));

Proposal 1

A syntax somewhat resembling the previous SDK, cloudinary-core, using an array of objects.

// No imports required for transformations
image.transform([
  {
    type: 'resize',
    crop: 'fill',
    width: 500,
    height: 500,
    gravity: 'south'
  },
  {
    type: 'overlay',
    text: {
      text: 'My Text',
      fontWeight: 'bold',
      textDecoration: 'underline',
      letterSpacing: 14
    },
    position: {
      gravity: 'north_west',
      x: 520,
      y: 50
    }
  },
  {
    type: 'delivery',
    quality: 'auto',
    format: 'auto'
  }
]);

Proposal 2

A syntax similar to the current version but is primarily data-driven.

// No imports required for transformations
image
  .resize({
    crop: 'fill',
    width: 500,
    height: 500,
    gravity: 'south'
  })
  .overlay({
    text: {
      text: 'My Text',
      fontWeight: 'bold',
      textDecoration: 'underline',
      letterSpacing: 14
    },
    position: {
      gravity: 'north_west',
      x: 520,
      y: 50
    }
  })
  .quality('auto')
  .format('auto')

Proposal 3

A syntax that is still similar to the current version, but with nested classes removed.

import { fill } from "@cloudinary/url-gen/actions/resize";
import { text } from "@cloudinary/url-gen/qualifiers/source";
import { quality, format } from "@cloudinary/url-gen/actions/delivery";

image
  .resize(
    fill({
      width: 2000,
      height: 2000,
      gravity: 'south'
    })
  )
  .overlay(
    text('My Text')
      .style("Verdana", 75)
      .fontWeight("bold")
      .textDecoration("underline")
      .letterSpacing(14)
      .position({
        gravity: 'north_west',
        x: 520,
        y: 50
      })
  )
  .delivery(quality('auto'))
  .delivery(format('auto'));

Other

We’re open to design ideas, whether extending our proposals or completely reimagining how Cloudinary URLs are constructed.

Considerations

• Initially, some documentation won’t be autogenerated, leading to fewer examples on the site.
• The first release may lack full Cloudinary feature parity, but the SDKs will include an "escape hatch" to manually add any needed transformations.
• This RFC covers the URL Gen SDK, which integrates with frontend SDKs like React and Angular. The frontend SDKs and the API for passing generated URLs to the frontend SDKs will not change.

Conclusion

Cloudinary is committed to improving the developer experience of the URL Gen SDK and values your feedback on where and how we can improve.

Please review the proposed options, participate in the poll, and share your thoughts or new ideas in the RFC comments.

Thank you—we’re excited to help you create the best visual experiences on the web!

[tsi]

Voted #1 💪
But why do we need the type field? Couldn't this be inferred? Wouldn't crop always be of type: 'resize'? and if not, how can I tell what type is right for which transformation?

[jerzy-mankowski]

Why type field is needed here:

• if we don't use it and just infer via some unclear properties, IDEs wont be able to guess what should be shape of the object and so wont be helpful at all while coding, even tho it's TS
• will help is in the implementation itself as it will provide a clear way to understand which transformation is happening
• will help out users to understand which transformations is being applied

[codercatdev]

Very much in favor of #3, the nesting was the only reason I didn't like v2.

[jlengstorf]

the extra imports led me to not use this SDK, so very much in favor of any approach that removes that requirement

option 1 and 2 both look good, but I'd love to see what happens with URLs that would require multiple fl_layer_apply uses. For example, this one:

https://res.cloudinary.com/jlengstorf/image/upload/u_fetch:aHR0cHM6Ly9pbWcuY2xlcmsuY29tL2V5SjBlWEJsSWpvaWNISnZlSGtpTENKemNtTWlPaUpvZEhSd2N6b3ZMMmx0WVdkbGN5NWpiR1Z5YXk1a1pYWXZkWEJzYjJGa1pXUXZhVzFuWHpKWVRVOXBZVlExTVVoVlZtdDRVRVZOTnpkYVFtaElWRk5sYUNKOQ==/c_thumb,w_500,ar_1,g_face/fl_layer_apply,g_north_west,x_-46,y_175/l_4d1a:club-sandwich:onigiri/e_overlay,fl_layer_apply,g_east/w_1600,h_900,c_crop,g_east/bo_8px_solid_black,co_white,w_1500,l_text:Verdana_75_stroke_bold_center:Join%20Blitz%20at%20Club%20Sandwich!/fl_layer_apply,c_fit,g_south_west,x_50,y_740/co_rgb:333333,w_560,c_fit,l_text:Verdana_40_italic_center:Join%20him!%20Knock%20to%20the%20tune%20of%20Darude%20Sandstorm%20then%20give%20the%20password:/fl_layer_apply,g_south_west,x_510,y_470/co_rgb:000000,w_560,l_text:Verdana_200_bold_center:ONIGIRI/fl_layer_apply,g_north_west,x_510,y_460/w_1200,f_auto,q_auto/v1698360748/4d1a/club-sandwich/invite.jpg

How would this look in the new API? Getting into the gnarly, advanced use cases will hopefully make it easier to find the rough edges of the SDK.

Thanks!

[jerzy-mankowski]

Hey,
Thanks for the feedback!
Regarding using multiple transformations with layer -

• Proposal 1 - it accepts a list of transformations, so u can just apply them as presented below

image.transform([
  { type: 'overlay', ... },
  { type: 'overlay', ... },
]

• Proposal 2 - here we keep the chaining ability so

image
  .overlay({ text: { ... }})
  .overlay({ text: { ... }})

[Baroshem]

Hey there!

Thanks for this RFC! I really like the fact that you guys are thinking not only about performance but about usability too!

I voted for the option two as it is most appealing to me. I like the fact that I don't need to import anything - I can just focus on using the features that I like with appropriate options :)

[colbyfayock]

thanks for your thoughts Jakub!