feat: Max Size (#78)

# Description

Allows the ability to pass in the maxSize option where you can configure
a maximum width and height to use for images.

Images will automatically resize down to the maximum values preserving
the aspect ratio.

It will also not upscale, only downscale.

```
[plugins.inputs.maxSize]
width = 1200
height = 800
```

## Issue Ticket Number

<!-- Specifiy which issue this fixes by referencing the issue number
(`#11`) or issue URL. -->
<!-- Example: Fixes
#1 -->

Fixes #62 

## Type of change

<!-- Please select all options that are applicable. -->

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update


# Checklist

<!-- These must all be followed and checked. -->

- [ ] I have followed the contributing guidelines of this project as
mentioned in [CONTRIBUTING.md](/CONTRIBUTING.md)
- [ ] I have created an
[issue](https://github.com/colbyfayock/netlify-plugin-cloudinary/issues)
ticket for this PR
- [ ] I have checked to ensure there aren't other open [Pull
Requests](https://github.com/colbyfayock/netlify-plugin-cloudinary/pulls)
for the same update/change?
- [ ] I have performed a self-review of my own code
- [ ] I have run tests locally to ensure they all pass
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes needed to the documentation

Author: colbyfayock

README.md

@@ -94,11 +94,30 @@ npm install netlify-plugin-cloudinary
 | folder          | string  | No      | myfolder  | Folder all media will be stored in. Defaults to Netlify site name |
 | imagesPath      | string/Array | No | /assets   | Local path application serves image assets from |
 | loadingStrategy | string  | No      | eager     | The method in which in which images are loaded (Ex: lazy, eager) |
+| maxSize         | object  | No      | eager     | See Below. |
 | privateCdn      | boolean | No      | true      | Enables Private CDN Distribution (Advanced Plan Users) |
 | uploadPreset    | string  | No      | my-preset | Defined set of asset upload defaults in Cloudinary |
 
 *Cloud Name must be set as an environment variable if not as an input
 
+#### Max Size
+
+The Max Size option gives you the ability to configure a maximum width and height that images will scale down to, helping to avoid serving unnecessarily large images.
+
+By default, the aspect ratio of the images are preserved, so by specifying both a maximum width and height, you're telling Cloudinary to scale the image down so that neither the width or height are beyond that value.
+
+Additionally, the plugin uses a crop method of `limit` which avoids upscaling images if the images are already smaller than the given size, which reduces unnecessary upscaling as the browser will typically automatically handle.
+
+The options available are:
+
+| Name            | Type    | Example   | Description |
+|-----------------|---------|-----------| ------------|
+| dpr             | string  | 2.0       | Device Pixel Ratio which essentially multiplies the width and height for pixel density. |
+| height          | number  | 600       | Maximum height an image can be delivered as. |
+| width           | number  | 800       | Maximum width an image can be delivered as.  |
+
+It's important to note that this will not change the width or height attribute of the image within the DOM, this will only be the image that is being delivered by Cloudinary.
+
 ### Environment Variables
 
 | Name                   | Required | Example  | Description |

docs/src/pages/configuration.mdx

@@ -27,13 +27,32 @@ import OgImage from '../components/OgImage';
 | folder          | string  | No      | myfolder  | Folder all media will be stored in. Defaults to Netlify site name |
 | imagesPath      | string/Array | No | /assets   | Local path application serves image assets from |
 | loadingStrategy | string  | No      | eager     | The method in which in which images are loaded (Ex: lazy, eager) |
+| maxSize         | object  | No      | eager     | See Below. |
 | privateCdn      | boolean | No      | true      | Enables Private CDN Distribution (Advanced Plan Users) |
 | uploadPreset    | string  | No      | my-preset | Defined set of asset upload defaults in Cloudinary |
 
 <Callout emoji={false}>
   Cloud Name must be set as an environment variable if not as an input
 </Callout>
 
+### Max Size
+
+The Max Size option gives you the ability to configure a maximum width and height that images will scale down to, helping to avoid serving unnecessarily large images.
+
+By default, the aspect ratio of the images are preserved, so by specifying both a maximum width and height, you're telling Cloudinary to scale the image down so that neither the width or height are beyond that value.
+
+Additionally, the plugin uses a crop method of `limit` which avoids upscaling images if the images are already smaller than the given size, which reduces unnecessary upscaling as the browser will typically automatically handle.
+
+The options available are:
+
+| Name            | Type    | Example   | Description |
+|-----------------|---------|-----------| ------------|
+| dpr             | string  | 2.0       | Device Pixel Ratio which essentially multiplies the width and height for pixel density. |
+| height          | number  | 600       | Maximum height an image can be delivered as. |
+| width           | number  | 800       | Maximum width an image can be delivered as.  |
+
+It's important to note that this will not change the width or height attribute of the image within the DOM, this will only be the image that is being delivered by Cloudinary.
+
 ## Environment Variables
 
 | Name                   | Required | Example  | Description |

netlify-plugin-cloudinary/manifest.yml

@@ -21,6 +21,9 @@ inputs:
     required: false
     description: "The method in which in which images are loaded (Ex: lazy, eager)"
     default: "lazy"
+  - name: maxSize
+    required: false
+    description: "Maximum dimensions (width and height) for an image to be delivered"
   - name: privateCdn
     required: false
     description: "Enable Private CDN Distribution (Advanced Plan Users)"

netlify-plugin-cloudinary/src/index.ts

@@ -2,11 +2,14 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { glob } from 'glob';
 
+import { Inputs } from './types/integration';
+
 import {
   configureCloudinary,
   updateHtmlImagesToCloudinary,
   getCloudinaryUrl,
   Assets,
+  getTransformationsFromInputs
 } from './lib/cloudinary';
 import { findAssetsByPath } from './lib/util';
 
@@ -62,20 +65,7 @@ type Constants = {
   SITE_ID: string;
 };
 
-/**
- * this type is built based on the content of the plugin manifest file
- * Information found here https://docs.netlify.com/integrations/build-plugins/create-plugins/#inputs
- */
-type Inputs = {
-  cloudName: string;
-  cname: string;
-  deliveryType: string;
-  folder: string;
-  imagesPath: string | Array<string>;
-  loadingStrategy: string;
-  privateCdn: boolean;
-  uploadPreset: string;
-};
+
 
 type Utils = {
   build: {
@@ -143,6 +133,7 @@ export async function onBuild({
     imagesPath = CLOUDINARY_ASSET_DIRECTORIES.find(
       ({ inputKey }) => inputKey === 'imagesPath',
     )?.path,
+    maxSize,
     privateCdn,
     uploadPreset,
   } = inputs;
@@ -185,6 +176,8 @@ export async function onBuild({
     privateCdn,
   });
 
+  const transformations = getTransformationsFromInputs(inputs);
+
   // Look for any available images in the provided imagesPath to collect
   // asset details and to grab a Cloudinary URL to use later
 
@@ -216,6 +209,7 @@ export async function onBuild({
           localDir: PUBLISH_DIR,
           uploadPreset,
           remoteHost: host,
+          transformations
         });
 
         return {
@@ -283,6 +277,7 @@ export async function onBuild({
               folder,
               path: `${cldAssetUrl}/:splat`,
               uploadPreset,
+              transformations
             });
 
             netlifyConfig.redirects.unshift({
@@ -367,6 +362,8 @@ export async function onPostBuild({
     privateCdn,
   });
 
+  const transformations = getTransformationsFromInputs(inputs);
+
   // Find all HTML source files in the publish directory
 
   const pages = glob.sync(`${PUBLISH_DIR}/**/*.html`);
@@ -382,6 +379,7 @@ export async function onPostBuild({
         folder,
         localDir: PUBLISH_DIR,
         remoteHost: host,
+        transformations
       });
 
       await fs.writeFile(page, html);

netlify-plugin-cloudinary/src/lib/cloudinary.ts

@@ -2,11 +2,13 @@ import crypto from 'crypto'
 import path from 'path'
 import fetch from 'node-fetch'
 import { JSDOM } from 'jsdom'
-import { v2 as cloudinary, ConfigOptions } from 'cloudinary'
+import { v2 as cloudinary, ConfigOptions, TransformationOptions } from 'cloudinary'
 
 import { isRemoteUrl, determineRemoteUrl } from './util'
 import { ERROR_CLOUD_NAME_REQUIRED } from '../data/errors'
 
+import { Inputs } from '../types/integration';
+
 type CloudinaryConfig = {
   apiKey?: string;
   apiSecret?: string;
@@ -52,11 +54,13 @@ type OtherDelivery = {
   deliveryType: Omit<DeliveryType, 'fetch'>;
   remoteHost?: string
 }
-type CloudinaryOptions = {
+
+export type CloudinaryOptions = {
   folder: string,
   path: string;
   localDir?: string;
   uploadPreset: string;
+  transformations?: Array<TransformationOptions>;
 } & (FetchDelivery | OtherDelivery)
 
 export type Assets = {
@@ -139,6 +143,7 @@ export async function getCloudinaryUrl(options: CloudinaryOptions) {
     path: filePath,
     localDir,
     remoteHost,
+    transformations = [],
     uploadPreset,
   } = options
 
@@ -232,6 +237,7 @@ export async function getCloudinaryUrl(options: CloudinaryOptions) {
         fetch_format: 'auto',
         quality: 'auto',
       },
+      ...transformations
     ],
   })
 
@@ -267,6 +273,7 @@ export async function updateHtmlImagesToCloudinary(html: string, options: Update
     localDir,
     remoteHost,
     loadingStrategy = 'lazy',
+    transformations
   } = options
 
   const errors = []
@@ -292,7 +299,6 @@ export async function updateHtmlImagesToCloudinary(html: string, options: Update
 
     // If we don't have an asset and thus don't have a Cloudinary URL, create
     // one for our asset
-
     if (!cloudinaryUrl) {
       try {
         const { cloudinaryUrl: url } = await getCloudinaryUrl({
@@ -302,6 +308,7 @@ export async function updateHtmlImagesToCloudinary(html: string, options: Update
           localDir,
           uploadPreset,
           remoteHost,
+          transformations
         })
         cloudinaryUrl = url
       } catch (e) {
@@ -372,3 +379,22 @@ export async function updateHtmlImagesToCloudinary(html: string, options: Update
   }
 }
 
+/**
+ * getTransformationsFromInputs
+ */
+
+export function getTransformationsFromInputs(inputs: Inputs) {
+  const { maxSize } = inputs;
+
+  const transformations: CloudinaryOptions['transformations'] = [];
+
+  if ( typeof maxSize === 'object' ) {
+    transformations.push({
+      height: maxSize.height,
+      width: maxSize.width,
+      crop: 'limit',
+      dpr: maxSize.dpr
+    })
+  }
+  return transformations;
+}

netlify-plugin-cloudinary/src/types/integration.ts

@@ -0,0 +1,19 @@
+/**
+ * this type is built based on the content of the plugin manifest file
+ * Information found here https://docs.netlify.com/integrations/build-plugins/create-plugins/#inputs
+ */
+export type Inputs = {
+  cloudName: string;
+  cname: string;
+  deliveryType: string;
+  folder: string;
+  imagesPath: string | Array<string>;
+  loadingStrategy: string;
+  maxSize: {
+    dpr: number | string;
+    height: number;
+    width: number;
+  };
+  privateCdn: boolean;
+  uploadPreset: string;
+};

netlify-plugin-cloudinary/tests/lib/cloudinary.test.js

@@ -106,6 +106,24 @@ describe('lib/util', () => {
     //   expect(cloudinaryUrl).toEqual(`https://res.cloudinary.com/${process.env.CLOUDINARY_CLOUD_NAME}/image/upload/f_auto,q_auto/vtYmp1x-ae71a79c9c36b8d5dba872c3b274a444`);
     // });
 
+    test('should apply transformations', async () => {
+      const maxSize = {
+        width: 800,
+        height: 600,
+        dpr: '3.0',
+        crop: 'limit'
+      }
+      const { cloudinaryUrl } = await getCloudinaryUrl({
+        deliveryType: 'fetch',
+        path: '/images/stranger-things-dustin.jpeg',
+        localDir: '/tests/images',
+        remoteHost: 'https://cloudinary.netlify.app',
+        transformations: [maxSize]
+      });
+
+      expect(cloudinaryUrl).toEqual(`https://res.cloudinary.com/${process.env.CLOUDINARY_CLOUD_NAME}/image/fetch/f_auto,q_auto/c_${maxSize.crop},dpr_${maxSize.dpr},h_${maxSize.height},w_${maxSize.width}/https://cloudinary.netlify.app/images/stranger-things-dustin.jpeg`);
+    });
+
   });
 
   describe('updateHtmlImagesToCloudinary', () => {