DEV Community: Cloudinary

Ship Your Next Great Web App in Record Time with create-cloudinary-react

Eric Portis — Tue, 07 Apr 2026 19:53:07 +0000

Over the past year or two, we've been having a lot of conversations about the future of Cloudinary's Libraries and SDKs. The conversations have been wide-ranging: the future of front-end frameworks, coding, and AI. It's all been a bit dizzying, and hard to wrap our heads around.

Late last year, my colleague Raya Straus brought us back down to earth with some good old-fashioned user research. By engaging users in conversations about their current day-to-day experiences, Raya got us to stop worrying about the future, and start thinking about ways we could make developers more successful with Cloudinary right now.

We released the first fruit of Raya's research last month: Cloudinary's React Starter Kit. If you're building a green-field, media-focused React app, and you're using LLM-powered development tools, we think npx create-cloudinary-react is the best way to get started.

Before we get into what it is, let's talk about how and why we built it.

What We Learned From React SDK User Research

We limited our research scope to two of our most popular SDKs: React and Next.js. We looked at every piece of user feedback for those two SDKs that we could find: support tickets, GitHub issues, chat transcripts, survey responses, and even a number of individual conversations held over email and Zoom, after we reached out to top SDK users.

Once we'd collected and digested it all, three things stuck out:

Many developers struggle to get started. The least fun part of any development project is setting up a working development environment; a handful of common config problems are tripping up many developers before they can take their first steps with Cloudinary.
Once set up, features that solve common use cases were straightforward and people were quickly successful. Cloudinary and our SDKs do a great job of solving common use cases with a minimum of fuss. Great!
But once use cases get more advanced, developers start to struggle again. Cloudinary is a mature product, and can do all sorts of things, but advanced features are more complicated to use. Niche functionality often has fiddlier syntax, less clear error messages, and trickier-to-find documentation. So even though the features are there, developers run into walls when trying to use them.

How the React Starter Kit Works

So, the question we ended up with, was: How can we help developers who are just getting started with Cloudinary, and folks with complex use cases?

We think we can address both with one new tool: npx create-cloudinary-react.

Type that into a terminal near you and you'll be led through a wizard, which will ask you a few questions about your environment. Then, it will spin up a working React project for you, using Vite as a build tool, and handle all of the configuration that people who are just starting to use Cloudinary with React so often get stuck on. The resulting project starts with a simple, one-page website that accepts and displays user-generated image uploads.

In addition to doing basic configuration, the wizard also installs Cloudinary's LLM-specific tools, and puts a bunch of rules and troubleshooting guidance to help LLMs with Cloudinary's APIs wherever your particular LLM-powered coding environment looks for context.

We derived these rules from our user research, by feeding all of the feedback we received about using Cloudinary's React SDK into an LLM and asking it to write rules to address that feedback. From there, we refined, added, and subtracted rules based on our experiences of using and helping other folks use Cloudinary.

Those rules, in addition to our other LLM-specific tools, significantly improve LLMs' results when prompted with complex tasks. To show off those capabilities, the initial built project offers a handful of example prompts which you can copy, paste into your agent, and hit the ground running.

With create-cloudinary-react, we believe we've built something that helps everyone get started, and also helps folks who have gone beyond common use cases use all of the nooks and crannies of Cloudinary's extensive feature set.

See the React Starter Kit in Action

Here's create-cloudinary-react in action:

How the React Starter Kit performed at Hack Canada 2026

After a few rounds of internal development and testing, we soft-launched the React Starter Kit a few weeks ago -- just before we participated as a sponsor in this year's Hack Canada.

A hackathon is a perfect environment for this kind of tool, and the results blew us away. Participants leveraged the Starter Kit to produce some truly incredible projects, and cited create-cloudinary-react as part of their success.

That was all the validation we needed to add a React Starter Kit walk through to our documentation and announce it in this very blog post.

So, go! Try it out! And tell us what you think in the comments.

Managing Media Files in Flask (Images, Videos, and Audio)

Sharon Yelenik — Mon, 23 Mar 2026 19:07:00 +0000

You’re building an app for a small business or website, maybe a portfolio site or boutique store, and you know high-quality visuals are key for attracting buyers and showcasing your work. But without a designer on the team, you’re responsible for handling all the images and videos yourself.

So how do you manage a moderate amount of media files in the simplest and most efficient way?

In this blog post, we’ll unveil transformative techniques for managing media files in Flask with Cloudinary to make your life easier as a developer.

Benefits of Streamlined Media Management

Before we get into the practical steps, here some of the advantages of establishing a solid media management approach in your Flask application:

Less custom code and reduced storage complexity. Offloading large media files from your database or filesystem keeps your application simpler and avoids managing bulky binary data.
Reliable uploads that scale. A predictable upload flow prevents issues with file size limits, timeouts, or custom route handling, especially when users submit large images or videos.
Consistent, high-quality digital media. Automated tasks like resizing, compression, tagging, and background removal help keep your images and videos optimized without manual editing.
Optimized, searchable delivery. Well-structured metadata and scalable search make assets easier to find, while delivering the right size and format improves performance across devices.

By storing your digital media in Cloudinary instead of on your server or in your database, you can take advantage of these benefits immediately, while keeping your Flask codebase lightweight and focused on application logic.

Managing media files in Flask becomes much simpler with the steps we cover next (tap the icons to navigate to the related section):

Setup and Configuration

Before we dive into the specifics of media management with Python and Flask, you'll need to sign up for Cloudinary. It's quick and straightforward.

Installing and Configuring Cloudinary in Your Python/Flask App

To get started with Cloudinary in your Python/Flask app, follow these steps:

Install the Cloudinary Python library using pip install cloudinary.
Configure Cloudinary in your Flask application, typically inside app.py or a separate config.py file:

# config.py or app.py
import cloudinary
import cloudinary.uploader
import cloudinary.api

cloudinary.config(
    cloud_name="your_cloud_name",
    api_key="your_api_key",
    api_secret="your_api_secret"
)

Note: Replace your_cloud_name, your_api_key, and your_api_secret with your actual Cloudinary credentials, which you can find on the API keys page of the Console Settings.

If you're using a config.py, you'd load it in your Flask app like this:

from flask import Flask
import config  # or your preferred config structure

app = Flask(__name__)

With these steps, you've successfully integrated Cloudinary into your Flask project, and you're ready to leverage its powerful media management capabilities.

Enhanced Media Processing With Upload Presets

Upload presets in Cloudinary help you automate your media workflow by applying transformations, metadata rules, and upload behaviors the moment a file arrives. This means less processing in your Flask routes and far more consistent results across all your media.

In this article, we’ll focus on two powerful capabilities you can unlock through presets: automated transformations and auto-tagging. You can explore many other preset options in Cloudinary’s documentation, but these two alone can dramatically simplify your media pipeline.

Automating Transformation Settings

Upload presets allow you to automatically apply transformations such as resizing, cropping, recoloring, background removal, and more, without writing additional code in Flask. For example, you can create presets that remove backgrounds from uploaded logos, ensure all portfolio images are a consistent size, or sharpen older or lower-quality photos.

Each preset applies its rules automatically when the file is uploaded.

Tip: By applying the g_auto AI-powered transformation, you can ensure that crops preserve the important parts of your images and keep the main subject of your videos in focus.

By defining these settings once, every uploaded media file stays consistent and optimized with no manual editing or external image processing tools required.

Leveraging Auto-TaggingCopy link to this heading
If you enable auto-tagging through Cloudinary’s categorization engines, images are automatically analyzed and tagged based on their content. These tags can support a variety of downstream tasks, including:

organizing assets
improving searchability
enabling content discovery
powering filters in your UI or internal tools

For example, an image of a woman on a city street using a smartphone and carrying a bag might receive tags such as “woman,” “bag,” “mobile phone,” “purse,” or “car,” depending on the AI model you use.

Important: Important: To use auto-tagging, you’ll need to subscribe to one of Cloudinary’s auto-tagging add-ons. The examples in this blog use the Rekognition Auto Tagging add-on.

Red-haired woman in stylish outfit chatting on phone

Tip: Check out the Computer Vision Image Analysis for Your E-commerce Website demo to see Cloudinary in action, returning information about the content it identifies in your images.

Creating an Upload Preset

You can create an upload preset using the Cloudinary Admin API right from your Flask application or a setup script. Here’s an example using the Python SDK:

# Define the upload preset details
upload_preset_name = "my_preset"
upload_preset_options = {
    "unsigned": False,
    "folder": "my_folder",
    "tags": "my_tags",
    "transformation": [
        {"width": 500, "height": 500, "crop": "fill"},
        {"effect": "vignette"},
    ],
    "categorization": "aws_rek_tagging",
    "auto_tagging": 0.9
}

# Create the upload preset using the SDK
upload_preset = cloudinary.api.create_upload_preset(
    name=upload_preset_name,
    settings=upload_preset_options
)

# Check if the upload preset was created successfully
if upload_preset.get("name") == upload_preset_name:
    print("Upload preset created successfully.")
else:
    print("Failed to create upload preset.")

Once created, simply reference the preset name during upload, and all rules will apply automatically.

Uploading Media With Python and Flask

Uploading files is central to your Flask workflow, and Cloudinary provides two flexible methods: the Upload Widget for client-side uploads and server-side uploads from your Flask routes.

Let’s explore both.

Upload Widget

If your app accepts user-generated content (UGC), such as portfolio images from creators or product photos submitted by small business owners, the Cloudinary Upload Widget provides a smooth, reliable upload experience directly from the browser. You can attach any upload presets you’ve created so transformations, optimization, tagging, and other processing happen automatically on upload, without additional Flask code.

Tip: You can also create a preset that automatically moderates user-uploaded images and videos to help ensure that the content appearing on your site is appropriate.

Example Use Case

A portfolio gallery or a simple shop catalog where users can upload photos or videos is an ideal scenario for the Upload Widget. It handles the entire client-side upload flow, while your presets manage all media processing in the background.

How to Implement the Upload Widget in Flask

Create a route that renders the template:

# app.py
from flask import Flask, render_template

app = Flask(__name__)

@app.route("/upload-media")
def upload_media():
    return render_template("upload_media.html")

Create the template (templates/upload_media.html):

<!DOCTYPE html>
<html>
<head>
    <title>Media Upload</title>
