@rikology/adonisjs-cloudinary

Cloudinary integration for AdonisJS v7 — upload, transform, and deliver media through the Cloudinary v2 SDK, with first-class IoC container support, Edge templating helpers, and an optional FlyDrive bridge.

Features

• 🚀 Typed service wrapping the Cloudinary v2 SDK, injectable anywhere via the IoC container
• 📸 Upload helpers for images, video, and raw files with a single call
• 🎨 URL transformations generated synchronously, including in Edge templates
• 🔐 Signed/expiring URLs with Date or Unix-timestamp expiration
• 🗄️ Optional FlyDrive bridge to use Cloudinary as a Drive disk
• 🧩 Zero-config Edge helper that registers itself when Edge is installed (and stays out of the way in API-only apps)
• 📦 Standalone helpers for scripts, workers, and non-AdonisJS projects
• 🩺 cloudinary:ping ace command to verify your credentials right after install

Documentation

| Topic | Document | | --- | --- | | Install, configure, first upload | Getting Started | | defineConfig, config types, container binding | Configuration | | Full CloudinaryService method reference | Service API | | The cloudinaryUrl Edge global | Edge Helpers | | Using Cloudinary as a FlyDrive disk | Drive Bridge | | Scripts, workers, non-AdonisJS usage | Standalone Helpers | | Raw SDK, Admin/Search API, presets, multi-account | Advanced | | Avatars, galleries, signed URLs, cleanup | Recipes |

Installation

node ace add @rikology/adonisjs-cloudinary

That single command installs the package, publishes config/cloudinary.ts, registers the CloudinaryProvider and the cloudinary:* ace commands in adonisrc.ts, and wires env validation for your CLOUDINARY_* keys.

Prefer the manual route?

# install
npm install @rikology/adonisjs-cloudinary # or: pnpm/yarn/bun add

# then configure
node ace configure @rikology/adonisjs-cloudinary

Verify your credentials are wired up:

node ace cloudinary:ping

Environment variables

Add these to your .env (values from the Cloudinary console):

| Variable | Required | Description | | ----------------------- | -------- | -------------------------- | | CLOUDINARY_CLOUD_NAME | Yes | Your Cloudinary cloud name | | CLOUDINARY_API_KEY | Yes | Your Cloudinary API key | | CLOUDINARY_API_SECRET | Yes | Your Cloudinary API secret |

node ace add / configure auto-registers these in your env validator (start/env.ts). The entry it adds looks like:

import { Env } from '@adonisjs/core/env'

export default await Env.create(new URL('../', import.meta.url), {
  CLOUDINARY_CLOUD_NAME: Env.schema.string(),
  CLOUDINARY_API_KEY: Env.schema.string(),
  CLOUDINARY_API_SECRET: Env.schema.string(),
})

Quick start

Inject the service and upload:

import { inject } from '@adonisjs/core'
import type { CloudinaryService } from '@rikology/adonisjs-cloudinary'

@inject()
export default class UploadsController {
  constructor(protected cloudinary: CloudinaryService) {}

  async store({ request, response }) {
    const file = request.file('avatar')!

    const result = await this.cloudinary.uploadImage(file.tmpPath!, {
      folder: 'avatars',
      transformation: { width: 200, height: 200, crop: 'fill' },
    })

    return response.ok({ url: result.secure_url, publicId: result.public_id })
  }
}

Render a transformed URL in Edge (the cloudinaryUrl global registers itself automatically):

<img
  src="{{ cloudinaryUrl('avatars/photo', { width: 200, height: 200, crop: 'fill' }) }}"
  alt="Avatar"
/>

Service API (summary)

The CloudinaryService is bound to the container as cloudinary. Full reference: Service API.

| Method | Description | | ------------------------------------------ | ----------------------------------------------------- | | sdk | Raw cloudinary v2 object for direct SDK calls | | uploadImage(file, options?) | Upload with resource_type: 'image' | | uploadVideo(file, options?) | Upload with resource_type: 'video' | | uploadFile(file, options?) | Upload with resource_type: 'raw' | | transformUrl(publicId, transformations?) | Generate a delivery URL with optional transformations | | signedUrl(publicId, options?) | Generate a signed URL, optionally with expiresAt | | uploadStream(options?) | Return a cloudinary.uploader.upload_stream() stream | | destroy(publicId, options?) | Delete an asset (defaults resource_type: 'image') |

// Signed URL expiring in 1 hour
const url = cloudinary.signedUrl('private-doc', {
  expiresAt: Date.now() / 1000 + 3600,
})

For scripts and workers without the container:

import { createCloudinaryService, transformUrl } from '@rikology/adonisjs-cloudinary'

const cloudinary = createCloudinaryService({
  cloudName: 'demo',
  apiKey: '123456',
  apiSecret: 'secret',
})

const url = transformUrl('my-image', { cloudName: 'demo', apiKey: 'k', apiSecret: 's' }, { width: 200 })

See Standalone Helpers.

Drive bridge

An optional FlyDrive driver maps Drive operations onto Cloudinary API calls. It's imported from the /drive subpath so it never loads unless you use it:

import { CloudinaryDrive } from '@rikology/adonisjs-cloudinary/drive'
import { createCloudinaryService } from '@rikology/adonisjs-cloudinary'

const cloudinary = createCloudinaryService({
  cloudName: env.get('CLOUDINARY_CLOUD_NAME'),
  apiKey: env.get('CLOUDINARY_API_KEY'),
  apiSecret: env.get('CLOUDINARY_API_SECRET'),
})

const driveConfig = defineConfig({
  default: 'cloudinary',
  services: {
    cloudinary: () => new CloudinaryDrive(cloudinary),
  },
})

Requires the optional flydrive (or @adonisjs/drive) peer dependency. Cloudinary is a media platform, not a byte-level object store — see the Drive Bridge guide for supported/unsupported operations.

Advanced

Need something the wrappers don't cover? The raw SDK is one property away:

const cloudinary = await app.container.make('cloudinary')

// Admin API
await cloudinary.sdk.api.resources({ type: 'upload', prefix: 'avatars/', max_results: 50 })

// Search API
await cloudinary.sdk.search
  .expression('resource_type:image AND tags=featured')
  .sort_by('created_at', 'desc')
  .max_results(30)
  .execute()

// Upload presets
await cloudinary.sdk.uploader.upload(file, { upload_preset: 'my-preset' })

See Advanced for Admin/Search API patterns, upload presets, multi-account strategies, and testing.

Contributing

See CONTRIBUTING.md. Contributions, issues, and feature requests are welcome.

License

MIT © Riko Riswandha Fahmi Prasetyo