Skip to content

⚡️ High-performance image delivery and uploading at scale in Next.js powered by Cloudinary.

License

Notifications You must be signed in to change notification settings

cloudinary-community/next-cloudinary

Repository files navigation

Cloudinary    Nextjs

GitHub Workflow Status npm npm bundle size GitHub

Next Cloudinary

High-performance image delivery and uploading at scale in Next.js powered by Cloudinary.

FeaturesGetting StartedCommunity & SupportContributing

This is a community library supported by the Cloudinary Developer Experience team.

✨ Features

  • Automatically optimize images and deliver in modern formats
  • Remove backgrounds from images
  • Dynamically add image and text overlays to images
  • AI-based cropping and resizing
  • Transform images using color and effects
  • Generate Open Graph Social Media cards on the fly
  • Drop-in Upload Widget
  • ...all at scale with Cloudinary

🚀 Getting Started

Installation

  • Install next-cloudinary with:
npm install next-cloudinary
  • Add an environment variable with your Cloud Name:
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"

Adding an Image

import { CldImage } from 'next-cloudinary';

<CldImage width="600" height="600" src="<Public ID or Cloudinary URL>" alt="<Alt Text>" />

Learn more about CldImage on the Next Cloudinary Docs

Generating an Social Media Card (Open Graph)

<CldOgImage src="<Public ID or Cloudinary URL>" text="Next Cloudinary" />

Note: The width and height is not required (or recommended) to comply with standardized social media card sizing of a 2:1 aspect ratio.

Learn more about CldOgImage on the Next Cloudinary Docs

Other Use Cases

❤️ Community & Support

🛠 Contributing

Please read CONTRIBUTING.md prior to contributing.

Working Locally

Installation

This project is using pnpm as a way to manage dependencies and workspaces.

With the project cloned, install the dependencies from the root of the project with:

pnpm install

Configuration

To work on the project, you need to have an active Cloudinary account. With the account, configure a .env.local file inside of docs with:

NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloudinary Cloud Name>"
NEXT_PUBLIC_CLOUDINARY_API_KEY="<Your Cloudinary API Key>"
CLOUDINARY_API_SECRET="<Your Cloudinary API Secret>"

Note: The Cloudinary account can be free, but some features may not work beyond free tier like Background Removal

The Cloud Name is required for all usage, where the API Key and Secret currently is only used for Upload Widget usage. The Upload Preset is additionally used for the Upload Widgets.

Uploading Example Images

In order to run the Docs project, you need to have the images referenced available inside of your Cloudinary account.

To do this, navigate to the scripts directory and first create a new .env file with:

CLOUDINARY_CLOUD_NAME="<Your Cloudinary Cloud Name>"
CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"

Then run the upload script with:

pnpm upload

By default, the images inside of scripts/images.json will be uploaded to the "images" directory inside of your Cloudinary account. To change the location, add the CLOUDINARY_IMAGES_DIRECTORY environment variable with your preferred directory:

CLOUDINARY_IMAGES_DIRECTORY="<Your Directory>"

Running the Project

Once installed and configured, open two terminal tabs, navigating one to next-cloudinary and one to docs, running the following command in each:

pnpm dev

The project will now be available at https://localhost:3000 or the configured local port.

Running Tests

All tests are located inside of next-cloudinary/tests with a directory structure that should reflect next-cloudinary/src.

While inside next-cloudinary, run tests with:

pnpm test

Contributors

Colby Fayock
Colby Fayock

💻 📖 💡
Daniel Olavio
Daniel Olavio

💻
ramadevsign
ramadevsign

🔧
Karey Higuera
Karey Higuera

⚠️ 💻
Azanul Haque
Azanul Haque

🔧
3t8
3t8

📖
John Agbanusi
John Agbanusi

💻 📖
Joan León
Joan León

📖
Tim Benniks
Tim Benniks

💻 📖
csgochan
csgochan

📖
codingis4noobs2
codingis4noobs2

💻 ⚠️
michizhou
michizhou

💻
Lee Conlin
Lee Conlin

💻
Ryan Smith
Ryan Smith

💻
Michael Liendo
Michael Liendo

📖
Jack
Jack

💻
Matheus Cabral
Matheus Cabral

💻
Jose Morales
Jose Morales

💻
Eric Pfister
Eric Pfister

💻
Joshua Olorunnipa
Joshua Olorunnipa

💻
Hari
Hari

📖
Shoaib Asgar
Shoaib Asgar

💻
Adeyanju Adeyemi
Adeyanju Adeyemi

💻
Simon
Simon

📖
Richard Oliver Bray
Richard Oliver Bray

💻
zecka
zecka

💻
Harshit Vashisht
Harshit Vashisht

📖
Sahil Silare
Sahil Silare

💻
Yash Mathur
Yash Mathur

💻