</head>
<body>
    <button id="upload_widget" class="cloudinary-button">Upload files</button>

    <script src="https://upload-widget.cloudinary.com/global/all.js" type="text/javascript"></script>  

    <script type="text/javascript">  
        var myWidget = cloudinary.createUploadWidget({
            cloudName: 'my_cloud_name',
            uploadPreset: 'my_preset'
        }, (error, result) => {
            if (!error && result && result.event === "success") {
                const imageUrl = result.info.secure_url;
                console.log("Done! Here is the file info: ", result.info);

                // Optional: Send imageUrl to your Flask backend
                // fetch('/save-media', { method: 'POST', body: JSON.stringify({ url: imageUrl }) })
            }
        });

        document.getElementById("upload_widget").addEventListener("click", function() {
            myWidget.open();
        }, false);
    </script>
</body>
</html>

Add the URL rule (if not using decorators):

# app.py
app.add_url_rule("/upload-media", view_func=upload_media)

Test it by visiting:

http://localhost:5000/upload-media

You now have a complete client-side upload flow, with Cloudinary handling media processing automatically.

Server-Side Upload

Server-side uploads are perfect when you need automation or want to process files uploaded through a traditional

Example Use Case

News aggregators, podcast platforms, or content curation apps often automate large-scale ingestion:

analyze images

apply tags

create captions

run moderation

convert formats

Cloudinary can handle these tasks server-side with very little code.

Uploading From Flask

from flask import request
import cloudinary.uploader

@app.route("/upload", methods=["POST"])
def upload():
    file_to_upload = request.files["file"]
    result = cloudinary.uploader.upload(
        file_to_upload,
        upload_preset="my_upload_preset"
    )
    return {"url": result["secure_url"]}

And that’s it. Your media is uploaded, transformed, stored, and ready to deliver.

Searching Made Simple

Once your assets are stored in Cloudinary, especially with auto-tagging enabled, searching becomes incredibly fast.

Instead of digging through folders or writing custom queries, you can retrieve matching media with a single expression:

def search_media_by_tags(tags):
    return cloudinary.Search().expression(f"tags:{tags}").execute()

Example queries:

tags:portrait
tags:handmade
resource_type:video AND tags:nature

Use search to build quick admin dashboards, galleries, filters, or automated content workflows.

Delivering Your Media

With Cloudinary managing your media, delivery becomes as powerful as upload. You can apply on-the-fly transformations directly in the image or video URL with no processing required in Flask.

Example: Dynamic Image Sizing in a Flask Template

<img 
  src="{{ cloudinary_url(public_id, width=width, height=height, crop='fill') }}"
  alt="Your Image"
/>

Or, using the SDK:

from cloudinary.utils import cloudinary_url

url, options = cloudinary_url(
    public_id,
    width=400,
    height=300,
    crop="fill"
)

Why It’s Powerful

You don’t store multiple versions of each image
Users automatically receive optimized formats (WebP, AVIF, MP4, etc.)
Dynamic resizing keeps your site lightweight and fast

For responsive layouts, check out:

Secret to Media File Management

In short, the features we’ve covered include upload presets, smart uploads, AI-powered search, and dynamic delivery. Apply these features to take managing media files in Flask from “painful but necessary” to “effortless and scalable.”

Instead of writing boilerplate logic for uploads, storage, and optimization, you can focus on building features your users care about.

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

How to Create a Digital Portfolio That Visually Pops

Sharon Yelenik — Mon, 23 Mar 2026 18:13:17 +0000

Job searching can be tough, and so is standing out among the competition.

When putting together job applications, there’s always that question: How should I describe myself? Will potential employers care more about past experience or a list of skills? A digital portfolio answers that question in a way a résumé alone can’t. It shows what you’re actually capable of.

That’s why I put together this digital portfolio demo project.

Instead of talking about performance, polish, and visual quality in theory, I wanted to demonstrate what that looks like in practice. This portfolio is built the way I’d recommend anyone build one today: fast, visually sharp, and optimized from the start.

In this guide, I’ll walk you through how I build a frontend portfolio project using Cloudinary to handle all the image and video magic. No endless hours in Photoshop. No massive file sizes. And, no manual resizing for every device.

Live Demo (Optional, but Highly Recommended)

Before diving into the code, you can check out the live portfolio demo here:

View the live demo on StackBlitz

Feel free to explore it, then come back and see how everything works under the hood.

Your browser does not support the video tag.

Keys to Making Your Digital Portfolio Stand Out

Building a great-looking digital portfolio is a no-brainer. However, the real question is: How do you make yours stand out? One of the biggest differentiators is focusing on performance and visual polish. When your portfolio feels fast, smooth, and thoughtfully built, it immediately comes across as more professional.

And when you build it efficiently, you’re also signaling to future employers that you know how to work efficiently:

Deliver images that load fast but look crisp.
Make videos that play smoothly without eating bandwidth.
Create responsive layouts that look perfect on every device.
Apply visual effects that make content pop.
Optimize everything without sacrificing quality.
So really, building a great portfolio is just practice for the real * thing. And that’s pretty cool.

The Tech Stack I ChoseCopy link to this heading

For my portfolio, I went with tools that are popular in the industry and honestly just fun to work with:

React 19 with TypeScript for type safety and component architecture.
Vite for lightning-fast development and optimized builds.
CSS for beautiful, responsive styling.
Cloudinary for all image and video transformations.

Feel free to clone my code and adapt it to whatever you’re used to working with.

Getting Started

I’m sharing my portfolio with you as a starting point. Once you get a feel for how it works, you can customize the design to match your style and add sections that show off what matters to you.

# Clone the starter portfolio repo
git clone https://github.com/your-username/digital-portfolio.git

# Install dependencies
cd digital-portfolio
npm install

# Start the development server
npm run dev

I’m excited to see how you make it your own.

How Cloudinary Helps Meet Stand-Out Goals

A portfolio that stands out needs to be fast, visually sharp, and responsive across devices.

Without automation, that usually means resizing images manually, generating multiple breakpoints, compressing files carefully, and managing large video assets.

Cloudinary handles image and video delivery, optimization, and transformations through simple URL parameters. In this project, cropping, resizing, blur effects, format conversion, and quality optimization are all applied directly in the media URLs.

Transformations run on the fly, and the right size and format are delivered automatically for each device and browser.

Instead of maintaining multiple asset versions or editing files manually, I define the transformation once and move on, without sacrificing quality or performance.

Swap the Demo Media for Your Own

This project uses Cloudinary’s demo account (res.cloudinary.com/demo) with sample images and videos, so it works out of the box. When you’re ready, switch to your own Cloudinary account to display your own images and videos.

Step 1: Create a Cloudinary Account

Step 2: Find Your Cloud Name

After logging in, copy your cloud name from the dashboard. You’ll use it in URLs like this:

https://res.cloudinary.com/<your_cloud_name>/image/upload/<public_id>

Step 3: Update One Line in the Code

In your project, change this:

// Set this to your cloud name when you're ready to use your own media
const CLOUDINARY_CLOUD_NAME = 'demo'

…to your cloud name:

const CLOUDINARY_CLOUD_NAME = '<your_cloud_name>'

That’s it. Since CLOUDINARY_BASE is built from CLOUDINARY_CLOUD_NAME, all image/video URLs that use CLOUDINARY_BASE will automatically point to your account.

Step 4: Upload Your Own Media and Swap the Public IDs

In your code, you reference assets using public IDs — for example:

image: 'docs/profile-pic'

That means Cloudinary is looking for an asset with the public ID docs/catwalk in your cloud.

After you upload your own images/videos to Cloudinary, replace those image values with your own public IDs, for example:

image: 'portfolio/catwalk'

Note: You don’t need to change the transformations. Everything in the URL after /upload/ (like c_fill,g_auto,h_400,w_600/f_auto/q_auto) can stay the same.

The Cool Cloudinary Features I Used

1. Smart Cropping With Face Detection

For the testimonials section, I needed consistent circular profile images that focused tightly on each person’s face.

Here’s the original image:

https://res.cloudinary.com/demo/image/upload/
docs/profile-pic.jpg

And here’s the transformed version:

https://res.cloudinary.com/demo/image/upload/c_thumb,g_face,h_300,w_300/r_max/e_sharpen:80/f_auto/q_auto/docs/profile-pic.jpg

What the Transformation Does

c_thumb,g_face automatically detects the face and crops around it.
h_300,w_300 enforces a fixed square size.
r_max makes the image circular.
e_sharpen:80 restores clarity after resizing.
f_auto,q_auto handle format and compression.

The result isn’t just a circle. It’s a consistent 300×300 headshot, centered correctly every time — regardless of how the original photo was framed.

That means no manual cropping, guessing focal points, or layout inconsistencies.

2. Hero Background Blur

For the hero section, I wanted a full-width background image that wouldn’t compete with the foreground content.

Original image:

https://res.cloudinary.com/demo/image/upload/vieste_italy.jpg

Transformed version:

https://res.cloudinary.com/demo/image/upload/c_fill,g_auto,h_1080,w_1920/e_blur:800/f_auto/q_auto/vieste_italy.jpg

What the Transformation Does

c_fill,g_auto crops intelligently to 1920×1080.
e_blur:800 applies a strong blur effect.
f_auto,q_auto optimize delivery.

The original image is detailed and high contrast — great for photography, not ideal for text overlays.

By blurring it at delivery time, I keep the color and atmosphere while removing visual noise. The background supports the content instead of competing with it. No separate “blurred copy” of the file is needed.

3. AI-Enhanced Portrait

For the hero portrait, I wanted a clean, high-quality look — even if the source image wasn’t studio-perfect.

Original:

https://res.cloudinary.com/demo/image/upload/docs/profile-pic1.jpg

Transformed:

https://res.cloudinary.com/demo/image/upload/c_fill,g_face,h_300,w_300/r_max,bo_2px_solid_green/e_enhance/f_auto/q_auto:best/docs/profile-pic1.jpg

What the Transformation Does

g_face centers the subject.
r_max applies a circular crop.
bo_2px_solid_green adds a clean, circular border.
e_enhance enhances lighting and contrast using AI.
q_auto:best balances compression with quality.

The enhancement isn’t dramatic — it’s subtle. Skin tones are more balanced, contrast is cleaner, and the framing is consistent.

It looks like a designed component, not just an uploaded image.

4. Responsive Project Images

In my project grid, the source images came from different industries — fashion, e-commerce, outdoor photography — all with different aspect ratios.

Here’s one of the original images:

https://res.cloudinary.com/demo/image/upload/woman_mountain_ledge.jpg

And here’s the version used in the grid:

https://res.cloudinary.com/demo/image/upload/c_fill,g_auto,h_400,w_600/r_20/e_saturation:20/f_auto/q_auto/woman_mountain_ledge.jpg

What the Transformation Does

