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

# JavaScript SDK

[alternative-transformations-link]:javascript_image_transformations#alternative_ways_to_apply_transformations
[sample-projects-link]:javascript_sample_projects
[changelog-link]: https://github.com/cloudinary/js-url-gen/blob/master/CHANGELOG.md

The Cloudinary JavaScript SDK provides simple, yet comprehensive image and video rendering, transformation, optimization, and delivery capabilities that you can implement using code that integrates seamlessly with your existing JavaScript or JS-based framework application.

> **NOTE**:
>
> This guide describes Cloudinary's `js-url-gen` frontend library. 

> * For the backend Node.js library, which also covers upload and admin functionality, see the [Node.js documentation](node_integration).

> * If you're using a frontend framework, jump straight to the relevant docs: 

>   * [Angular](angular_integration)

>   * [React](react_integration)

>   * [Vue](vue_integration)
> If you're using pure frontend JavaScript without one of the above frameworks, follow the instructions on this page for installation and setup.

## How would you like to learn?

{table:class=no-borders overview}Resource | Description 
--|--
[JavaScript quick start](javascript_quick_start) | Get up and running in five minutes with a walk through of installation, configuration, rendering, and transformations.
[Video tutorials](javascript_video_tutorials) | Watch tutorials relevant to your use cases, from getting started with the JavaScript SDK, to rendering and transforming your images and videos. 
[Sample projects](javascript_sample_projects) | Explore sample projects to see how to implement Cloudinary functionality such as rendering and delivery with transformations.
[Cloudinary js-url-gen GitHub repo](https://github.com/cloudinary/js-url-gen) | Explore the source code and see the [CHANGELOG][changelog-link] for details on all new features and fixes from previous versions. 

Other helpful resources...

This guide focuses on how to set up and implement popular Cloudinary capabilities using the JavaScript SDK, but it doesn't cover every feature or option. Check out these other resources to learn about additional concepts and functionality in general. 

{table:class=no-borders overview}Resource | Description 
--|--
[Developer kickstart](dev_kickstart) |A hands-on, step-by-step introduction to Cloudinary features.
[Glossary](cloudinary_glossary) | A helpful resource to understand Cloudinary-specific terminology.
[Guides](programmable_media_guides) | In depth guides to help you understand the many, varied capabilities provided by the product. 
[References](cloudinary_references) | Comprehensive references for all APIs, including JavaScript code examples.

## Install

Install the `@cloudinary/url-gen` package using the NPM package manager:

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

If you prefer not to use a bundler, you can [import the SDK directly from a CDN](#cdn_import).

## Configure

Include Cloudinary's JavaScript classes in your code:

```js
import {Cloudinary} from "@cloudinary/url-gen";
```

> **TIP**: :title=CDN import

If you prefer not to use a bundler, you can import the SDK directly from a CDN using an ESM-compatible URL:

```js
import { Cloudinary } from 'https://cdn.jsdelivr.net/npm/@cloudinary/url-gen/+esm';
```

### Set required configuration parameters

You can set the required configuration parameter, `cloudName`, either when creating a [Cloudinary instance](#cloudinary_instance_configuration) or [per asset](#asset_instance_configuration).

#### Cloudinary instance configuration

If you want to use the same configuration to deliver all your media assets, it's best to set up the configuration through a Cloudinary instance, for example:

```js
// Import the Cloudinary class.
import {Cloudinary} from "@cloudinary/url-gen";

// Create a Cloudinary instance and set your cloud name.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'
  }
});

// cld.image returns a CloudinaryImage with the configuration set.
const myImage = cld.image('sample');

// The URL of the image is: https://res.cloudinary.com/demo/image/upload/sample
const myURL = myImage.toURL();

// Render the image in an 'img' element.
const imgElement = document.createElement('img');
imgElement.src = myURL;
```

#### Asset instance configuration

If you need to specify different configurations to deliver your media assets, you can specify the configuration per image/video instance, for example:

```js
// Import the configuration classes.
import {URLConfig} from "@cloudinary/url-gen";
import {CloudConfig} from "@cloudinary/url-gen";
import {CloudinaryImage} from '@cloudinary/url-gen';

// Set the Cloud configuration and URL configuration
let cloudConfig = new CloudConfig({cloudName: 'demo'});
let urlConfig = new URLConfig({secure: true});

// Instantiate and configure a CloudinaryImage object.
let myImage = new CloudinaryImage('docs/shoes', cloudConfig, urlConfig);

// The URL of the image is: https://res.cloudinary.com/demo/image/upload/docs/shoes
const myURL = myImage.toURL();

// Render the image in an 'img' element.
const imgElement = document.createElement('img');
imgElement.src = myURL;
```

### Set additional configuration parameters

In addition to the required configuration parameters, you can define a number of optional [configuration parameters](cloudinary_sdks#configuration_parameters) if relevant.

> **NOTE**: Specify all configuration parameters in `camelCase`, for example **secureDistribution**.

You can use the Cloudinary constructor to set configuration parameters, for example:

```js

// Create a Cloudinary instance, setting some Cloud and URL configuration parameters.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'
  },
  url: {
    secureDistribution: 'www.example.com', 
    secure: true 
  }
});

// This creates a URL of the form: https://www.example.com/demo/image/upload/sample
```

### Build environments

Some build environments require additional configuration:

* **Rollup + Vanilla JS:** install and use `@rollup/node-resolve`.
* **Next.js + Vanilla JS:** install and use `moxystudio/next-compile-node-modules` (or some other similar solution).
* **TypeScript + Webpack:** set `"moduleResolution": "node"` in the **TSConfig** file.

### Configuration video tutorials

The following tutorials can help you install and set up your SDK:

  
  
  
    Find Your Credentials
    Find your Cloudinary credentials for APIs and SDKs 
  

  
  
  
    Configure the JavaScript SDK
    Install and configure the Cloudinary JavaScript SDK 
  

See more [JavaScript video tutorials](javascript_video_tutorials).

## Use

Once you've installed and configured the JavaScript SDK, you can use it for:

* **Transforming images** - Generate transformation URLs for your images. [See examples](#quick_examples_image_transformations)
* **Transforming videos** - Generate transformation URLs for your videos. [See examples](#quick_examples_video_transformations)
* **Optimizing delivery** - Use plugins to improve your user's experience by automating media tasks like lazy loading, responsive images and more. [See plugins](#plugins)

### Quick examples: Image transformations

Here are two quick examples to get you started with image transformations:

* [Image transformation example 1](#image_transformation_example_1) - Apply a sepia effect to an image
* [Image transformation example 2](#image_transformation_example_2) - Apply multiple transformations as chained transformations

#### Image transformation example 1

The following Javascript code renders the front_face.jpg image with a sepia effect applied:

```js

//// Use `@cloudinary/url-gen` to generate your transformations.
import {Cloudinary} from "@cloudinary/url-gen";

// Import required actions.
import {sepia} from "@cloudinary/url-gen/actions/effect";

// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'
  }
}); 

// Use the image with public ID, 'front_face'.
const myImage = cld.image('front_face');

// Apply the transformation.
myImage
.effect(sepia());  // Apply a sepia effect.

// Render the transformed image in an 'img' element.
const imgElement = document.createElement('img');
imgElement.src = myImage.toURL();

```

This code creates the HTML required to render the following transformation URL:

![Sample image transformation](https://res.cloudinary.com/demo/image/upload/e_sepia/front_face "with_url:true, with_code:false, thumb: c_scale,w_150")

#### Image transformation example 2

You can apply more than one transformation at a time (see [chained transformations](image_transformations#chained_transformations)) to give more interesting results (notice how you import only the actions and qualifiers that you need, to [minimize your bundle size](javascript_image_transformations#tree_shaking)):

![Sample image transformation](https://res.cloudinary.com/demo/image/upload/c_thumb,g_face,h_150,w_150/r_20/e_sepia/l_cloudinary_icon/e_brightness:90/o_60/c_scale,w_50/fl_layer_apply,g_south_east,x_5,y_5/a_10/q_auto/front_face.png "disable_all_tab: true, with_url: false, frameworks:js_2")

```js
new CloudinaryImage("front_face.png")
  .resize(
    thumbnail()
      .width(150)
      .height(150)
      .gravity(focusOn(face()))
  )
  .roundCorners(byRadius(20))
  .effect(sepia())
  .overlay(
    source(
      image("cloudinary_icon").transformation(
        new Transformation()
          .adjust(brightness().level(90))
          .adjust(opacity(60))
          .resize(scale().width(50))
      )
    ).position(
      new Position()
        .gravity(compass("south_east"))
        .offsetX(5)
        .offsetY(5)
    )
  )
  .rotate(byAngle(10))
  .delivery(quality(auto()));
```

This relatively simple code performs all of the following on the original front_face.jpg image before delivering it:

* **Crop** to a 150x150 thumbnail using face-detection gravity to automatically determine the location for the crop
* **Round the corners** with a 20 pixel radius
* Apply a **sepia effect**
* **Overlay the Cloudinary logo** on the southeast corner of the image (with a slight offset). Scale the logo overlay down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%).
* **Rotate** the resulting image (including the overlay) by 10 degrees
* **Optimize** the image to reduce the size of the image without impacting visual quality.
* **Convert** and deliver the image in PNG format (the originally uploaded image was a JPG)

And here's the URL that's automatically generated and rendered from the above code:

![Sample image transformation](https://res.cloudinary.com/demo/image/upload/c_thumb,g_face,h_150,w_150/r_20/e_sepia/l_cloudinary_icon/e_brightness:90/o_60/c_scale,w_50/fl_layer_apply,g_south_east,x_5,y_5/a_10/q_auto/front_face.png "disable_all_tab: true, with_code:false, with_image:false")
The `@cloudinary/url-gen` package installs an additional [transformation-builder-sdk](https://github.com/cloudinary/js-transformation-builder-sdk) library as a dependency, which handles the transformation generation part of the URL. 

You can use the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/index.html) to find all available transformations, syntax and examples.> **TIP**: There are [alternative ways to apply transformations][alternative-transformations-link] to your images, for example:

```js
import { transformationStringFromObject } from "@cloudinary/url-gen";

const transformation = transformationStringFromObject([
  {gravity: "face", height: 150, width: 150, crop: "thumb"},
  {radius: 20},
  {effect: "sepia"},
  {overlay: "cloudinary_icon"},
  {width: 50, crop: "scale"},
  {opacity: 60},
  {effect: "brightness:90"},
  {flags: "layer_apply", gravity: "south_east", x: 5, y: 5},
  {angle: 10},
  {fetch_format: "png"}
  ]);
myImage.addTransformation(transformation);
```
> **Learn more about image transformations**:
>
> * Read the [image transformation guide](image_transformations) to learn about the different ways to transform your images.

> * See more examples of [image transformations](javascript_image_transformations) using the Cloudinary JavaScript SDK.  

> * See all possible transformations in the [Transformation URL API reference](transformation_reference).

> * See all JavaScript transformation actions and qualifiers in the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/list_namespace.html).

### Quick examples: Video transformations

Here are two quick examples to get you started with video transformations:

* [Video transformation example 1](#video_transformation_example_1) - Adjust the brightness of a video
* [Video transformation example 2](#video_transformation_example_2) - Apply multiple transformations as chained transformations

#### Video transformation example 1

The following Javascript code renders the ship.mp4 video with a brightness adjustment applied:

```js
import {Cloudinary} from "@cloudinary/url-gen";

// Import required actions.
import {brightness} from "@cloudinary/url-gen/actions/adjust";

// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'
  }
}); 

// Use the video with public ID, 'ship'.
const myVideo = cld.video('ship');

// Apply the transformation.
myVideo
.adjust(brightness().level(20));  // Adjust brightness.

// Get the video URL.
const videoURL = myVideo.toURL();

```

This code creates the HTML required to render the following transformation URL:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/e_brightness:20/ship.mp4 "with_url:true, with_code:false, thumb: c_scale,w_300")

#### Video transformation example 2

You can apply more than one transformation at a time (see [chained transformations](video_manipulation_and_delivery#chained_transformations)) to give more interesting results (notice how you import only the actions and qualifiers that you need, to [minimize your bundle size](javascript_video_transformations#tree_shaking)):

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/ar_1:1,c_fill,g_auto,w_300/e_blur:50/r_max/ship.mp4 "disable_all_tab: true, with_url: false, frameworks:js_2")

```js
new CloudinaryVideo("ship.mp4")
  .resize(
    fill()
      .width(300)
      .aspectRatio(ar1X1())
      .gravity(autoGravity())
  )
  .effect(blur().strength(50))
  .roundCorners(max());
```

This relatively simple code performs all of the following on the original ship.mp4 video before delivering it:

* **Crop** to a 1:1 aspect ratio (square) with a width of 300 pixels, using automatic gravity to determine the focal point
* Apply a **blur effect** with strength 50
* Apply **maximum rounding** to create a circular video

And here's the URL that's automatically generated and rendered from the above code:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/ar_1:1,c_fill,g_auto,w_300/e_blur:50/r_max/ship.mp4 "disable_all_tab: true, with_code:false, with_image:false")

Similar to [image transformations](#quick_examples_image_transformations), there are [alternative ways to apply transformations](javascript_video_transformations#alternative_ways_to_apply_transformations) to your videos.

> **Learn more about video transformations**:
>
> * Read the [video transformation guide](video_manipulation_and_delivery) to learn about the different ways to transform your videos.

> * See more examples of [video transformations](javascript_video_transformations) using the Cloudinary JavaScript SDK.  

> * See all possible transformations in the [Transformation URL API reference](transformation_reference).

> * See all JavaScript transformation actions and qualifiers in the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/list_namespace.html).

### Plugins

The `@cloudinary/html` package from [frontend-frameworks](https://github.com/cloudinary/frontend-frameworks) provides [plugins](javascript_image_transformations#plugins) to render the media on your site in the optimal way and improve your user's experience by automating media tasks like lazy loading, responsive images and more.

> **Learn more about plugins**:
>
> * See how to use [image plugins](javascript_image_transformations#plugins) in your JavaScript application.

 
## Sample projects
Take a look at the [JavaScript sample projects][sample-projects-link] page to help you get started integrating Cloudinary into your JavaScript application.> **TIP**: Check out our collection of [JavaScript code explorers](code_explorers) too!

> **READING**:
>
> * Try out the JavaScript SDK using the [quick start](javascript_quick_start).   

> * See examples of powerful [image](javascript_image_transformations) and [video](javascript_video_transformations) transformations using JavaScript code, and see our [image transformation](image_transformations) and [video transformation](video_manipulation_and_delivery) docs.   

> * For details on migrating to this SDK from the legacy JavaScript SDK, see the [JavaScript migration guide](javascript1_migration_guide).

> * For information about uploading images and videos from a JavaScript application, see [JavaScript image and video upload](javascript_image_and_video_upload).

> * Stay tuned for updates by following the [Release Notes](programmable_media_release_notes) and the [Cloudinary Blog](https://cloudinary.com/blog).