Cloudinary Next

Purpose

next-cloudinary

Core workflow

1. Classify the user's goal before writing code:
   • render a transformed Cloudinary image in JSX
   • generate a Cloudinary URL string
   • embed a video player
   • upload from the browser
   • perform a signed upload
   • upload from the server
   • delete an asset
   • build an overlay or text overlay
   • generate an OG/social image
   • fix TypeScript, environment, import, runtime, or upload errors
   • review an existing implementation
2. Load the relevant reference file from the map below.
3. Apply the non-negotiable rules in this

   SKILL.md

   before using any detailed reference.
4. For code review or debugging, load

   references/troubleshooting.md

   plus the task-specific reference.
5. When a detail is version-sensitive or not covered here, consult the official documentation linked in

   references/official-docs.md

   and prefer official prop names and event names over memory.

Non-negotiable rules

• Use

  next-cloudinary

  for Next.js components and URL helpers:

  CldImage

  ,

  CldVideoPlayer

  ,

  CldUploadWidget

  ,

  CldUploadButton

  ,

  CldOgImage

  ,

  getCldImageUrl

  ,

  getCldOgImageUrl

  , and

  getCldVideoUrl

  .
• Use the Cloudinary Node SDK v2 only for server-side operations:

  import { v2 as cloudinary } from 'cloudinary'

  .
• Never expose

  CLOUDINARY_API_SECRET

  to the browser. Never create

  NEXT_PUBLIC_CLOUDINARY_API_SECRET

  .
• Put upload widgets, video player UI, and any component with React event handlers behind a Client Component boundary with

  'use client'

  .

• CldImage

  may be used from a Server Component for static rendering, but if you add client-only props such as

  onLoad

  or local state, move it into a Client Component.
• Do not import

  cloudinary

  in Client Components or Edge runtime code. Server Actions and route handlers that import

  cloudinary

  must run on the Node.js runtime.
• Use documented

  next-cloudinary

  prop names and shapes. Do not infer prop names from Cloudinary URL transformation parameters.
• Use

  onSuccess

  for upload widget success handling. Do not use deprecated upload callback names unless the installed version explicitly documents them.
• For deletes, pass a public ID, not a delivery URL. Pass

  resource_type

  when deleting videos or raw assets, and use

  invalidate: true

  when CDN cache invalidation is desired.

Reference map

• references/official-docs.md

  — official documentation links and the global prop-name rule.

• references/api-decision-tree.md

  — choose the correct Cloudinary API/component/helper for a user goal.

• references/project-setup.md

  — install packages, configure Next.js image domains, configure upload presets, and create starter setup files.

• references/environment.md

  — environment variables and TypeScript process env typing.

• references/imports.md

  — correct import paths and server/client boundaries.

• references/cldimage.md

  —

  CldImage

  , sample assets, and

  getCldImageUrl

  usage.

• references/cldimage-transformations.md

  — transformation props, generative editing, optimization, raw transformations, and crop traps.

• references/responsive-images.md

  — responsive image sizing and

  sizes

  guidance.

• references/video-player.md

  —

  CldVideoPlayer

  , required CSS, and client-only player setup.

• references/upload-widget.md

  — browser uploads, upload widget/button usage, events, and signed-vs-unsigned tradeoffs.

• references/signed-uploads.md

  — App Router signature endpoint pattern.

• references/server-upload-delete.md

  — Server Action and route-handler upload/delete patterns with the Node SDK v2.

• references/overlays.md

  — image overlays and text overlay prop shapes.

• references/og-images.md

  — App Router and Pages Router OG/social card patterns.

• references/typescript.md

  — upload result narrowing, server upload result types, refs, and avoiding

  any

  .

• references/troubleshooting.md

  — common error messages and fixes.

• references/quick-checklist.md

  — final code-review checklist and best practices.

Output expectations

assets/app-router-signature-route.ts

assets/server-action-upload.ts

assets/server-action-delete.ts