c_fill,h_400,w_600 forces a consistent 600×400 frame.
g_auto intelligently selects the focal area.
r_20 adds rounded corners.
e_saturation:20 slightly boosts color.
f_auto,q_auto optimize delivery.

The original image has its own natural proportions.

The transformed version guarantees:

Every card in the grid is exactly the same size.
No distortion.
No manual cropping.
No awkward whitespace.

Even though the source images vary wildly, the layout stays predictable and clean. That’s what makes the grid feel cohesive.

5. Video Transformations That Actually Work

Video is usually where portfolios fall apart. Files are large, aspect ratios are inconsistent, and playback isn’t optimized.

Here’s the original full video:

Your browser does not support the video tag.

https://res.cloudinary.com/demo/video/upload/v1731855790/guy_woman_mobile.mp4

And here’s the version used in the portfolio:

Your browser does not support the video tag.

https://res.cloudinary.com/demo/video/upload/so_0.5,eo_2.5/c_pad,h_400,w_600/b_rgb:d4a520/v1731855790/guy_woman_mobile.mp4

What the Transformation Does

so_0.5,eo_3 trims the clip to a specific segment.
c_pad,h_400,w_600 fits it into a 600×400 frame without cutting off content.
b_rgb:d4a520 fills extra space with a consistent background color.
f_auto,q_auto optimize format and compression.

Instead of uploading a separately edited clip, I trim and resize at delivery time.

That means:

The video is shorter and lighter.
The layout dimensions are guaranteed.
There are no black bars.
The browser gets the best possible format automatically.

It behaves like a designed component — not a raw media file dropped onto a page.

6. Small Details That Make a Difference

Once layout and performance were handled, I added subtle refinements.

Here’s the original image:

https://res.cloudinary.com/demo/image/upload/docs/profile-pic1.jpg

And here’s the polished version:

https://res.cloudinary.com/demo/image/upload/c_fill,g_auto,h_800,w_700/e_vignette:30/e_sharpen:100/r_20/bo_1px_solid_rgb:e0e0e0/f_auto/q_auto/docs/profile-pic1.jpg

What the Transformation Does

c_fill,g_auto enforces consistent framing.
e_vignette:30 darkens the edges slightly.
e_sharpen:100 restores clarity.
r_20 rounds the corners.
bo_1px_solid_rgb:e0e0e0 adds a subtle border.
f_auto,q_auto optimize delivery.

None of these effects are dramatic, but together they:

Improve edge definition.
Add separation from the background.
Standardize presentation across sections.
These are small adjustments, but they’re the difference between “image placed on a page” and “designed component.”

What This Means for Performance

You might be thinking, “All these effects must slow things down, right?” Actually, the opposite!

With Cloudinary:

70-80% smaller file sizes compared to unoptimized images.
3-5x faster loading thanks to automatic optimization.
Zero manual editing time.
Automatic device optimization — phone users get mobile-sized images, desktop users get high-res.

When someone views your portfolio on their phone, they automatically get perfectly-sized images. On a 4K monitor, they get crisp, detailed versions. It just works.

Notice how much this image was optimized and what that means for your website stats and loading time! Reduced from a 21.30 MB JPG to a 18.26 KB AVIF.

Bringing It Full Circle

Here’s what I love about this whole process: The skills you use to build an impressive portfolio are the same skills you’ll use every day in your job.

When you build this portfolio, you’re learning how to:

Build modern React applications with TypeScript.
Create responsive, mobile-first designs.
Optimize images and videos for real-world performance.
Use cloud services to solve practical problems.
Write clean, maintainable code.
Think about user experience.

Your portfolio becomes a preview of what you can do. So, you’ve shown you can build websites that look great, load fast, and feel professional. That’s exactly what teams are looking for.

Wrapping Up

Making a portfolio that stands out doesn’t have to be complicated or stressful. It’s really about:

Polish that shows you care about details.
Performance that respects people’s time.
Smart visual choices that guide the eye.
Responsive design that works everywhere.

Using the right tools (like Cloudinary) to make your life easier.
If you’re job searching right now, I hope this helps. You’ve got this.

Resources:

Live demo: https://stackblitz.com/github/cloudinary-devs/digital_portfolio?file=README.md
Source code: GitHub repository
Cloudinary docs: https://cloudinary.com/documentation

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

Your Images Are Probably Slowing Down Your Website (Here’s How to Fix It)

Jen Looper — Wed, 11 Mar 2026 18:43:45 +0000

Images often account for the majority of a webpage’s weight. Learn how developers can improve performance using modern image formats, responsive images, and smarter delivery strategies.

The hidden performance problem on most websites

Open Chrome DevTools on almost any modern site and check the Network tab.

What you’ll usually see is something surprising:

Images dominate the payload.

The average homepage ships around 1 MB of images, often more than JavaScript, CSS, and HTML combined.

A super heavy page with a lot of big product images. Lazy loading and optimization would help here.

That product page with 20 images?
Each one is an opportunity to either:

Deliver a fast, polished experience
Or frustrate users with slow loading and layout shifts

If you care about Core Web Vitals, SEO, and user experience, image optimization is one of the highest-impact improvements you can make.

This article was generated from our Cloud to Crowd: Media IQ with Next.js curriculum, built by Cloudinary Developer Relations. Go through this curriculum and pass the certification exam to qualify to become an official Cloudinary Creator!

Why images matter (and when they don’t)

Humans process images much faster than text.

A well-chosen image can:

Explain a product instantly
Replace paragraphs of documentation
Capture attention in fast-scrolling feeds

But images can also hurt your product experience when used poorly:

Too many images slow down page loads
Poor cropping hides important information
Large files damage Core Web Vitals
Undisclosed AI or edited images reduce user trust

So you need to follow this simple rule:

Right format + right size + smart delivery

Check out the way these images are delivered to the browser

Images and Core Web Vitals

Images heavily influence Google's Core Web Vitals, particularly:

Largest Contentful Paint (LCP)

Measures how long it takes for the largest visible element on the page to load.

This is often your hero image.

A good LCP target is under 2.5 seconds.

Cumulative Layout Shift (CLS)

Images without defined dimensions can cause layout shifts while loading.

Interaction to Next Paint (INP)

Heavy pages delay responsiveness.

Optimizing images can dramatically improve all three metrics.

The current state of images on the web

Nearly every webpage (99.9%) loads at least one image.

Average number of images per page:

Device	Avg Images
Desktop	14
Mobile	13

Common formats used across the web:

Format	Usage
JPEG	32.4%
PNG	28.4%
GIF	16.8%
WebP	12%
SVG	6.4%
AVIF	1%

But these numbers reflect habit, not best practices.

Performance-focused teams are already shifting toward modern formats.

Example data from optimized platforms shows:

Format	Usage
WebP	49.5%
JPEG	19.9%
AVIF	13.3%
HEIC / PNG	8.7%

The takeaway:

Modern image formats are replacing JPEG-first strategies.

Choosing the right image format

Different formats solve different problems.

Lossy compression

Reduces file size by permanently discarding some data.

Formats:

JPEG
WebP
AVIF

Pros:

Much smaller file sizes
Ideal for photos

Cons:

Slight quality loss

Lossless compression

Reduces size without losing data.

Formats:

Pros:

Perfect image quality
Ideal for UI graphics

Cons:

Larger file sizes

Check out the difference between a lower res image vs JPEG XL

Quick developer cheat sheet

Use case	Best format
Photos	WebP / AVIF
Graphics	PNG
Icons	SVG
Legacy fallback	JPEG

Modern formats like WebP and AVIF can reduce file size by 40–60% compared to JPEG while keeping similar visual quality.

Delivering images efficiently

Choosing the right format is only part of the story.
Delivery strategy matters just as much.

Guess what? Cloudinary takes the guesswork out of all of this by helping you optimize, transform and deliver images the right way for your users. Check out how on the Developers Hub.

1. Use responsive images

Don't force mobile users to download desktop-sized images.

Use srcset and <picture>:

<picture>
  <source srcset="hero.avif" type="image/avif">
  <source srcset="hero.webp" type="image/webp">
  <img src="hero.jpg" alt="Product hero image">
</picture>

The browser automatically chooses the best supported format and size.

2. Use a CDN

A Content Delivery Network (CDN) reduces the physical distance between your users and your images.

Modern image CDNs can also:

Resize images automatically
Convert formats (WebP / AVIF)
Adjust compression
Crop dynamically

This allows you to store one high-quality original while serving optimized versions.

3. Lazy-load images (strategically)

Lazy loading delays images until they approach the viewport.

Example:

<img src="gallery.jpg" loading="lazy" alt="Gallery image">

But there is one important rule:

⚠️ Never lazy-load above-the-fold images.

Doing so hurts Largest Contentful Paint.

Lazy loading should only be used for below-the-fold content.

Responsible image usage

Performance isn't the only consideration.

Developers should also use images ethically and accessibly.

1. Avoid misleading visuals

Don't use edited or cropped images that misrepresent a product.

2. Disclose AI-generated images

Transparency builds trust with users.
The banner at the top of this article was generated using Nano Banana.

3. Make images accessible

Always include descriptive alt text.

<img src="dashboard.png" alt="Analytics dashboard showing user growth trends">

4. Respect privacy and licensing

Check image licenses
Get consent when photographing people
Remove sensitive EXIF metadata

5. Balance aesthetics and performance

A beautiful image that takes 8 seconds to load isn't beautiful.

It's broken.

Common image optimization myths

“A CDN replaces responsive images”

False.

Responsive images help the browser choose the correct size, while CDNs deliver optimized assets.

You need both.

“More images mean more engagement”

Not necessarily.

Images should help users make decisions, not clutter the interface.

Three practical tips for developers

1. Start with your largest image

Open DevTools → Network and find the biggest image.

Check if delivered size == display size.

A common mistake: 3000px image displayed in a 600px container.

That’s wasted bandwidth.

2. Measure your format mix

Check what formats your pipeline actually delivers.

If you're still mostly serving JPEG, there's likely a huge optimization opportunity.

3. Don’t assume mobile is optimized

Mobile networks amplify performance problems.

Check your 75th and 90th percentile metrics, not just averages.

Try this: Analyze a website’s image performance

You can test any website using Cloudinary’s Web Speed Test.

Visit https://webspeedtest.cloudinary.com

Then analyze:

Performance score
Total image weight
Largest Contentful Paint
Potential size reductions

You'll often discover massive performance gains from simple fixes.

Final thoughts

Images are often the largest performance lever on a webpage.

If you remember only three things:

1️⃣ Optimize your largest image first
2️⃣ Use modern formats like WebP and AVIF
3️⃣ Deliver responsive images with proper sizing

Small improvements in image delivery can produce huge gains in performance and user experience.

