---
name: bijection-cloudinary
description: "Evaluate and integrate the Cloudinary component with Bijection."
---

# Cloudinary

Image upload and transformations

- Package: @bijectionhq/cloudinary
- Category: Media
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/cloudinary/tree/3897f008668b38b4326b484a2ef2789f4b2c05ed
- Upstream: https://github.com/imaxisXD/cloudinary-convex/tree/937e5977fd2bdc0dbdf1a83b24653caa118ad42c
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/cloudinary

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/cloudinary.git
cd cloudinary
git checkout 3897f008668b38b4326b484a2ef2789f4b2c05ed
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @imaxis/cloudinary-convex. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Cloudinary

## Instructions

This component integrates Cloudinary's image management APIs directly into Convex, providing both base64 uploads for small files and direct uploads that bypass Convex's 16MB limit for large files up to 100MB. It automatically tracks assets in your Convex database with optimized indexes, generates secure upload signatures server-side, and provides full TypeScript support with exported validators. The component offers both a high-level `makeCloudinaryAPI` approach for React apps and a lower-level `CloudinaryClient` for custom server logic.

### Installation

```bash
npm install @imaxis/cloudinary-convex
```

## Use cases

• Building a photo sharing app where users upload high-resolution images that exceed typical serverless limits
• Creating a content management system that needs real-time asset tracking synchronized between Cloudinary and your database
• Implementing dynamic image transformations with type-safe parameters for e-commerce product galleries
• Building an admin dashboard that requires secure server-side image uploads with progress tracking
• Developing a social media platform where you need both small profile pictures and large media uploads

## How it works

The component provides two main integration patterns: `makeCloudinaryAPI` creates public functions in your Convex app that React clients can call directly, while `CloudinaryClient` gives you fine-grained control within Convex actions and queries. For uploads, it supports both base64 encoding for files under 10MB and direct uploads to Cloudinary that bypass Convex entirely for larger files.

Asset metadata gets automatically stored in Convex with optimized indexes, allowing you to use `useQuery` for real-time asset lists and management. The component includes React hooks like `useCloudinaryUpload` and `useCloudinaryImage` that work with your app's API functions, providing upload progress tracking and transformation capabilities.

Setup requires adding the component to your `convex.config.ts` with `app.use(cloudinary)` and configuring your Cloudinary credentials as environment variables. The component handles secure signature generation server-side and provides full TypeScript support with validators like `vAssetResponse` for type-safe data flow.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Cloudinary is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40imaxis%2Fcloudinary-convex)
- [GitHub repository](https://github.com/imaxisXD/cloudinary-convex)
- [Live demo](https://github.com/imaxisXD/cloudinary-convex-studio)
- [Convex Components Directory](https://www.convex.dev/components/imaxis/cloudinary-convex)
- [Convex documentation](https://docs.convex.dev)