Cloudinary

Cloudinary is a cloud-based media management platform. It handles storing, transforming, optimizing, and delivering images and videos. StackKit generates a complete media upload module for your Express API, including routes, a controller, and configuration.

Compatible frameworks

Cloudinary is available for Express projects only.

Installation

In a new project

npx stackkit@latest create my-api --framework express --storage-provider cloudinary

In an existing project

npx stackkit@latest add
# Navigate to: Storage → Cloudinary

What gets generated

• src/config/cloudinary.ts — Cloudinary SDK configuration using your credentials from environment variables.
• src/modules/media/media.controller.ts — Controller with an upload handler that accepts a file and returns the Cloudinary URL.
• src/modules/media/media.routes.ts — Express routes for the media upload endpoint (POST /api/media/upload).

Setup

cp .env.example .env

CLOUDINARY_CLOUD_NAME="your_cloud_name"
CLOUDINARY_API_KEY="your_api_key"
CLOUDINARY_API_SECRET="your_api_secret"

npm run dev

Using the upload endpoint

Send a multipart/form-data request to upload a file:

curl -X POST http://localhost:3000/api/media/upload \
  -F "file=@/path/to/your/image.png"

The response includes the Cloudinary URL and other metadata:

{
  "url": "https://res.cloudinary.com/your-cloud/image/upload/v1234567890/sample.png",
  "public_id": "sample",
  "format": "png",
  "width": 800,
  "height": 600
}

Customizing uploads

Edit src/config/cloudinary.ts to set default upload options:

import { v2 as cloudinary } from "cloudinary";

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

export default cloudinary;

And edit the controller to apply transformations, set a folder, restrict file types, and more. See the Cloudinary Upload API docs for all options.

Next steps

• Troubleshooting — Common issues