What’s the biggest image optimization issue you’ve found on a website?

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

Meet the Cloudinary Creators Community: A New Space for Developers Building with Media

eugene musebe — Mon, 23 Feb 2026 14:13:47 +0000

The wait is finally over! We’re honored and excited to pull back the curtain on a project that has been fueling our passion for months: the Cloudinary Creators Community (CCC).

At Cloudinary, we know that the leap from finishing a coding tutorial to landing your dream role can feel like a massive chasm. That’s why we created the CCC. We aren't just building a community; we’re building a bridge to help you cross that gap and step into your future as a leader in the tech industry.

The Vision: ‘From Cloud to Crowd’

Our mission is captured in four simple words: from Cloud to Crowd,a phrase coined by one of our community members, Jerome Hardaway.

This program is specifically designed for the dreamers and the doers, the early-career developers, the brave career-changers, and the media-savvy creators who are ready to shape the future of the visual web. Whether you're just starting to understand how images and videos power the internet or you're already building complex apps, we’re here to empower you with the tools, mentorship, and global network you need to grow from a learner into a recognized Cloudinary Creator.

At the heart of everything we do are our three core values:

Learn. Master the fundamentals of modern media management and high-performance web development through structured, accessible education.
Build. Turn that knowledge into action! We provide the platform for you to ship real-world projects that make your portfolio shine.
Connect. Join a vibrant, global ecosystem of peers and industry experts who are all rooting for your success.

We believe that when you combine the right tools with a supportive community, there’s no limit to what you can create. Ready to see how we’re making it happen?

Phase 1: Education

Joining the Community: Two Pathways

We want to make sure the CCC is accessible while maintaining the high-quality mentorship that makes this program special. There are two exciting ways to join us:

The Partner Pathway

We’re incredibly proud to launch in collaboration with global nonprofits that are changing the face of tech. If you’re a member of GirlScript, Developers in Vogue, Vets Who Code, Hack Your Future, or Tampa Devs, you have a direct seat at the table! We work closely with these organizations to provide dedicated spots for their communities.

The Individual Pathway

Are you an independent builder ready to level up? You can join, too! Simply dive into our "Cloud to Crowd" course at the Cloudinary Academy. Once you’ve mastered the material and passed the exam, you can submit an application to join our priority waitlist for the next available cohort.

Because we keep our cohorts selective to ensure everyone gets the support they need, these spots are highly coveted, so bring your A-game!

Phase 2: Activation

Discord: Our Digital Headquarters

Discord is where Phase 2 happens. Once inside, you get access to private channels, technical support, and our Developer Relations staff. To keep the community vibrant, we have a 30-day rule: New members must introduce themselves within their first month to keep their seat. You have 14 days to accept your invitation. We also monitor activity. After 60 days of silence, your status becomes inactive, and after 90 days, your spot is released to a new learner on the waitlist. This ensures our headquarters is full of creators ready to ship.

Selectivity and Waitlist Management

To guarantee quality mentorship, we limit active seats. This keeps our environment high-performing and focused. We operate on a bi-annual model with two intake cycles. If seats are full, you’ll join our priority waitlist. We monitor activity closely and invite waitlisted learners as spots open, ensuring every creator gets the support they deserve. Even if you’re not yet onboarded as an official Cloudinary Creator, however, please join us on Discord to engage with the community and participate in our fun activities such as hackathons and challenges.

Membership Benefits and Rewards

Your growth is rewarded at every stage. As a recognized creator, you gain access to a toolkit designed to power your professional portfolio.

The journey includes a one-year renewable Ambassador Plan to ensure your personal projects perform at their best. We also celebrate your milestones with exclusive digital badges via Holopin, giving you a way to showcase your education and project achievements to your network.

Beyond the tech, you’ll join an ecosystem built on mentorship. This includes dedicated office hours for technical Q&A, tailored career advice, and networking opportunities within the broader Cloudinary partner network. And to welcome you properly, once you’ve made your first meaningful engagement on Discord, we’ll ship the official CCC Swag Pack directly to your door.

The Engagement Path (12 Points/Year)

We value builders over observers. To keep your creator status active, we use a simple point system with a goal of 12 points per year.

You earn 5 points for shipping a project and 3 for joining a mini-community hackathon. Attending events earns you 2 points, while smaller acts like helping a peer solve a bug or joining a weekly standup earn 1 point. This path ensures our creators stay sharp, connected, and consistently moving forward.

Community Life and Activities

The activation phase is where the energy truly shifts. We keep the momentum high with hackathons and mini challenges designed to test your skills and reward your creativity with exciting prizes.

Our regular Demo Days give you a global stage to showcase your projects to the community and beyond. To track your progress, we use gamification through leaderboards and badges to celebrate our most active contributors. When you need help or career advice, our live office hours provide direct access to the experts who can help you solve technical challenges and plan your next big move.

Professionalism and Governance

A community this vibrant thrives on respect. Our Code of Conduct ensures that every member feels included and supported as they grow. We prioritize kindness and helpfulness, creating a professional network where everyone can advance their career safely.

This is a long-term partnership. To renew your spot each year, we look for continued growth through new project submissions and engagement with your peers. Staying connected means dropping into Discord at least once every 60 days to share your progress.

We’re ready to build the future of the visual web with you. Visit our Community page to find your path and start your journey from learner to creator today. Let's go!

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

DRY January: Demotivational Posters with the TanStack or Next.js

Jen Looper — Mon, 26 Jan 2026 18:18:58 +0000

January can be a time when we make all the resolutions to do and be better in the shiny new year. We resolve to do more... more exercise, a more rigorous diet, even more mindfulness, doggone it. But what if we (and hear me out) instead thought about doing LESS. Less struggling against those 4PM sugar cravings, less fighting to not take an after-lunch nap, less battling frozen driveways to back the car out so you can make it to pilates.

I don't know if this is creepy or inspiring, but let's build it anyway

What if we embraced our inner zen and simply...did the best we could? After all, isn’t all the productivity that AI is bestowing upon us freeing up our time to do less, rather than more? I’m only half-kidding here.

To encourage us to embrace a reductionist mentality, I did a little experiment to see if I could rethink some popular messaging that I’m sure you encountered if you ever worked in an American corporate office in the early 2000s: motivational posters.

These little gems were plastered on the walls to exhort us to Bring Our Best Selves To Work, Achieve More, and Be Bold. Here’s an example from the “Successories” company:

As you can see, they have a particular format of a black background, an inspiring photo, an uplifting word with a lot of kerning, and a blurb at the bottom to drive the message home. A Whole Vibe was created as you walked down a poster-adorned corridor in order to toss your bag lunch into the office fridge.

I particularly like this wolf. This is me.

Even back in those days, people made fun of these posters, and I remember being employed in one company packed with sarcastic Eastern Europeans that was instead decorated with demotivational posters such as those crafted by the brilliant Despair.inc. Here’s a good one:

The problem with all of these posters is that, well, you have to buy them, and that’s no fun. So let’s see if we can build something like this ourselves, and actually make it a more surprising experience by connecting two APIs to generate shady messaging like this at random.

not sure what 'this' is, but you got it!

Temporarily shelve that resolution against unproductive and negative thinking and let’s see what we can build using:

The Affirmations API
Unsplash API
TanStack for a web frontend
Cloudinary image storage to display the image so you can print off a PDF of your poster

You'll need two API keys, one for the ever-useful affirmations.dev API and one for Unsplash images. You'll also need a Cloudinary account, so create one for free here if you aren't already setup. You then need to gather your Cloudinary API key, secret, cloud name and build an upload preset so that you can upload images neatly into Cloudinary. Learn how to get credentials here and how to create an upload preset here.

We’re going to grab one of the pithy affirmations from the API, extract the longest word as the central message to display with plenty of kerning, and then send that word to Unsplash to find a match. Store the image returned in Cloudinary and display the lot a as a printable poster, as a stacked image, word, and affirmation on a black background, like this one:

The miracle of survival

Continuing my tradition of building useless things to try new stacks, let’s give TANStack a whirl. TanStack is a React framework that's pitched as a less 'magical' alternative to Next.js. I also built this same app using Next.js, to compare the two codebases, for learning purposes. Check out the GitHub repo with the two apps here

Disclosure; I used Cursor to help build the two comparable apps in the demo repo. According to Cursor, the difference between the two boils down to your personal dev preference: "Next.js is a full-stack framework with conventions and a large ecosystem. TanStack Router/Start is a type-safe, flexible routing solution that can be extended to full-stack. The choice often comes down to preferring conventions (Next.js) vs. flexibility and type safety (TanStack)."

Some differences between these two frameworks in the context of this app include:

Server-side data fetching architecture

Next.js:

Uses Server Actions ('use server') and async Server Components
Server actions in actions.ts are callable from both server and client TanStack:
Uses route loaders and createServerFn for server functions
Data fetching happens in the route's loader function
Loaders run on the server before the component renders

Environment variable access

Next.js:

Uses process.env.* for environment variables
Variables are available on the server by default TanStack:
Uses import.meta.env.VITE_* (Vite convention)
Only variables prefixed with VITE_ are exposed to the client buildCloudinaryUrl.ts, because this app was built with Vite as its build tool.

Difference in image handling

Next.js:

Images are displayed using the built-in optimized component TanStack:
TanStack doesn't have such a component built-in, so you need to make sure to optimize your images! This is consistent with its 'magic-free' approach.

Guess what! You can easily optimize your images in Cloudinary. While there are other ways to do this, I decided to just add some URL transformations to the Cloudinary URL returned once the Unsplash image is uploaded:

export function buildCloudinaryImageUrl(publicId: string): string {
  const cloudName = import.meta.env.VITE_CLOUDINARY_CLOUD_NAME

  if (!cloudName) {
    throw new Error('Cloudinary cloud name not configured')
  }

  const plainPublicId = publicId

  const transformations = [
    `c_fill,w_1200,h_800`, // Fill to 1200x800 for poster feel
    `f_auto`, // Auto format
    `q_auto`, // Auto quality
  ].join('/')

  // Return the complete Cloudinary URL with transformations `https://res.cloudinary.com/${cloudName}/image/upload/${transformations}/${plainPublicId}`
}

Now you're able to grab an affirmation from the API and use it to query Unsplash, storing the result into Cloudinary and using it to build your poster. In TANStack it looks like this:

