You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Optimize and serve all images served in your Netlify site deploy with [Cloudinary](https://cloudinary.com/).
Optimize and serve all images served in your Netlify site, deploy with [Cloudinary](https://cloudinary.com/).
The Cloudinary plugin hooks into your Netlify build process and sets up images for optimization and delivery. First, the plugin replaces all your on-page, post-compilation images with a Cloudinary-sourced URL, greatly accelerating your initial page load. Next, for comprehensive coverage, Cloudinary redirects assets requested from your images directory to a Cloudinary URL with the default fetch feature or the upload delivery type.
The Cloudinary plugin hooks into your Netlify build process and sets up images for optimization and delivery. First, the plugin replaces all your on-page, post-compilation images with a Cloudinary-sourced URL, greatly accelerating your initial page load. Next, for comprehensive coverage, Cloudinary redirects assets requested from your images' directory to a Cloudinary URL with the default fetch feature or the upload delivery type.
tl;dr automatically serves smaller images in modern formats
Tl;dr automatically serves smaller images in modern formats
**This plugin is not officially supported by Cloudinary.**
Expand All
@@ -34,7 +34,7 @@ tl;dr automatically serves smaller images in modern formats
Before installing, make sure you're set up with a free [Cloudinary](https://cloudinary.com/) account.
### Installing via Netlify UI
### Installing via the Netlify UI
- [Install the plugin](https://app.netlify.com/plugins/netlify-plugin-cloudinary/install) using the [Netlify Build Plugins Directory](https://app.netlify.com/plugins)
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.
By default, the aspect ratio of the images is preserved, so by specifying both a maximum width and height, you're telling Cloudinary to scale the image down so that neither the width nor 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.
| dpr | string | 2.0 | Device Pixel Ratio which essentially multiplies the width and height for pixel density. |
| 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. |
Expand All
@@ -130,7 +130,7 @@ It's important to note that this will not change the width or height attribute o
### Setting your Cloud Name
You have two options for setting your Cloud Name: plugin input or environment variable.
You have two options for setting your Cloud Name: plugin input or an environment variable.
**Input**
Expand All
@@ -157,9 +157,9 @@ Learn how to [set environment variables with Netlify](https://docs.netlify.com/c
Default - no additional configuration needed.
The fetch method allows you to use Cloudinary delivery by providing a remote URL. Learn more about using delivering remote images with [fetch](https://cloudinary.com/documentation/fetch_remote_images).
The fetch method allows you to use Cloudinary delivery by providing a remote URL. Learn more about delivering remote images with [fetch](https://cloudinary.com/documentation/fetch_remote_images).
> Note: if you are currently restricting Fetched URLs, you need to ensure your Netlify URL is listed under allowed fetch domains. Older accounts may restrict fetched images by default. Read more about [restricting the allowed fetch domains](https://cloudinary.com/documentation/fetch_remote_images#restricting_the_allowed_fetch_domains).
> Note: if you are currently restricting Fetched URLs, you need to ensure your Netlify URL is listed under allowed fetch domains. Older accounts may restrict the fetched images by default. Read more about [restricting the allowed fetch domains](https://cloudinary.com/documentation/fetch_remote_images#restricting_the_allowed_fetch_domains).
**upload - Unsigned**
Expand DownExpand Up
@@ -223,27 +223,27 @@ Inside your Netlify config:
### I'm using the default settings but my images 404
The plugin uses the fetch method by default and if you're receiving a 404 with a valid URL and valid Cloudinary account, you may be currently restricting fetched URLs.
The plugin uses the fetch method by default, and if you're receiving a 404 with a valid URL and a valid Cloudinary account, you may be currently restricting fetched URLs.
You have two options to resolve this: adding your Netlify domain to the list of "allowed fetch domains" and removing the fetched URL restriction.
Adding your domain to the "allowed fetch domains" list is more secure by not allowing others to use your Cloudinary account with their own images. You can do this under Settings > Security > Allowed fetch domains.
Adding your domain to the "allowed fetch domains" list makes it more secure by not allowing others to use your Cloudinary account with their own images. You can do this under Settings > Security > Allowed fetch domains.
Alternatively, you can remove the restriction and allow all fetched images to work by going to Settings > Security > Restricted media types and unchecking the box for Fetched URL.
## ⚙️ How It Works
### Delivery Part 1: Replacing all static, on-page images with Cloudinary URLs
During the Netlify build process, the plugin is able to tap into the `onPostBuild` hook where we use [jsdom](https://github.com/jsdom/jsdom) to create a node-based representation of the DOM for each output HTML file, then walk through each node, and if it's an image, we replace the source with a Cloudinary URL.
During the Netlify build process, the plugin is able to tap into the `onPostBuild` hook, where we use [jsdom](https://github.com/jsdom/jsdom) to create a node-based representation of the DOM for each output HTML file, then walk through each node, and if it's an image, we replace the source with a Cloudinary URL.
Depending on the configuration, we'll either use the full URL for that image with the [Cloudinary fetch API](https://cloudinary.com/documentation/fetch_remote_images) or alternatively that image will be [uploaded](https://cloudinary.com/documentation/upload_images), where then it will be served by public ID from the Cloudinary account.
Depending on the configuration, we'll either use the full URL for that image with the [Cloudinary fetch API](https://cloudinary.com/documentation/fetch_remote_images) or alternatively that image will be [uploaded](https://cloudinary.com/documentation/upload_images), where it will be served by a public ID from the Cloudinary account.
While this works great for a lot of cases and in particular the first load of that page, using a framework with clientside routing or features that mutate the DOM may prevent that Cloudinary URL from persisting, making all of that hard work disappear, meaning it will be served from the Netlify CDN or original remote source (which is fine, but that leads us to Part 2).
While this works great for a lot of cases, and in particular the first load of that page, using a framework with clientside routing or features that mutate the DOM may prevent that Cloudinary URL from persisting, making all of that hard work disappear, meaning it will be served from the Netlify CDN or original remote source (which is fine, but that leads us to Part 2).
### Delivery Part 2: Serving all assets from the /images directory from Cloudinary
To provide comprehensive coverage of images being served from Cloudinary, we take advantage of Netlify's dynamic redirects and serverless functions to map any image being served from the /images directory (or the configured `imagesPath`), redirect it to a serverless function, which then gets redirected to a Cloudinary URL.
To provide comprehensive coverage of images being served from Cloudinary, we take advantage of Netlify's dynamic redirects and serverless functions to map any image being served from the /images directory (or the configured `imagesPath`) and redirect it to a serverless function, which then gets redirected to a Cloudinary URL.
Through this process, we're still able to afford the same option of using either the fetch or upload API depending on preference, where the latter would be uploaded if it's a new asset within the serverless function.
Expand DownExpand Up
@@ -274,7 +274,7 @@ Which will combine the build and deploy contexts and run through the full proces
### Demo
The repository additionally includes a demo that uses the plugin. The demo is a simple Next.js application that lows a few images statically and those same images in a separate list once the page loads. This helps us test both the on-page image replacement and the redirecting of the images directory.
The repository additionally includes a demo that uses the plugin. The demo is a simple Next.js application that loads a few images statically and those same images in a separate list once the page loads. This helps us test both the on-page image replacement and the redirecting of the images' directory.
You can link this project to your Netlify account for testing purposes by creating a new Netlify site at the root of this project and linking it to that new site.
Expand All
@@ -286,7 +286,7 @@ netlify deploy --build
### Tests
Tests require all environment variables to be actively set pass. See [configuration](#-configuration) above to see which variables need to be set.
Tests require all environment variables to be actively set to pass. See the [configuration](#-configuration) above to see which variables need to be set.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
@@ -24,10 +24,10 @@ import OgImage from '../../components/OgImage';
The fetch method allows you to use Cloudinary delivery by providing a remote URL.
<Callout emoji={false}>
If you are currently restricting Fetched URLs, you need to ensure your Netlify URL is listed under allowed fetch domains. Older accounts may restrict fetched images by default. Read more about [restricting the allowed fetch domains](https://cloudinary.com/documentation/fetch_remote_images#restricting_the_allowed_fetch_domains).
If you are currently restricting Fetched URLs, you need to ensure your Netlify URL is listed under allowed fetch domains. Older accounts may restrict the fetched images by default. Read more about [restricting the allowed fetch domains](https://cloudinary.com/documentation/fetch_remote_images#restricting_the_allowed_fetch_domains).
</Callout>
Learn more about using delivering remote images with [fetch](https://cloudinary.com/documentation/fetch_remote_images).
Learn more about delivering remote images with [fetch](https://cloudinary.com/documentation/fetch_remote_images).
## Unsigned Uploads
Expand DownExpand Up
@@ -72,9 +72,9 @@ CLOUDINARY_API_SECRET="[Your Cloudinary API Secret]"
```
<Callout emoji={false}>
Environment variables need to be configured in any environment that you're building your Netlify site.
Environment variables need to be configured in any environment in which you're building your Netlify site.
</Callout>
Uploading media to Cloudinary gives you more flexibility with your media upon delivery.
Learn more about [signed uploads](https://cloudinary.com/documentation/upload_images#uploading_assets_to_the_cloud).
Learn more about [signed uploads](https://cloudinary.com/documentation/upload_images#uploading_assets_to_the_cloud).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
@@ -48,7 +48,7 @@ import OgImage from '../components/OgImage';
### Deploy!
The Cloudinary Build Plugin runs during your Netlify build, meaning, you need to trigger a new deploy to see it in action.
The Cloudinary Build Plugin runs during your Netlify build, meaning you need to trigger a new deployment to see it in action.
</Steps>
</Tab>
Expand DownExpand Up
@@ -88,17 +88,17 @@ import OgImage from '../components/OgImage';
During the Netlify build process, the plugin is able to tap into the `onPostBuild` hook where we use [jsdom](https://github.com/jsdom/jsdom) to create a node-based representation of the DOM for each output HTML file, then walk through each node, and if it's an image, we replace the source with a Cloudinary URL.
Depending on the configuration, we'll either use the full URL for that image with the [Cloudinary fetch API](https://cloudinary.com/documentation/fetch_remote_images) or alternatively that image will be [uploaded](https://cloudinary.com/documentation/upload_images), where then it will be served by public ID from the Cloudinary account.
Depending on the configuration, we'll either use the full URL for that image with the [Cloudinary fetch API](https://cloudinary.com/documentation/fetch_remote_images) or alternatively, that image will be [uploaded](https://cloudinary.com/documentation/upload_images), where then it will be served by a public ID from the Cloudinary account.
While this works great for a lot of cases and in particular the first load of that page, using a framework with clientside routing or features that mutate the DOM may prevent that Cloudinary URL from persisting, making all of that hard work disappear, meaning it will be served from the Netlify CDN or original remote source (which is fine, but that leads us to Part 2).
While this works great for a lot of cases, and in particular the first load of that page, using a framework with client-side routing or features that mutate the DOM may prevent that Cloudinary URL from persisting, making all of that hard work disappear, meaning it will be served from the Netlify CDN or original remote source (which is fine, but that leads us to Part 2).
### Delivery Part 2: Serving all assets from the /images directory from Cloudinary
To provide comprehensive coverage of images being served from Cloudinary, we take advantage of Netlify's dynamic redirects and serverless functions to map any image being served from the /images directory (or the configured `imagesPath`), redirect it to a serverless function, which then gets redirected to a Cloudinary URL.
To provide comprehensive coverage of images being served from Cloudinary, we take advantage of Netlify's dynamic redirects and serverless functions to map any image being served from the /images directory (or the configured `imagesPath`) and redirect it to a serverless function, which then gets redirected to a Cloudinary URL.
Through this process, we're still able to afford the same option of using either the fetch or upload API depending on preference, where the latter would be uploaded if it's a new asset within the serverless function.
Through this process, we're still able to afford the same option of using either the fetch or upload API, depending on preference, where the latter would be uploaded if it's a new asset within the serverless function.
## Using Netlify Cloudinary
* [Configuration](/configuration): Learn how to configure the Cloudinary Build Plugin for Netlify
* [Configuration](/configuration): Learn how to configure the Cloudinary Build Plugin for Netlify
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
@@ -18,10 +18,10 @@ import OgImage from '../../components/OgImage';
## I'm using the default settings, but my images 401
The plugin uses the fetch method by default and if you're receiving a 401 with a valid URL and valid Cloudinary account, you may be currently restricting fetched URLs.
The plugin uses the fetch method by default, and if you're receiving a 401 with a valid URL and a valid Cloudinary account, you may be currently restricting fetched URLs.
You have two options to resolve this: adding your Netlify domain to the list of "allowed fetch domains" and removing the fetched URL restriction.
Adding your domain to the "allowed fetch domains" list is more secure by not allowing others to use your Cloudinary account with their own images. You can do this under Settings > Security > Allowed fetch domains.
Adding your domain to the "allowed fetch domains" list makes it more secure by not allowing others to use your Cloudinary account with their own images. You can do this under Settings > Security > Allowed fetch domains.
Alternatively, you can remove the restriction and allow all fetched images to work by going to Settings > Security > Restricted media types and unchecking the box for Fetched URL.
Alternatively, you can remove the restriction and allow all fetched images to work by going to Settings > Security > Restricted media types and unchecking the box for Fetched URL.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.