Integrating Cloudinary with Next.js

Next.js is a React.js-based web application framework that gives developers tools that extend React capabilities including data fetching and page rendering.

Cloudinary works complementary with Next.js allowing developers to take advantage of modern tooling while being able to build performant web apps with automatic optimization and use powerful media features like dynamic cropping and other transformations.

Prerequisites

Before getting started, ensure you have:

• Basic knowledge of React and Next.js fundamentals
• Node.js 16.8 or later installed
• A free Cloudinary account with your cloud name (sign up for one here)
  

Using Cloudinary with Next.js

There are three main options for getting started with using Cloudinary in Next.js.

Next Cloudinary (Recommended)

This is recommended for most projects because it provides the most complete feature set while following Next.js best practices.

Next Cloudinary is a community-built library maintained by the Cloudinary Developer Experience team that wraps the Next.js Image component with Cloudinary’s optimization capabilities. It’s mainly designed to enhance the default Next.js Image component with advanced Cloudinary features, while still fully supporting Next.js conventions.

The CldImage component wraps the Next.js Image component, extending the features with the power of Cloudinary tech.

This includes features beyond automatic optimization like dynamic cropping and resizing, background removal, and image and text overlays.

For basic usage, first install the package with:

yarn add next-cloudinary
# or
npm install next-cloudinary

Add your Cloudinary environment variables in `.env.local`:

NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"

And use the component in your project:

import { CldImage } from 'next-cloudinary';
<CldImage
  width="600"
  height="600"
  src="<Public ID>"

The CldOgImage component uses the same APIs as CldImage to easily generate social media cards for your website.

And to easily upload images and videos to Cloudinary the CldUploadWidget is a drop-in solution that wraps the Cloudinary Upload Widget for Next.js.

Learn more about all of the features at: https://next-cloudinary.spacejelly.dev/

Next.js Image Component Cloudinary Loader

When using the built-in Next.js Image component, you can specify to use the Cloudinary Loader to deliver your images using Cloudinary with basic included features including resizing and optimization.

Note: These instructions are compatible with Next.js 13+ using the App Router. As of Next.js 13, you must configure the loader directly on the Image component:

<Image … loader={<Loader Function>} />

Note: The Next Cloudinary library above handles this for you, acting as a wrapper around the Next.js Image component.

Next.js Image Component Allowed Domain

You can use the Next.js Image component with Next.js features by adding Cloudinary as an “allowed domain”.

This does not rely on Cloudinary for delivery, but uses Next.js and the platform the project is deployed on to dynamically serve the Cloudinary-sourced image from a serverless function.

> Note: This isn’t our recommended solution as this prevents the Cloudinary CDN from fully functioning with the Next.js processing and delivery in front of the Cloudinary URL request.

In your `next.config.js` file add the following to your configuration:

images: {
  domains: ['res.cloudinary.com']
}

Find a full example over on Github

Cloudinary React SDK

Next.js is built on top of React.js which allows you to use the Cloudinary React SDK.

Learn more about the available components, widgets, and tools on the Cloudinary docs: https://cloudinary.com/documentation/react_integration

Or find examples on GitHub.

Integration Methods Comparison

Integration Methods Comparison

When to Use Each Method

• Choose Next Cloudinary if you want the best balance of features and Next.js compatibility, or need advanced transformations, uploads, or social cards.
• Choose Cloudinary Loader if you’re already using the Next.js Image component and only need basic optimization.
• Choose Allowed Domain only for quick prototypes where CDN performance isn’t critical.
• Choose React SDK if you need direct access to Cloudinary’s full API or are building complex media workflows.

Frequently Asked Questions

What’s the difference between Next Cloudinary and the Cloudinary React SDK?

Next Cloudinary is specifically built for Next.js and wraps the Next.js Image component, providing optimized integration with Next.js patterns. The React SDK is a general-purpose library for any React application and offers direct access to Cloudinary’s full API but isn’t optimized for Next.js-specific features.

Is Next Cloudinary officially supported by Cloudinary?

Next Cloudinary is a community-developed library maintained by the Cloudinary Developer Experience team. Bug fixes and feature requests should be submitted to the Next Cloudinary GitHub repository.

Which integration method is best for production applications?

For most production applications, Next Cloudinary is recommended because it provides the most complete feature set, follows Next.js best practices, and leverages Cloudinary’s CDN for optimal performance.

More Resources

Learn more about how to use Cloudinary with Next.js:

• Build Performant, Engaging Experiences in Next.js with Next Cloudinary
• Optimize Images, Responsive Sizing, & AI Cropping in Next.js with Next Cloudinary
• How to Optimize Images with Responsive Sizes & AI Cropping in Next.js with Next Cloudinary
• Next Cloudinary Docs
• Cloudinary Next.js Examples