export const fetchNewAffirmationData = createServerFn({
  method: 'GET',
}).handler(async (): Promise<AffirmationData> => {
  // First fetch the affirmation
  const affirmationData = await getAffirmation()

  // Extract the longest word from the affirmation to use as image search query
  const words = affirmationData.affirmation.split(' ').filter(word => word.length > 0)
  const longestWord = words.reduce((longest, current) => 
    current.length > longest.length ? current : longest, ''
  ).toLowerCase()

  // Fetch an image based on the longest word
  const accessKey = import.meta.env.VITE_UNSPLASH_ACCESS_KEY
  if (!accessKey) {
    throw new Error('Unsplash access key not configured')
  }

  const unsplashResponse = await fetch(
    `https://api.unsplash.com/photos/random?client_id=${accessKey}&orientation=landscape&query=${encodeURIComponent(longestWord)}`
  )
  if (!unsplashResponse.ok) {
    throw new Error('Failed to fetch Unsplash photo')
  }
  const unsplashData = await unsplashResponse.json() as { id: string; urls: { full: string } }

  // Upload the Unsplash image to Cloudinary
  const publicId = await uploadToCloudinary(unsplashData.urls.full)

  // Build the Cloudinary URL with transformations
  const cloudinaryUrl = buildCloudinaryImageUrl(publicId)

  return {
    affirmation: affirmationData.affirmation,
    longestWord,
    cloudinaryUrl,
    photoId: unsplashData.id,
    publicId,
  }
})

And once you have all your pieces in place, you'll be able to view that matching affirmation, image, and printable styling all in one place so you can build a PDF poster:

const handlePrint = () => {
    if (posterRef.current) {
      const printWindow = window.open('', '_blank')
      if (printWindow) {
        printWindow.document.write(`
          <!DOCTYPE html>
          <html>
            <head>
              <title>Affirmation Poster</title>
              <style>
                ...some fancy styling
              </style>
            </head>
            <body>
              <div class="poster-container">
                <img src="${imageUrl}" alt="${affirmation}" class="poster-image" />
                <h1>${longestWordWithDots}</h1>
                <div class="poster-line"></div>
                <h2>${affirmation}</h2>
              </div>
            </body>
          </html>
        `)
        printWindow.document.close()

        // Wait for image to load before printing
        setTimeout(() => {
          printWindow.focus()
          printWindow.print()
          printWindow.onafterprint = () => printWindow.close()
        }, 250)
      }
    }
  }

So there you have it...you've built a delightfully useless little app that combines a few API calls with optimized image presentation to make you feel a little less seasonally-affected, we hope.

Happy New Year! If you liked this little app, there are plenty more where it comes from from your friends at Cloudinary Developer Relations.

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

Hacktoberfest as a First-Time Maintainer

Eric Portis — Fri, 19 Dec 2025 20:02:29 +0000

Earlier this year, I took over maintenance duties on Cloudinary's Community Libraries. Fast forward a few months, and my team was gearing up to participate in Digital Ocean's annual Hacktoberfest.

Reader, I was worried.

I was still very much familiarizing myself with how the libraries worked, and trying to wrap my head around their issue backlogs. And while I'd never participated in a Hacktoberfest in any capacity before, I had read some scary things from other maintainers, who complained of an annual avalanche of spam.

What’s worse than an avalanche? A turbo-avalanche powered by the recent explosion of AI-powered coding tools. As September drew to a close, I imagined hundreds of AI-written PRs coming in, each hundreds of lines long, all based on prompts that poorly understood the underlying issues, containing code that the submitters themselves didn't understand, but which we would be expected to review.

The good news: It wasn't that bad. While the underlying incentive structures of Hacktoberfest did generate some spam, and while almost all of that spam smelled like AI, our team was able to get ahead of many problems with strong policies, and would have been able to prevent many more with a bit of additional preparation and planning.

The worst PRs were about as bad as I expected, but there weren't as many of them as I'd feared, and the best PRs were actually, dare I say, really good? Hackathon participants tackled some of the issues I'd been putting off addressing for months, helping me push the libraries forward.

All in all, while participation as a maintainer did take a lot of time (and we're in active discussions about whether or not we want to participate next year), it also provided some tangible value, without overwhelming us. And hopefully it helped some folks get more comfortable with the mechanics of open source along the way.

If you're thinking about participating as a maintainer in years to come, read on to learn about what worked for us — and what didn't.

Narrowing Scope

The best decision we made was to limit participation to fixes for a specific set of existing issues, which we identified with a Hacktoberfest tag. This addressed a few issues:

We had a clear mandate to quickly close any drive-by, low-value PRs (e.g. "improve docs").
We could spend our time during Hacktoberfest reviewing PRs rather than trying to reproduce new issues or define new features.
We could further limit contributions to issues whose fixes would be reasonably straightforward, allowing for quick reviews.

It was a good theory! In practice, we applied the Hacktoberfest tag fairly liberally, and did spend some time reproducing issues, specifying new features, and reviewing complex PRs. This led to a lot of work and some very long review delays.

We weren't stingy enough with the tag because we set a goal for how many contributions we wanted to accept by the end of the month, up front, and tagged that many issues, rather than seeing how many issues were going to be a good fit for Hacktoberfest first, and using that number to set the goal.

We had good reasons to set a number ahead of time. For one, it's always good to define a success metric up front so that you can quantify (and communicate) success or failure; we set the quota based on the number of successful submissions that we received in 2024?utm_source=dev-dot-to&utm_content=hacktoberfest2025). For two, we were offering our own swag (a plushie Cloudinary unicorn) to contributors of accepted PRs, and it's best to know how many of those you're going to need well ahead of time.

The end result, though, was a Hacktoberfest tag on a number of issues that I only poorly or vaguely understood, which came back to bite us later.

Knowing that we had a quota to hit did motivate me to do one good thing; I did a full docs review and identified and filed a handful of minor issues, which would be easy to fix and review. It would have been much (much!) faster to fix these myself, as soon as I identified them, but:

I wouldn't have done the docs review without Hacktoberfest.
One of the best things Hacktoberfest does is invite people who are new to open source to learn the mechanics of it. In some ways, it doesn't matter what the contributions are, as long as new contributors are "getting their feet wet" forking, committing, PRing, and responding to feedback.

So, the stage was set. As October came around, the PRs started to come in.

Hacktoberfest Begins

Most of the PRs we received for the month came in during the first week. People were also very good at identifying which issues would be easiest to fix. All of my "easy" issues were taken off of the board immediately. We received a number of the predicted nonsensical drive-bys that were easy to close, but after that, it was time to chew through dozens of substantive PRs.

It wasn't long before I started to regret that we'd applied the tag to some poorly defined and understood issues. The most embarrassing of these was: Someone submitted a "fix" for an issue, but their changes seemed unrelated to the problem at hand. Turns out, the issue had already been fixed a year ago, as part of a much broader update, but the issue was never closed. My guess at what happened is that the submitter fed the issue into Cursor, which, being asked to solve a solved problem, did its best.

It was clear that many submissions were created with the help of AI. It was also clear — both in the initial PRs that came in and in the reviews and discussions that followed — that the humans behind these submissions had varying levels of understanding of what they were trying to accomplish, and how their PRs were accomplishing it. The more understanding they had, the better things went. A number of follow-up conversations — where we tried to clarify the issue or suggest possible alternate paths forward — went nowhere, leading to closed PRs and wasted time on both sides.

However, the quality of the highest-quality submissions was well beyond my expectations. A handful of contributors clearly understood the underlying frameworks better than I do, and took the time to suggest thoughtful solutions to nuanced problems that we hadn't yet been able to tackle. I'm extremely grateful for their time and effort, which was worth far more than a unicorn plushie and a Digital Ocean T-shirt.

Overwhelmed, but Just a Little

Because a number of the issues turned out to be rather thorny (and because I and the other technical reviewers had more to do in October than review Hacktoberfest PRs), review times stretched to weeks, which I know was frustrating for contributors. In a couple of cases, we were not able to either accept or reject PRs before the November 15 deadline. We sent those contributors a unicorn anyway, but if the real purpose of Hacktoberfest is to familiarize folks with the mechanics of open source, learning that things are surprisingly complicated and your code might never land isn't a great lesson. Again, I wish we'd been a little more careful about which issues we invited people to solve.

Worth It?

From Cloudinary's side, it's hard to measure the value of a thing like Hacktoberfest. Our community library docs are in better shape now, and dozens of small fixes that would have been easy to put off have now been done. In addition, we made real progress on a handful of meaty issues that I'd been putting off tackling for months. And, hopefully, the participants are more familiar with Cloudinary and our SDKs, and are more likely to use us as they continue to build and grow their careers.

At the same time, the slow (and in a couple of cases, unresolved) reviews may have had the opposite effect, driving participants away. And the cost in time to Cloudinary was real, as we prioritized Hacktoberfest work over other projects in October and November.

Personally, I'm definitely glad I did it, once. Whether we as a company decide to do it again next year remains to be seen.

Happy hacking!

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

Build Holiday Card Collages with One Line of Code

Jen Looper — Thu, 04 Dec 2025 14:48:59 +0000

In this article, I'm not going to show you much code. Instead, I'm going to show you how you can build a holiday card collage, complete with a ribbon footer with text, a background, and 5 styled photos with rounded, colored borders in one line using the magic of Cloudinary's transformations.

This is way cool, so buckle up and let me show you how I built this URL-generating app for your holiday card-sending needs. You can try it right now here; it generates cards that look like this:

Maybe this tool will even save you some money as printing photo-quality holiday cards can get expensive!

Build an app, any app

I have been enjoying building Astro apps, and, let's face it, using Cursor makes architecting this sort of thing a real breeze. Use your favorite AI tool to craft an app that will allow you to upload five photos to Cloudinary, rearrange them, and generate a URL to build the holiday card.

💡 Here's a tip. If you are looking to quickly scaffold an app via prompting in Cursor or your IDE of choice, you can get better results by using two tools: ChatGPT to build the prompt, and Cursor to execute it.

My initial lazy half-baked idea sent over to ChatGPT:

what kind of demo could I build to create a holiday photo card maker for cloudinary

ChatGPT, of course, thought I wanted it to build an app for me, and went straight to scaffolding a Next.js app with code everywhere. A few clarifications later, after requesting Astro for use in Cursor...

create this as a prompt I can give to cursor

...ChatGPT generated a really nice, detailed prompt ready for building which you can read in full here

By having this kind of very detailed prompt, Cursor is able to build a perfectly reasonable app on the first try. Then it's up to the engineer to tweak it, redesign it, and add elements while keeping the core functionality of uploading and URL-building intact.

Add some extras and get ready to upload

I went ahead and changed the app colors for a wintry, cozy look, adding some falling snow, a popup elf with changing holiday messages (can you find him?), glowing lights, and a candy cane border, mostly borrowed from CodePen. Just because we use AI doesn't mean we can't continue to make interesting interfaces! And AI can help you do that, too.

After those fun things are complete, you can start making sure that you're set up to use Cloudinary's image upload and image transformation capabilities. To make this work, you need to ensure that you have some environment variables set up. Create an account on Cloudinary (there's a generous free tier) and grab your API keys from the console by clicking the "⚙️" gear icon in the left nav and selecting 'API Keys':

You want to add those keys to your .env file locally, and then make sure they're available on your hosting service when you push your app to the cloud. I use Netlify so I add these keys into the Netlify console before publishing.

PUBLIC_CLOUDINARY_CLOUD_NAME=<your cloud name>
PUBLIC_CLOUDINARY_UPLOAD_PRESET=christmas-collage

This app also needs what's called an 'Upload Preset', which is essentially a placeholder that helps your app figure out where your uploaded images should go.

Set up that preset by clicking the 'Uploads' navigation link that's right under the 'API Keys' navigation on the left. This will let you set up an unsigned preset.
Call it 'christmas-collage' (or something else, and make sure to update your app).

Make sure you have a folder set up by clicking Assets > folders on the left nav in the Cloudinary console. Call this folder 'collages'.
Also create a folder called 'holiday-assets' and add a collage background image and a background image for your ribbon element on the card. I used a white pixel image and a fancy holiday background like this:

Photo by JESHOOTS.COM on Unsplash

Watch the URL builder work

Now here's the interesting bit. Once you're done messing with your interface to make it look cute, take a look at the very clever way that your card is generated. First, you upload a series of 5 photos of your family to the app, and the interface lets you rearrange them into the order in the card that you want.

True story, my daughter asked me what the difference is between this and PicCollage, the answer being "Mom made it!"

The URL that is generated, packed with Cloudinary image transformations, looks something like this:

https://res.cloudinary.com/jen-demos/image/upload/w_1600,h_900,c_fill,q_auto,f_auto
/l_holiday-assets:jhi9cpio4ahxomhagwvs/c_fill,w_473,h_680/r_25,bo_8px_solid_rgb:FFD700/fl_layer_apply,g_north_west,x_50,y_50
/l_holiday-assets:d9njoekpa1zzzepy2y5d/c_fill,w_473,h_426/r_25,bo_8px_solid_rgb:FFD700/fl_layer_apply,g_north_west,x_563,y_50
/l_holiday-assets:nm9i3sjh6c3mkfj0ari1/c_fill,w_473,h_214/r_25,bo_8px_solid_rgb:FFD700/fl_layer_apply,g_north_west,x_563,y_516
/l_holiday-assets:rg0c1ul7ux1gcgl8c2lr/c_fill,w_473,h_214/r_25,bo_8px_solid_rgb:FFD700/fl_layer_apply,g_north_west,x_1076,y_50
/l_holiday-assets:d0brmcfuqfyzwtelsiyt/c_fill,w_473,h_426/r_25,bo_8px_solid_rgb:FFD700/fl_layer_apply,g_north_west,x_1076,y_304
/l_holiday-assets:white-pixel/c_fill,w_1600,h_100/o_70/fl_layer_apply,g_south,y_20
/l_text:Pacifico_70:Our%20Family%20-%20Holiday%202025,co_rgb:000000/fl_layer_apply,g_center,y_380
/holiday-assets/collage-bg

Yes, that one line created this card:

Let's break down that one-liner.

Step 1: Set up the base “card” background:

.../image/upload/w_1600,h_900,c_fill,q_auto,f_auto/ ... /holiday-assets/collage-bg

w_1600,h_900 – make the final image 1600×900.
c_fill – crop/resize to fill that aspect ratio.
q_auto,f_auto – optimize quality and format automatically (WebP/AVIF/etc).
holiday-assets/collage-bg – this is the base background image for the card.

Step 2: Add the first photo (top left)

/l_holiday-assets:uzfzkx8d5xd0jr1jxzyo/c_fill,w_473,h_680
/r_25,bo_8px_solid_rgb:FFD700/fl_layer_apply,g_north_west,x_50,y_50

l_holiday-assets:... – load this image as a layer.
c_fill,w_473,h_680 – size it to 473×680, cropping to fill.
r_25 – rounded corners (radius 25).
bo_8px_solid_rgb:FFD700 – 8px solid gold (#FFD700) border.
fl_layer_apply,g_north_west,x_50,y_50 – apply the layer at the top-left, offset 50px from the top and left.

Add the remaining images, some taller than others and placed in different areas of the card.

Step 3: Add a semi-transparent footer bar

/l_holiday-assets:white-pixel/c_fill,w_1600,h_100/o_70
/fl_layer_apply,g_south,y_20

This bar uses a white-pixel asset as a tiny base and stretches it to w_1600,h_100 to form a strip which is o_70 – 70% opacity (semi-transparent). It's then applied at the bottom (g_south) with a small vertical offset (y_20).

Step 4: Finally, add the holiday greeting text

/l_text:Pacifico_70:Our%20Family%20-%20Holiday%202025,co_rgb:000000
/fl_layer_apply,g_center,y_380

l_text:Pacifico_70:... – create a text layer with Font: Pacifico in size: 70. Give it the text: Our Family - Holiday 2025 with co_rgb:000000 – black text color.
fl_layer_apply,g_center,y_380 – center the text horizontally and shift it vertically to overlay the footer.

In short, this monster URL

starts with a festive background
lays out five photos in a collage with rounded corners and gold frames
adds a semi-transparent white bar at the bottom
and writes “Our Family - Holiday 2025” in a script font on top of that bar

...rendering the whole card on demand in a single Cloudinary transformation URL. Really nice!

Tip: you can make edits right in the URL to change elements on the card - try adding your own family name and changing the border color.

Enjoy the results

You could save this image and print it for snail mail, or send it right away via email to the folks who are eager to hear from you this holiday season. And you did it in one line. That's awesome!

Try this in Cloudinary today, and get one more item checked off your holiday to-do list. Learn more about image transformations here.

Happy holidays from Cloudinary Developer Relations to you.

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

Building a Fashion App Using Cloudinary’s GenAI in React and Node.js

Pato — Thu, 06 Nov 2025 01:30:09 +0000

Upload a picture → get four styled looks (elegant, streetwear, sporty, business casual). In this walkthrough we’ll build FashionistaAI with Cloudinary GenAI, React (Vite) on the frontend, and a tiny Node.js/Express backend for secure uploads.

Repo: Cloudinary-FashionistaAI

What you’ll build

A React app that:
- uploads an image to your Node backend
- asks Cloudinary GenAI to swap tops/bottoms
- replaces the background
- lets you recolor top or bottom on click
A Node.js server that securely uploads files to Cloudinary using the official SDK.

Demo (what it looks like)

The background adapts to the look; each tile is a different style:

Elegant

Streetwear

Sporty

Business casual

Prerequisites

Node 18+ and npm
A free Cloudinary account

GenAI features may need to be enabled depending on your plan.

Basic React/TypeScript familiarity (optional but helpful)

1) Set up Cloudinary

Create/Login → Settings → Product Environments.
Confirm your Cloud name (keep it consistent across tools).
Settings → Product Environments → API Keys → Generate New API Key. Save: Cloud name, API key, API secret (secret stays on the server).

2) Bootstrap the React app (Vite)

# Create a Vite + React + TS app
npm create vite@latest fashionistaai -- --template react-ts
cd fashionistaai

# Frontend deps
npm i axios @cloudinary/react @cloudinary/url-gen

# Dev tooling
npm i -D @vitejs/plugin-react

# Backend deps (we'll use one package.json for both)
npm i express cors cloudinary multer streamifier dotenv

# Nice-to-have dev deps
npm i -D nodemon concurrently

3) Configure Vite dev proxy (frontend → backend)

Create/replace vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true,
        secure: false,
      },
    },
  },
})

This forwards any /api/* calls to the Express server on port 8000.

4) Environment variables

Create .env in the project root:

# Server (Node) reads these:
CLOUDINARY_CLOUD_NAME=YOUR_CLOUD_NAME
CLOUDINARY_API_KEY=YOUR_API_KEY
CLOUDINARY_API_SECRET=YOUR_API_SECRET

# Frontend (Vite) reads those prefixed with VITE_
VITE_CLOUDINARY_CLOUD_NAME=YOUR_CLOUD_NAME

Never expose CLOUDINARY_API_SECRET on the frontend. That’s why we’re using a server.

5) Node/Express backend (`server.js`)

Create server.js in the project root. You can find the complete server file here.

Let's explain the main parts of the server.js file.

cloudinary.config({
  secure: true,
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
})

This is the part responsible for connecting your server to your Cloudinary account by pulling your credentials from .env.

const storage = multer.memoryStorage()
const upload = multer({
  storage,
  limits: { fileSize: 10 * 1024 * 1024 }, // 10MB
  fileFilter: (_req, file, cb) => {
    const ok = /image\/(png|jpe?g|webp)/i.test(file.mimetype)
    cb(ok ? null : new Error('Only PNG/JPG/WEBP images are allowed'), ok)
  },
})

Remember the npm dependency multer we installed? Time to put it to work! Multer stores uploaded files in memory, not on disk which means is faster & simpler. Limits uploads to 10MB and only accepts PNG, JPG, WEBP images.

Why in memory?

Because Cloudinary works great with streams, no need to save files to disk!

const uploadStream = cloudinary.uploader.upload_stream(
  { resource_type: 'image' },
  (error, result) => {
    if (error) {
      console.error('Cloudinary error:', error)
      return res.status(500).json({ error: error.message })
    }
    res.json(result)
  }
)

streamifier.createReadStream(req.file.buffer).pipe(uploadStream)

Let's talk about uploading images to the Cloudinary using the NodeJS SDK.

The Cloudinary NodeJS SDK expects either a file path or a stream. Since multer stored the image in memory, we convert the buffer to a readable stream then we pipe the stream directly into Cloudinary’s upload_stream(). When Cloudinary finishes, it calls the callback, and we return the Cloudinary result to the frontend.

package.json scripts

Open package.json and add these scripts:

{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "server": "nodemon server.js",
    "start:both": "concurrently -k \"npm:server\" \"npm:dev\""
  }
}

Now you can run both servers with:

npm run start:both

(Or use two terminals: npm run server and npm run dev.)

6) React UI (`src/App.tsx`)

Below is a drop‑in, TypeScript friendly version that keeps your original logic but tightens types, separates file vs. Cloudinary images, and reads the cloud name from env. You can find the complete code for the App.tsx here.

Now, let's dive into the UI code!

Creating the clothing styles

type StyleKey = 'top' | 'bottom'
type StyleConfig = {
  top: string
  bottom: string
  background: string
  type: string
}

const STYLES: StyleConfig[] = [
  { top: 'suit jacket for upper body', bottom: 'suit pants for lower body', background: 'office', type: 'business casual' },
  { top: 'sport tshirt for upper body', bottom: 'sport shorts for lower body', background: 'gym', type: 'sporty' },
  { top: 'streetwear shirt for upper body', bottom: 'streetwear pants for lower body', background: 'street', type: 'streetwear' },
  { top: 'elegant tuxedo for upper body', bottom: 'elegant tuxedo pants for lower body', background: 'gala', type: 'elegant' },
]

The StyleKey type indicates whether the user is recoloring the top or bottom of an outfit, while StyleConfig represents a complete look, including the top, bottom, background, and a human-readable label. The STYLES array acts as a preset wardrobe: each entry specifies what clothing should replace the user’s upper and lower garments, the general background aesthetic for the image, and the style’s name. Each of these presets becomes one of the “cards” displayed in the grid, such as Business Casual, Sporty, Streetwear, or Elegant.

Submitting to the Backend and Getting the Base Image

  async function handleSubmit() {
    setError(null)
    setLooks([])
    setLoadingStatus([])
    if (!file) return

    try {
      setLoading(true)
      const data = new FormData()
      data.append('image', file)

      const resp = await axios.post('/api/generate', data, {
        headers: { 'Content-Type': 'multipart/form-data' },
      })

      const publicId = resp.data.public_id as string
      const base = cld.image(publicId).resize(fill().width(508).height(508))
      setBaseImg(base)
      createLooks(publicId)
    } catch (err: any) {
      console.error(err)
      setError(err?.message ?? 'Upload failed')
    } finally {
      setLoading(false)
    }
  }

When the user submits an image, the function begins by clearing any previous errors and removing any previously generated looks. It then builds a FormData object containing the uploaded image and sends it via a POST request to the /api/generate endpoint you created earlier. The backend uploads this file to Cloudinary and returns Cloudinary’s full response, including the crucial public_id. Once the upload succeeds, the frontend creates a new CloudinaryImage based on that ID, resizes it to 508×508 for consistent display, and stores it in baseImg. With the base image ready, the function then calls createLooks(publicId) to generate all of the AI-styled outfit variations

Preloading Derived Images (Poll Until Ready)

  function preload(img: CloudinaryImage, index: number, attempts = 0) {
    const url = img.toURL()
    const tag = new Image()
    tag.onload = () =>
      setLoadingStatus(prev => {
        const copy = [...prev]
        copy[index] = false
        return copy
      })
    tag.onerror = async () => {
      // 423 means "still deriving" on Cloudinary
      try {
        const r = await fetch(url, { method: 'HEAD' })
        if (r.status === 423 && attempts < 6) {
          setTimeout(() => preload(img, index, attempts + 1), 2000 * (attempts + 1))
          return
        }
      } catch {}
      setError('Error loading image. Please try again.')
      setLoadingStatus(prev => {
        const copy = [...prev]
        copy[index] = false
        return copy
      })
    }
    tag.src = url
  }

The preload function works by converting a CloudinaryImage into a URL and creating a temporary Image() object to load it in the background. If the image loads successfully, it marks that particular look as finished by updating loadingStatus[index] to false. If the load fails, the function sends a HEAD request to check whether Cloudinary is still generating the derived asset, indicated by a 423 status code. When this happens—and as long as the maximum number of attempts hasn’t been reached—it retries after an increasing delay. If the error persists for reasons other than derivation, the function sets an error message and stops retrying.

Creating the Different Looks (Generative Effects)

  function createLooks(publicId: string) {
    const imgs = STYLES.map(style => {
      const i = cld.image(publicId)
      i.effect(generativeReplace().from('shirt').to(style.top))
      i.effect(generativeReplace().from('pants').to(style.bottom))
      i.effect(generativeBackgroundReplace()) // optional: prompt with your background
      i.effect(generativeRestore())
      i.resize(fill().width(500).height(500))
      return i
    })
    setLooks(imgs)
    setLoadingStatus(imgs.map(() => true))
    imgs.forEach((img, idx) => preload(img, idx))
  }

To generate each outfit variation, the app creates a new CloudinaryImage from the same publicId and applies a series of generative effects: it replaces the shirt with the style’s top, swaps the pants for the style’s bottom, updates the background, and restores the image to remove artifacts. After resizing the result, the image is added to the looks array and marked as loading. The app then calls preload() on each look to determine when Cloudinary has finished processing it. This is the step where the “magic wardrobe” is created, turning a single uploaded image into multiple styled variations.

Example:

It replaces the shirt with the style's designated top using generativeReplace().from('shirt').to(style.top) and swaps the pants for the appropriate bottom using generativeReplace().from('pants').to(style.bottom), allowing prompts like “suit jacket for upper body” or “tuxedo pants” to transform the clothing.

Recolor Modal Logic

  function openRecolorModal(index: number) {
    setSelectedLookIndex(index)
    setOpenModal(true)
  }

  function applyRecolor() {
    const clone = [...looks]
    const img = clone[selectedLookIndex]
    if (!img) return
    setLoadingStatus(prev => {
      const copy = [...prev]
      copy[selectedLookIndex] = true
      return copy
    })
    setOpenModal(false)
    // Recolor only the chosen item for the chosen look
    img.effect(generativeRecolor(STYLES[selectedLookIndex][selectedItem], color))
    setLooks(clone)
    preload(img, selectedLookIndex)
  }

Recoloring works by letting the user click any generated look, which opens a modal and stores the index of the selected outfit. Inside the modal, the user chooses whether to recolor the top or bottom and picks a new color. When they confirm, applyRecolor() marks that look as loading again, applies a new generativeRecolor() transformation using the appropriate prompt and selected hex value, updates the looks array, and triggers preload() to wait for Cloudinary to finish generating the updated image. In essence, the app layers an additional AI transformation on top of an already styled outfit.

Add some love to your app by adding our css or your own.

7) How it works (quick tour)

Upload: The file is sent to POST /api/generate. The server uses cloudinary.uploader.upload_stream to store it and returns the public_id.
Transform:
- generativeReplace().from('shirt').to(style.top)
- generativeReplace().from('pants').to(style.bottom)
- generativeBackgroundReplace() (optionally prompt it to steer the scene)
- generativeRestore() for quality
Recolor: On a generated tile, open a modal and apply generativeRecolor(<item>, <hex>).
423 handling: When the first request for a derived image hits Cloudinary while it’s still being generated, you might see HTTP 423. The preload helper retries with backoff; for heavy use, consider preparing eager transformations on upload.

8) Testing locally

# Install (already done if you followed along)
npm i

# Run both servers
npm run start:both
# Frontend: http://localhost:3000
# Backend:  http://localhost:8000

Production notes (optional but recommended)

Secrets: Keep CLOUDINARY_API_SECRET server‑side only; use environment vars on your host.
Upload presets: Lock down transformations and content rules with a Cloudinary upload preset.
Limits: Add rate limiting to your API if you open it to the public.
Validation: Keep the Multer fileFilter and limits in place; consider scanning/validating uploads.
Caching/CDN: Cloudinary URLs are CDN‑backed; reusing the same public_id improves cache hits.
Accessibility: Provide helpful alt text for generated images (the example includes captions).

Wrap‑up

FashionistaAI shows how a small React app plus Cloudinary’s GenAI can turn one image into four on‑brand looks with background changes and easy recoloring. Fork it, tweak the prompts, and ship your own AI‑powered try‑on experience.

If you build something with this, drop a link—DEV readers will want to see it!

Hacktoberfest 2025: Open Source Celebration With Cloudinary

Pato — Fri, 10 Oct 2025 17:54:57 +0000

Hacktoberfest is back for 2025 — and Cloudinary is joining the celebration! 🎉
We’re excited to recognize the power of open source and the developers who keep the community thriving.

This year, we’ve opened up a wide range of SDKs and issues ready for your contributions. Whether you’re fixing bugs, improving docs, or building new features, your pull requests help make Cloudinary better for everyone.

And yes — there’s swag. 👕

🌟 What’s Hacktoberfest?

Hacktoberfest is a month-long celebration of open source that happens every October. It’s a chance for developers around the world to contribute to projects, grow their skills, and earn recognition (and sometimes prizes!) for their pull requests.

While the official Hacktoberfest program now offers digital badges, Cloudinary is keeping the swag tradition alive.
Make a valid contribution to any of our participating repositories and you could snag one of 30 exclusive Cloudinary swag packs, featuring:

🦄 A limited-edition 2025 Hacktoberfest T-shirt
✨ Custom Cloudinary stickers
🦄 The fan-favorite Cloudinary unicorn plushie

🧩 How You Can Contribute

We’re opening up several SDKs and community projects for Hacktoberfest participants.

Official SDKs

Community SDKs

👉 To confirm a repo is part of the event, look for the “Hacktoberfest” label in the repository.

📜 Contribution Rules

We love all contributions, but only those following the rules below qualify for swag:

❌ No spammy or low-effort PRs.
❌ No typo-only fixes.
❌ Don’t submit PRs without approved issues.
❌ Don’t take over issues already assigned to others.
✅ Do have fun and collaborate!

Also, please ensure your code passes tests and follows project guidelines. Each repo includes detailed Contributing instructions.

⚠️ Cloudinary reserves the right to withhold swag for contributions that don’t meet these standards or the spirit of Hacktoberfest.

🎁 What’s in the Swag Pack?

This year’s Cloudinary Hacktoberfest kit includes:

1 × Cloudinary Hacktoberfest T-shirt (Limited Edition)
2 × Cloudinary Hacktoberfest Stickers (Limited Edition)
3 × Classic Cloudinary Stickers
1 × Cloudinary Unicorn Plushie

🕒 Only 30 swag packs are available — first-come, first-served!

❓ Frequently Asked Questions

🌍 Where do you ship?
We’ll ship worldwide where possible (excluding sanctioned countries). Some locations, like Brazil, may require a Tax ID.

📦 How do I share my address?
Once your PR is merged, we’ll send you a form to collect shipping details. Please double-check your address — we’ll ship it exactly as you submit it.

🧑‍🤝‍🧑 Can I get more than one swag pack?
No — one per person.

⏰ When do I need to submit my PR?
All valid pull requests must be submitted during October 2025. Even if we merge it later, it still counts as long as it’s submitted this month.

🚀 Join Us!

Ready to make your mark in open source?
Head over to one of our Cloudinary open-source repositories and start contributing today.

Together, let’s make Hacktoberfest 2025 one to remember — with great code, great community, and great swag. 💙

Cloudinary Transformations, But Make It a Mystery Adventure - meet Clara Denari!

Jen Looper — Tue, 30 Sep 2025 20:51:16 +0000

Tired of plowing through blogs and scanning through video to learn? Done with 🔥Tutorial Hell🔥? Want to get hands on quickly to explore a toolset? Looking to spice up your world with a little mystery?

Have we got an experience for you.

Introducing a new heroine for the ages: Clara Denari, Master Detective. Join her as she prowls through Boston, recovering stolen property by solving the mysteries left by the nefarious Dr. Chiaro Obscuro.

This villain, who is both a meticulous kleptomaniac AND someone with considerable long-term memory issues, has done it again. His habit is to hide his ill-gotten gains in obscure places, leaving a trail of clues that only he will understand. This time he’s stolen something valuable and has hidden it...but where?

It’s up to Clara to save the day. By deciphering each clue, she may be able to find the stolen property...but it’s up to you to help her!

Start your adventure here!

Follow the trail in the story, picking up objects and storing them in inventory. Use Cloudinary transformations to clean a piece of string, brighten an image to reveal hidden text, use image refiners to tidy up lost keys, and discover the secret hiding place of the lost treasure. You’ll even be able to view clues by digging into Content Credentials, which allow you to view an image’s history as it undergoes changes through its lifecycle:

Content Credentialing using C2PA standards

You’ll be able to solve the mystery only by getting hands-on with Cloudinary’s powerful image transformations - try them out yourself by creating a free account at cloudinary.com. Solve all 5 challenges and arrive at your destination, key in hand.

As you progress, you’ll complete labs to work with the clues scattered through Boston. Add your cloud name and the public ID of the image in the Lab to experiment with different transformations that will help you solve the clue.

Clara's Lab

Préférez-vous le français ? ¿Qué tal el español? Português brasileiro? We have you covered, as the app is fully localized to four languages. Speaking of local, this first edition Clara Denari Adventure features the gritty underside of Boston, USA, cannoli and all. If you’d like Clara to come to your city to solve a mystery, just say the word!

Because this app is a true learning experience, it features both short embedded quizzes to test your knowledge. Pass the quiz and earn a custom Holopin, showing your own detective mastery on your favorite social media channels.

Earn your limited edition Holopin!

Ready? Have your trench coat ready and your magnifying glasses polished? Join us on the inaugural Clara Denari Adventure, new from your friends in Developer Relations at Cloudinary.

Click here to start.

"It is a happy talent to know how to play.“ - Ralph Waldo Emerson, American writer, 1803–1882

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account

Build a Docs‑Aware Chatbot with React, Vite, Node, and OpenAI (plus fun DALL·E avatars)

Pato — Wed, 17 Sep 2025 17:57:11 +0000

What you’ll build

A chat UI that streams answers from your own examples/context
A Node/Express API that calls OpenAI for text and image generation
Two cute, auto‑generated avatars (user & assistant)

Demo question shown here: “How do I use the Cloudinary React SDK?”

Repo (reference): Cloudinary-Chatbot-OpenAI-Demo

Prereqs

Node 18+
An OpenAI API key stored server‑side (never in the browser). How to create/manage keys: see the official docs. (OpenAI Platform)

1) Create the React app (Vite)

# New project
npm create vite@latest cloudinary-chatbot -- --template react
cd cloudinary-chatbot
npm i

Vite proxy (avoid CORS while developing)

vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:6000',
        changeOrigin: true,
        secure: false,
      },
    },
  },
})

Chatbot UI

Create a src/App.jsx file. You can file the full code of this file in the repo.

The Chat functionality

  const sendMessage = async () => {
    if (!inputMessage.trim()) return;
    const newMessages = [...messages, { role: "user", content: inputMessage.trim() }];
    setMessages(newMessages);
    setInputMessage("");
    setStatus("loading");

    try {
      const res = await fetch("/api/chat", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ messages: newMessages }),
      });
      const data = await res.json();
      setMessages([...newMessages, { role: "assistant", content: data.content }]);
    } catch (e) {
      setMessages([...newMessages, { role: "assistant", content: "Server error. Try again." }]);
    } finally {
      setStatus("idle");
    }
  };

This function sends the user’s message to the backend and updates the chat UI. It first adds the user’s message to the conversation, clears the input, and sets a loading state. Then it POSTs the full message history to /api/chat and appends the assistant’s reply when the server responds. If the request fails, it adds an error message instead. Finally, it resets the status to idle.

Generating avatars

  useEffect(() => {
    const makeAvatars = async () => {
      try {
        const res = await fetch("/api/avatar", { method: "POST" });
        const data = await res.json(); // [{url}, {url}]
        setUserImage(data[0].url);
        setAssistantImage(data[1].url);
      } catch {
        // silently ignore; UI still works without avatars
      }
    };
    makeAvatars();
  }, []);

To make a more realistic chatBot, we are going to generate 2 avatars. In our backend, we have the endpoint /api/avatar. We call that endpoint, and we assign the avatars one for the user and one for the bot/assistant.

Add your own CSS or use our existing App.css.

2) Add the backend (Express + OpenAI)

Inside the project root, create a folder named backend and a file server.js. We’ll reuse the root package.json for simplicity.

Install deps

npm i express dotenv openai
# optional: nodemon for dev
npm i -D nodemon

Environment variables

Create .env in the project root:

OPENAI_API_KEY=sk-...

Server code (Responses API + Images API)

Why Responses API? It’s the recommended, modern way to generate text and stream outputs going forward; if you’re coming from Chat Completions, see the official migration guide. (OpenAI Platform)
Why SDK over raw fetch? Cleaner code, types, and built‑ins for images. (OpenAI Platform). You can find the full code to the backend in the repo.

backend/server.js

Training the chatBot

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const demoModel = [
  {
    role: "user",
    content: "Where is the Cloudinary React SDK documentation?"
  },
  {
    role: "assistant",
    content: "See: https://cloudinary.com/documentation/react_integration"
  },
  {
    role: "user",
    content: "Where can I read about Cloudinary image transformations in React?"
  },
  {
    role: "assistant",
    content: "See: https://cloudinary.com/documentation/react_image_transformations"
  },
  {
    role: "user",
    content: "How do I display an image using the Cloudinary React SDK?"
  },
  {
    role: "assistant",
    content:
`Use @cloudinary/react and @cloudinary/url-gen. Example:

import { AdvancedImage } from '@cloudinary/react';
import { Cloudinary } from '@cloudinary/url-gen';
import { sepia } from '@cloudinary/url-gen/actions/effect';

const cld = new Cloudinary({ cloud: { cloudName: 'demo' } });
const img = cld.image('front_face').effect(sepia());

<AdvancedImage cldImg={img} />`
  }
];

This code initializes the OpenAI client on the server using an API key from environment variables, ensuring all AI calls are authenticated. It also defines a demoModel array containing a series of example question-and-answer pairs. These serve as “conversation seeds” that help guide the AI toward Cloudinary-specific knowledge by showing it how the assistant should respond. Each entry mimics a real chat message, with a role (user or assistant) and content. Together, these samples act as contextual training data, steering the model to provide accurate Cloudinary documentation links and example React code when similar questions are asked.

Creating the chatBot with OpenAI

app.post("/api/chat", async (req, res) => {
  try {
    const { messages = [] } = req.body;

    // System prompt keeps the bot scoped to your docs
    const system = {
      role: "system",
      content:
        "You are a helpful developer docs assistant. Prefer official Cloudinary docs. Include links when helpful."
    };

    const input = [system, ...demoModel, ...messages]
      .map(m => ({ role: m.role, content: m.content }));

    const r = await openai.responses.create({
      model: "gpt-4o-mini",
      input
    });

    // Convenience: return plain text
    res.json({ content: r.output_text });
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: "Internal Server Error" });
  }
});

This endpoint takes the user’s chat messages, prepends a system prompt, and mixes in example Q&A pairs to guide the model toward Cloudinary-focused answers. It sends this combined conversation to OpenAI using the gpt-4o-mini model, then returns the assistant’s plain-text reply to the client. If an error occurs, it logs the issue and responds with a 500 error.

Creating the Avatars with DALL-E

app.post("/api/avatar", async (_req, res) => {
  try {
    const r = await openai.images.generate({
      model: "gpt-image-1",
      prompt:
        "minimal, cute round animal avatar on flat background, high contrast, centered, no text",
      n: 2,
      size: "256x256"
    });

    // Return {url} objects for the UI
    res.json(r.data.map(d => ({ url: d.url })));
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: "Internal Server Error" });
  }
});

This endpoint generates simple AI-created avatars. When called, it sends a prompt to OpenAI’s image generation model (gpt-image-1) requesting two minimal, cute, round animal avatars at 256×256 resolution. The OpenAI API returns image objects containing URLs, which the server maps into a clean { url } format for the frontend. If generation fails, the server logs the error and responds with a 500 status code.

Responses API reference (Node): see Responses docs. (OpenAI Platform)
Images API reference: see Images docs. (OpenAI Platform)

3) Dev scripts

Add these to your root package.json:

{
  "scripts": {
    "dev": "vite",
    "server": "node backend/server.js",
    "server:dev": "nodemon backend/server.js"
  }
}

4) Run it

# terminal 1
npm run server:dev

# terminal 2
npm run dev
# open http://localhost:3000

Type:
“How do I use the Cloudinary React SDK?”
You should get a helpful, linked answer pulled in the spirit of your seed examples.

Production notes (important)

Never expose your API key in client code or public repos. Use env vars and a server. (OpenAI Platform)
Prefer Responses API for new builds and streaming; see migration notes if you used Chat Completions before. (OpenAI Platform)
If you want retrieval over your actual docs (beyond hardcoded examples), look at the Assistants API with tools or Retrieval. (OpenAI Platform)

Wrap‑up

You now have a lightweight, dev‑friendly chatbot that answers from your docs and greets users with generated avatars. From here you can:

Swap the seed examples for real retrieval.
Add streaming UI for token‑by‑token responses. (OpenAI Platform)
Validate outputs with structured JSON. (OpenAI Platform)

Further reading:

OpenAI Quickstart (Node) (OpenAI Platform)
Responses API (text generation) (OpenAI Platform)
Images API (generation & sizes) (OpenAI Platform)

Repo: Cloudinary-Chatbot-OpenAI-Demo

Cloudinary ❤️ developers
Ready to level up your media workflow? Start using Cloudinary for free and build better visual experiences today.
👉 Create your free account